Getting Started with the Mobile SDK

Every WelcomingWeb SDK follows the same three-step integration shape: configure, track your screens, and optionally add the in-app panel. The code is platform-native; the concepts, rules and dashboard are identical.

You need an API key from your WelcomingWeb dashboard. If you don’t have one yet, create a free account at welcomingweb.com and generate a key from Settings → API Keys.

Pick Your Platform

Full RN integration guide.

React Native

UIKit and SwiftUI integration.

iOS (Swift)

Views and Jetpack Compose.

Android (Kotlin)

Dart package for all Flutter targets.

Flutter

Three-Step Integration

Step 1: Install the Package

React Native


# npm
npm install @welcomingweb/react-native-sdk
 
# yarn
yarn add @welcomingweb/react-native-sdk

No pod install or gradle sync is required — the SDK uses only JavaScript APIs available in React Native core.

iOS

Add the package in Xcode via File → Add Packages…, or add the dependency directly in your Package.swift:

Package.swift


dependencies: [
  .package(url: "https://github.com/welcomingweb/ios-sdk.git", from: "1.0.0")
]

No CocoaPods entry, no bridging header, no script phases. The package imports URLSession, Foundation, UIKit and SwiftUI — all Apple-bundled.

Android

Add Maven Central to your root build.gradle (if not already there) and the SDK to your app module:

app/build.gradle


dependencies {
  implementation 'com.welcomingweb:sdk:1.0.0'
}

Compose support is a soft dependency (declared compileOnly), so apps that don’t use Compose carry zero runtime cost.

Flutter

Add the package to your pubspec.yaml:

pubspec.yaml


dependencies:
  welcomingweb_flutter_sdk: ^1.0.0

Then run:


flutter pub get

Step 2: Configure the SDK

Call configure() once at app startup, before any navigation renders.

React Native

App.tsx


import { WelcomingWeb } from '@welcomingweb/react-native-sdk';
 
WelcomingWeb.configure({
  apiKey: 'YOUR_API_KEY',
  appId: 'com.yourcompany.yourapp',
  appVersion: '1.0.0',
  environment: 'development',
  autoScan: true,
  debug: true,
});

iOS

AppDelegate.swift


import WelcomingWebSDK
 
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
  func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    WelcomingWeb.configure(
      WelcomingWebConfig(
        apiKey: "YOUR_API_KEY",
        appId: "com.yourcompany.yourapp",
        appVersion: "1.0.0",
        environment: .development,
        autoScan: true,
        debug: true
      )
    )
 
    // Install the global view-controller hook so every screen is tracked.
    ViewControllerSwizzler.installIfNeeded()
 
    return true
  }
}

Android

MyApplication.kt


import com.welcomingweb.sdk.WelcomingWeb
import com.welcomingweb.sdk.WelcomingWebConfig
import com.welcomingweb.sdk.Environment
 
class MyApplication : Application() {
  override fun onCreate() {
    super.onCreate()
 
    WelcomingWeb.configure(
      this,
      WelcomingWebConfig(
        apiKey = "YOUR_API_KEY",
        appId = "com.yourcompany.yourapp",
        appVersion = "1.0.0",
        environment = Environment.DEVELOPMENT,
        autoScan = true,
        debug = true
      )
    )
  }
}

Don’t forget to register your Application class in AndroidManifest.xml:

AndroidManifest.xml


<application
  android:name=".MyApplication"
  ...>
</application>

Flutter

main.dart


import 'package:flutter/material.dart';
import 'package:welcomingweb_flutter_sdk/welcomingweb_flutter_sdk.dart';
 
void main() {
  WelcomingWeb.configure(
    const WelcomingWebConfig(
      apiKey: 'YOUR_API_KEY',
      appId: 'com.yourcompany.yourapp',
      appVersion: '1.0.0',
      environment: Environment.development,
      autoScan: true,
      debug: true,
    ),
  );
 
  runApp(const MyApp());
}

For the full list of configuration options, see the configuration reference below.

Step 3: Track Your Screens

Each platform has its own idiomatic way to register screens for scanning.

React Native

Wrap each screen with the HOC, or use the hook in function components:

screens/HomeScreen.tsx


import { withAccessibilityTracking } from '@welcomingweb/react-native-sdk';
 
function HomeScreen() {
  return <ScrollView>{/* screen content */}</ScrollView>;
}
 
export default withAccessibilityTracking(HomeScreen, 'HomeScreen');

Or with the hook:


import { useAccessibilityTracking } from '@welcomingweb/react-native-sdk';
 
export default function ProductDetailScreen() {
  const a11yRef = useAccessibilityTracking('ProductDetailScreen');
  return <ScrollView ref={a11yRef}>{/* ... */}</ScrollView>;
}

iOS

With the swizzler installed (from Step 2), every UIViewController is tracked automatically using its class name or title. No per-screen code needed.

