Setting Up SDK

Follow this guide to integrate Reteno into an Expo app.

Step 1: Install package

Using yarn:

yarn add expo-reteno-sdk

or npm:

npm i expo-reteno-sdk

Step 2: Configure plugin in `app.json`

{
  "expo": {
    "plugins": [
      [
        "expo-reteno-sdk",
        {
          "ios": {
            "sdkAccessToken": "YOUR_SDK_ACCESS_KEY",
            "mode": "production",
            "notificationService": "apns",
            "devTeam": "XXXXXXXXXX",
            "appGroups": ["group.com.your.bundleid.reteno-local-storage"],
            "config": {
              "isDebugMode": false
            }
          }
        }
      ]
    ]
  }
}

Step 3: Run Expo prebuild and install pods

npx expo prebuild --platform ios
npx pod-install

The plugin configures Reteno initialization, Notification Service Extension target, entitlements, and App Groups.

It also creates Notification Content Extension (NotificationContentExtension) for rich push UI (carousel/content rendering).

Step 4: Open Xcode project and verify capabilities

Open ios/<YourApp>.xcworkspace in Xcode.

For your main app target:

Go to Signing & Capabilities
Add Push Notifications
Ensure App Groups capability is enabled

Step 5: Development build required

Run iOS app with native build:

npx expo run:ios

expo-reteno-sdk is not supported in Expo Go.

EAS Build (important for iOS extensions)

If you build with EAS Build (managed credentials), define iOS app extensions in Expo config. Without this block, extension signing/provisioning may fail in cloud build.

Add to app.json / app.config:

{
  "expo": {
    "extra": {
      "eas": {
        "build": {
          "experimental": {
            "ios": {
              "appExtensions": [
                {
                  "targetName": "NotificationServiceExtension",
                  "bundleIdentifier": "com.your.bundle.NotificationServiceExtension",
                  "entitlements": {
                    "com.apple.security.application-groups": [
                      "group.com.your.bundle.reteno-local-storage"
                    ]
                  }
                },
                {
                  "targetName": "NotificationContentExtension",
                  "bundleIdentifier": "com.your.bundle.NotificationContentExtension",
                  "entitlements": {
                    "com.apple.security.application-groups": [
                      "group.com.your.bundle.reteno-local-storage"
                    ]
                  }
                }
              ]
            }
          }
        }
      }
    }
  }
}

Replace com.your.bundle with your real iOS bundle identifier.

References:

Optional: Firebase on iOS

If you use FCM on iOS:

set notificationService to "firebase"
add GoogleService-Info.plist to your iOS project target
pass FCM token to Reteno with Reteno.setDeviceToken(token)

Plugin Props

Prop	Type	Required	Description
`sdkAccessToken`	`string`	Yes	Reteno SDK access key
`mode`	`"development"` \| `"production"`	Yes	APS environment. Use `"development"` for debug/simulator builds, `"production"` for App Store/TestFlight
`notificationService`	`"apns"` \| `"firebase"`	Yes	Push delivery provider
`devTeam`	`string`	No	Apple Development Team ID (10-character string from Apple Developer portal)
`appGroups`	`string[]`	Yes	App Group identifiers (e.g. `["group.com.your.bundleid.reteno-local-storage"]`)
`config`	`object`	Yes	SDK initialization config (see `config` object below)
`deploymentTarget`	`string`	No	iOS deployment target for Notification Service Extension. Default: `"15.1"`
`nseFilepath`	`string`	No	Path to a custom `NotificationService.swift` file

`config` object

The config object inside the ios section controls native SDK initialization behavior:

Key	Type	Default	Description
`isDebugMode`	`boolean`	`false`	Enable SDK debug logging
`isAutomaticSessionReportingEnabled`	`boolean`	`false`	Automatically track session start/end events
`isAutomaticPushSubsriptionReportingEnabled`	`boolean`	`false`	Automatically track push subscription/unsubscription events
`isPausedInAppMessages`	`boolean`	`false`	Start with in-app messages paused

Example:

"config": {
  "isDebugMode": true,
  "isAutomaticSessionReportingEnabled": true,
  "isAutomaticPushSubsriptionReportingEnabled": true,
  "isPausedInAppMessages": false
}

Firebase Integration

If you use Firebase Cloud Messaging instead of APNs directly:

1. Install Firebase package

yarn add @react-native-firebase/app @react-native-firebase/messaging

2. Set `notificationService` to `"firebase"` in `app.json`

{
  "ios": {
    "sdkAccessToken": "YOUR_SDK_ACCESS_KEY",
    "mode": "production",
    "notificationService": "firebase",
    "devTeam": "XXXXXXXXXX",
    "appGroups": ["group.com.your.bundleid.reteno-local-storage"],
    "config": {
      "isDebugMode": false
    }
  }
}

3. Run prebuild and pod install

npx expo prebuild --platform ios
npx pod-install

The plugin automatically adds Firebase modular headers to your Podfile and configures MessagingDelegate in AppDelegate.swift.

4. Add `GoogleService-Info.plist` to Xcode

Download GoogleService-Info.plist from your Firebase Console and add it to your main app target in Xcode.

5. Pass the FCM token to Reteno

import { useEffect } from 'react';
import messaging from '@react-native-firebase/messaging';
import Reteno from 'expo-reteno-sdk';
import { Platform } from 'react-native';

useEffect(() => {
  if (Platform.OS !== 'ios') return;

  messaging().getToken().then((token) => {
    Reteno.setDeviceToken(token);
  });

  return messaging().onTokenRefresh((token) => {
    Reteno.setDeviceToken(token);
  });
}, []);

Auto-open Links — Native Setup

To control automatic URL opening on cold start (app launched from a killed state via push notification), add a link handler to AppDelegate.swift before Reteno.start():

import Reteno

@main
class AppDelegate: RCTAppDelegate {

  private static let autoOpenLinksKey = "RetenoAutoOpenLinks"

  private static var autoOpenLinks: Bool {
    if UserDefaults.standard.object(forKey: autoOpenLinksKey) == nil {
      return true
    }
    return UserDefaults.standard.bool(forKey: autoOpenLinksKey)
  }

  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
  ) -> Bool {

    // IMPORTANT: set handler BEFORE Reteno.start()
    Reteno.addLinkHandler { linkInfo in
      NotificationCenter.default.post(
        name: NSNotification.Name("RetenoLinkReceived"),
        object: nil,
        userInfo: [
          "customData": linkInfo.customData,
          "url": linkInfo.url?.absoluteString as Any
        ]
      )

      if AppDelegate.autoOpenLinks, let url = linkInfo.url {
        UIApplication.shared.open(url)
      }
    }

    // rest of setup...
  }
}

See the Push notification guide for the JS-side setAutoOpenLinks / getAutoOpenLinks API.

Important

mode is required (development for debug/simulator, production for TestFlight/App Store).
appGroups is required for proper Reteno storage between app and extension.