React Native

Ensure you have completed the Prerequisites section before continuing.

Requirements

• React Native: 0.74+
• Android: SDK 26+ (Android 8.0+)
• iOS: 13.0+
• Node.js: 16+

The SDK supports both the Old Architecture (bridge) and New Architecture (TurboModule) from a single install — no code changes or flags needed in your app.

note

This SDK uses native modules and is not compatible with Expo Go. If you're using Expo, use a development build.

Installation

If you're using npm:

npm install @dashx/react-native

If you're using yarn:

yarn add @dashx/react-native

Native setup (Push / FCM)

DashX push notifications are delivered via Firebase Cloud Messaging (FCM).

Android

1. Add the Google Services plugin in android/build.gradle:

buildscript {
  dependencies {
    // ...
    classpath 'com.google.gms:google-services:4.4.2'
  }
}

2. Apply the plugin in android/app/build.gradle:

apply plugin: 'com.google.gms.google-services'

3. Create/choose a Firebase project and add an Android app in the Firebase console.

4. Download google-services.json and place it at android/app/google-services.json.

note

On Android 13+, you must request the runtime notification permission (POST_NOTIFICATIONS) before notifications can be shown. The SDK declares this permission in its manifest and provides requestNotificationPermission() to prompt the user.

iOS

1. Add the DashX iOS SDK and Firebase Messaging to your ios/Podfile:

pod 'DashX', :git => 'https://github.com/dashxhq/dashx-ios.git', :tag => '1.1.9'
pod 'FirebaseMessaging', :modular_headers => true

note

The DashX iOS SDK is not published to CocoaPods trunk. You must add it from GitHub as shown above.

2. Install pods:

cd ios && pod install

3. Create/choose a Firebase project and add an iOS app in the Firebase console.

4. Download GoogleService-Info.plist and add it to your Xcode project (Copy items if needed). In the File Inspector, under Target Membership, enable your main iOS app target so the plist is bundled with the app (see Receive push notifications).

Wire up DashXNotificationHandler in your AppDelegate

The SDK ships a DashXNotificationHandler utility class with static methods you call from your own AppDelegate. This works with any AppDelegate — including Expo's ExpoAppDelegate.

import UIKit
import DashX
import FirebaseCore
import FirebaseMessaging

@main
class AppDelegate: UIResponder, UIApplicationDelegate, UNUserNotificationCenterDelegate, MessagingDelegate {

  var window: UIWindow?

  func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    FirebaseApp.configure()
    Messaging.messaging().delegate = self
    UNUserNotificationCenter.current().delegate = self

    UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .badge, .sound]) { granted, _ in
      if granted {
        DispatchQueue.main.async { application.registerForRemoteNotifications() }
      }
    }

    return true
  }

  // MARK: - Device token

  func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
  ) {
    DashXNotificationHandler.handleDeviceToken(deviceToken)
  }

  // MARK: - Remote notifications (silent push)

  func application(
    _ application: UIApplication,
    didReceiveRemoteNotification userInfo: [AnyHashable: Any],
    fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void
  ) {
    DashXNotificationHandler.handleRemoteNotification(userInfo: userInfo, completionHandler: completionHandler)
  }

  // MARK: - Foreground notifications

  func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    willPresent notification: UNNotification,
    withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
  ) {
    DashXNotificationHandler.handleForegroundNotification(notification, completionHandler: completionHandler)
  }

  // MARK: - Notification taps

  func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    didReceive response: UNNotificationResponse,
    withCompletionHandler completionHandler: @escaping () -> Void
  ) {
    let result = DashXNotificationHandler.handleNotificationResponse(response)
    if let url = result.url {
      // Handle deep link navigation
    }
    completionHandler()
  }

  // MARK: - FCM token

  func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
    guard let token = fcmToken else { return }
    DashX.setFCMToken(to: token)
  }
}

DashXNotificationHandler automatically:

• Bridges APNS tokens to FCM and registers with DashX (handleDeviceToken)
• Parses silent pushes, creates local notifications with action buttons and image attachments (handleRemoteNotification)
• Tracks delivered events and presents foreground notifications as banner + sound (handleForegroundNotification)
• Tracks clicked / dismissed events and extracts the notification URL for deep linking (handleNotificationResponse)
• Forwards all payloads to the JS onMessageReceived listener

Set FirebaseAppDelegateProxyEnabled = NO in your Info.plist

This tells Firebase not to swizzle the remote-notification methods so your AppDelegate gets the raw payloads:

<key>FirebaseAppDelegateProxyEnabled</key>
<false/>

New Architecture (optional)

If you want to opt into the New Architecture / TurboModule path:

• Android — in android/gradle.properties:

  newArchEnabled=true

• iOS — run pod install with RCT_NEW_ARCH_ENABLED=1:

  cd ios && RCT_NEW_ARCH_ENABLED=1 pod install

The same @dashx/react-native package and the same JavaScript API work on both architectures — no code changes needed.

Configuration

Initialize the SDK once, as early as possible (module-level initialization is recommended):

import DashX from '@dashx/react-native';

DashX.configure({
  publicKey: 'your-public-key',
  // baseURI: 'https://api.dashx.com/graphql',   // optional
  // targetEnvironment: 'production',            // optional
});

Usage

Identify a user

DashX.identify({
  firstName: 'John',
  lastName: 'Doe',
  email: 'john@example.com',
});

Set identity token

DashX Identity (setIdentity)