If you want a custom screen name or route, call ScreenTracker.trackScreen manually:


import WelcomingWebSDK
 
class HomeViewController: UIViewController {
  override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    ScreenTracker.trackScreen(self, name: "HomeScreen", route: "/home")
  }
}

For SwiftUI views, add the opt-in scan modifier to key interactive elements:


Button("Save") { save() }
  .welcomingWebScan(type: "Button", label: "Save", isInteractive: true)

Android

The easiest path is the automatic ActivityLifecycleHook, which registers every Activity and Fragment as it appears:

MyApplication.kt


override fun onCreate() {
  super.onCreate()
  WelcomingWeb.configure(this, config)
 
  // One line covers every Activity and Fragment in the app.
  ActivityLifecycleHook.install(this, trackFragments = true)
}

Using Jetpack Navigation? Wire the NavControllerHook from your Activity:


class MainActivity : AppCompatActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    val navController = findNavController(R.id.nav_host_fragment)
    NavControllerHook.install(this, navController)
  }
}

For Jetpack Compose, wrap screens with TrackAccessibility:


@Composable
fun HomeScreen() {
  TrackAccessibility(screenName = "HomeScreen") {
    // screen content
  }
}

Flutter

Wrap each screen with A11yTracker and register the navigator observer on MaterialApp:

main.dart


final a11yObserver = A11yNavigatorObserver();
 
MaterialApp(
  navigatorObservers: [a11yObserver],
  builder: (context, child) => A11yNavigatorObserverScope(
    observer: a11yObserver,
    child: child!,
  ),
  home: const HomeScreen(),
);

screens/home_screen.dart


class HomeScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return A11yTracker(
      screenName: 'HomeScreen',
      route: '/home',
      child: Scaffold(/* screen content */),
    );
  }
}

Step 4: (Optional) Add the Accessibility Panel

Give your end users an in-app panel for text size, contrast, reduce motion and more. See the Accessibility Panel guide for full setup on each platform.

Verify the Integration

Launch your app in development mode and navigate between screens. With debug: true set, you should see scan logs in your platform’s console (Metro console for RN, Xcode console for iOS, logcat for Android, flutter logs for Flutter):


[WelcomingWeb] Scanning screen: HomeScreen
[WelcomingWeb] Found 45 nodes, 8 interactive
[WelcomingWeb] Scan complete: 2 critical, 1 major, 0 minor — score 94.4
[WelcomingWeb:API] Response: 200

Open your WelcomingWeb dashboard to see the scan appear under your app’s session view.

Configuration Reference

All SDKs accept the same configuration options. Only apiKey and appId are required.

Option	Type	Default	Description
`apiKey`	string	(required)	Your WelcomingWeb API key.
`appId`	string	(required)	Unique app identifier, e.g. `com.company.app`.
`appVersion`	string	`null`	App version string. Sent with every scan.
`environment`	enum	`development`	Set to `production` to disable scanning unless `enableInProduction` is true.
`autoScan`	boolean	`true`	Scan automatically on screen changes. Set false for manual or CI scanning.
`scanDelay`	number (ms)	`600`	Milliseconds to wait after a screen change before scanning.
`debug`	boolean	`false`	Enable verbose console logging.
`reportingEndpoint`	string	`null`	Custom API endpoint URL. Overrides the default.
`enableInProduction`	boolean	`false`	Allow scanning in production builds.
`disabledRules`	string array	`[]`	Rule IDs to suppress globally. See rule reference.
`excludeScreens`	string array	`[]`	Screen names to never scan.
`maxStoredScans`	number	`50`	Maximum scan results kept in memory.
`onScanComplete`	function	`null`	Callback invoked after each scan with the full result.
`onIssueFound`	function	`null`	Callback invoked once per issue found during a scan.

Common Issues

⚠️

“Found 0 nodes” on scan — the screen may not have finished laying out when the scan fired. Increase scanDelay from 600 ms to 1200 ms for screens with complex or virtualised content. Platform-specific causes are covered on each platform page.

⚠️

Scans not firing on navigation — each SDK relies on its platform’s navigation primitive (useFocusEffect, RouteObserver, ActivityLifecycleCallbacks, viewDidAppear swizzling). See your platform page for the exact setup.

⚠️

Scans appear in debug logs but not on the dashboard — enable debug: true and check for [WelcomingWeb:API] Response: 200. If you see 401, verify apiKey. If you see 403 app_deactivated, the app is disabled on the backend. If you see 409 platform_mismatch, the app was registered under a different platform — re-register or contact support.

Next Steps

Detailed guides for React Native, iOS, Android and Flutter.

Platform-Specific Setup

Full reference for the eight WCAG 2.2 rules the SDK evaluates.

Accessibility Rules

Fail builds on accessibility issues with Detox, Maestro, Fastlane or GitHub Actions.

CI / CD Integration

Configure the in-app panel for text size, contrast, reduce motion and more.

Accessibility Panel