You can set uid without token and still use public features/resources. The second argument is the DashX Identity Token: a JWT from your backend, signed with your workspace private key (see User management). Setting token grants access to your private resources in DashX — only set it for users who need that access, and treat it as sensitive. Omit the token when the app only needs public features/resources.

Pass both when you need access to private resources:

DashX.setIdentity('user-uid', 'user-token');

Or just the UID for public features:

DashX.setIdentity('user-uid');

Reset

DashX.reset();

Learn more

Track events

DashX.track('Button Clicked', { placement: 'top' });

Track screen views

DashX.screen('HomeScreen', { referrer: 'DeepLink' });

Learn more

Messaging (push + preferences)

Subscribe/unsubscribe the device:

DashX.subscribe();
DashX.unsubscribe();

Request and check notification permissions:

// Request permission to show notifications
await DashX.requestNotificationPermission();

// Check current permission status without prompting
const status = await DashX.getNotificationPermissionStatus();

getNotificationPermissionStatus and requestNotificationPermission return a numeric status:

Value	Status
0	Not determined
1	Denied
2	Authorized
3	Provisional (iOS only)
4	Ephemeral (iOS only)

note

On Android, requestNotificationPermission uses the POST_NOTIFICATIONS runtime permission on API 33+. On older Android versions, permission is auto-granted and the method returns 2 (authorized).

Fetch and save stored preferences (requires an identified user via setIdentity with uid + JWT when private resources require it):

const prefs = await DashX.fetchStoredPreferences();

await DashX.saveStoredPreferences({
  'new-post': { enabled: true },
  'new-bookmark': { enabled: false },
});

Listen for incoming messages:

const subscription = DashX.onMessageReceived((message) => {
  console.log('Message received', message);
});

// later
subscription.remove();

Learn more

CMS

Fetch a record by URN (the URN must be in the form {resource}/{uuid}):

const record = await DashX.fetchRecord('email/550e8400-e29b-41d4-a716-446655440000', {
  preview: true,
  language: 'en_US',
});

Search records:

const records = await DashX.searchRecords('email', {
  filter: { identifier: { eq: 'welcome' } },
  limit: 10,
  preview: true,
  language: 'en_US',
});

Assets

Upload a file:

const asset = await DashX.uploadAsset('/path/to/file', 'users', 'avatar');

Fetch an asset's status and URL:

const asset = await DashX.fetchAsset('asset-id');

note

fetchAsset is not available on Android and will reject with EUNSUPPORTED. uploadAsset works on both platforms.

iOS-specific features

The following methods are available only on iOS:

// Automatically track app lifecycle events (installed, updated, opened, backgrounded)
DashX.enableLifecycleTracking();

// Request App Tracking Transparency permission and enable IDFA collection
DashX.enableAdTracking();

// Listen for deep links / universal links
const subscription = DashX.onLinkReceived((link) => {
  console.log('Link received', link);
});

// later
subscription.remove();

Track deep link opens

Record a dx_deep_link_opened analytics event and optionally forward the URL to the onLinkReceived listener:

DashX.processURL('https://example.com/promo', {
  source: 'universal_link',       // optional attribution source
  forwardToLinkHandler: true,     // default: true — forwards to onLinkReceived
});

Option	Type	Default	Description
source	string	undefined	Attribution source (e.g. "universal_link", "notification", "scene_url")
forwardToLinkHandler	boolean	true	Whether to also forward the URL to the onLinkReceived listener

Track notification navigation

Record a dx_notification_navigated event when the user taps a notification. Pass a navigation action describing where the tap leads:

// Deep link
DashX.trackNotificationNavigation(
  { type: 'deepLink', url: 'https://example.com/item/42' },
  'notification-id-123'
);

// In-app screen
DashX.trackNotificationNavigation(
  { type: 'screen', name: 'OrderDetails', data: { orderId: '42' } },
  'notification-id-456'
);

// Rich landing (in-app browser)
DashX.trackNotificationNavigation(
  { type: 'richLanding', url: 'https://promo.example.com' },
  'notification-id-789'
);

// Click action
DashX.trackNotificationNavigation(
  { type: 'clickAction', action: 'OPEN_SETTINGS' },
  'notification-id-000'
);

// Default (no specific action)
DashX.trackNotificationNavigation(null, 'notification-id-111');

Action type	Fields	Description
deepLink	url: string	Opens the URL externally
screen	name: string, data?: Record<string, string>	In-app navigation to a named screen
richLanding	url: string	Opens the URL in an in-app browser
clickAction	action: string	Intent action (Android) or notification category (iOS)

Learn more about deep linking

Error Handling

All promise-based methods reject with an error containing code and message properties:

try {
  await DashX.fetchRecord('blog/invalid');
} catch (error) {
  console.log(error.code);    // 'EUNSPECIFIED'
  console.log(error.message); // description of what went wrong
}

The SDK exports a DashXErrorCode enum for type-safe comparisons:

Code	Meaning
EUNSPECIFIED	An unspecified error occurred
EUNSUPPORTED	The operation is not supported on this platform

Troubleshooting

Logging

DashX.setLogLevel(2); // 0 = off, 1 = errors, 2 = debug

Android notification channels

DashX.configure() automatically creates a default notification channel (default_dashx_notification_channel) with IMPORTANCE_HIGH, so heads-up banners work out of the box. For custom channels, create them in Application.onCreate() and have your backend send channel_id in the DashX payload.