Expo Plugin for Iterable's React Native SDK

Iterable's React Native SDK offers an Expo plugin that extends configuration management, making it easier to manage dependencies and configurations. Use the Expo plugin to minimize the potential for configuration errors, which might occur during a manual setup, and to significantly reduce the time to complete the following tasks, which are required to use Iterable's React Native SDK:

• Configure native dependencies
• Set up iOS and Android project settings
• Handle native code modifications
• Manage platform-specific configurations

The Expo plugin has the following additional benefits:

• The plugin automatically configures push notifications for both iOS and Android platforms.

  • For iOS, the plugin adds bridge to native Iterable code, sets up the notification service extension, configures required entitlements, and handles notification permissions.

  • For Android, the plugin adds bridge to native Iterable code, configures the Firebase integration, sets up notification handling, and manages notification permissions.

• The plugin configures deep linking capabilities for both platforms.

  • For iOS, the plugin sets up Universal Links and configures associated domains.

  • For Android, the plugin configures App Links amd sets up intent filters.

Read this article to learn about the requirements that must be satisfied before using this plugin and how to automate Installing Iterable's React Native SDK by utilizing Iterable's Expo plugin.

# In this article

# Requirements

To use the Iterable Expo plugin, you must satisfy the following requirements:

• Expo SDK 52+
• React Native 0.75+
• React 18.1+
• Iterable's React Native SDK 2.0.0+

# Special considerations

Before you install the Expo plugin, note the following considerations and limitations:

# Non-EAS compatibility

If your app is not built with EAS, a compatibility issue between React Native 0.75 and Xcode 16.3 requires you to install:

• React Native 0.75
• Xcode 16.2 or earlier (download here)

Or:

• React Native 0.76+
• Xcode 16.3+

# React Native's New Architecture

@iterable/react-native-sdk and @iterable/iterable-expo-plugin do not currently support React Native's New Architecture (Fabric, TurboModules, and Codegen). The SDK is designed to work with the legacy architecture only. If you're using the New Architecture in your React Native application, you may encounter compatibility issues.

To disable the New Architecture, see Disabling New Architecture.

# Expo Go

Your expo app needs to be run as a development build instead of through Expo Go. Both @iterable/iterable-expo-plugin and @iterable/react-native-sdk will NOT work in Expo Go, as they rely on native code, which Expo Go does not support.

# Native code

# Installing and configuring the Expo plugin

The Expo plugin (@iterable/expo-plugin) simplifies the installation and configuration process by automating several steps that would otherwise need to be done manually. These steps include:

# 1. Simplified installation

Instead of manually configuring native dependencies and settings, all you need to do is:

1. Install the plugin and SDK with a single command:

   npx expo install @iterable/expo-plugin @iterable/react-native-sdk
   

2. Add a simple configuration to your app.json or app.config.js:

    {
      "expo": {
        "plugins": [
          ["@iterable/expo-plugin", {}]
        ]
      }
    }
   

# 2. Automated native setup

The plugin handles all of the native configuration automatically, including:

• Setting up the necessary native dependencies
• Configuring iOS and Android project settings
• Handling any required native code modifications

If you are NOT manually configuring your native code, run:

npx expo prebuild --clean

# 3. Development workflow

After the automated setup:

• Run npx expo run:ios for iOS development
• Run npx expo run:android for Android development

# 4. Simple integration

Once the setup is complete, you can start using the SDK in your React Native code with a straightforward import and initialization:

import {useEffect} from 'react';
import {Iterable, IterableConfig} from '@iterable/react-native-sdk';

const App = () => {
  useEffect(() => {
    Iterable.initialize('MY_API_KEY', new IterableConfig());
  }, []);
}

# Configuration options

When you add the plugin to your app.json or app.config.js, you can use the following plugin options:

{
  "expo": {
    "plugins": [
      ["@iterable/expo-plugin", {
        "appEnvironment": "development",
        "autoConfigurePushNotifications": true,
        "enableTimeSensitivePush": true,
        "requestPermissionsForPushNotifications": true,
      }]
    ]
  }
}

# Additional configuration tasks

# Disabling New Architecture

@iterable/react-native-sdk is NOT compatible with Reacts New Architecture, so this needs to be disabled in your app.json.

To disable the new architecture, add the following to your app.json:

{
  "expo": {
    "newArchEnabled": false
  }
}

# Adding push capabilities

# iOS

To add push capabilities to your iOS app, follow the steps to configure push notifications for iOS in Iterable.

# Android

To add push capabilities for your Android app, first, configure push notifications for Android in Iterable.

Your app also needs a google-services.json file. If you don't have one, you can get it from the Firebase console. Follow steps 4.1.1 and 4.1.2 to configure Firebase for Iterable and download the google-services.json file.

Add the path to your google-services.json file to the app file under expo.android.googleServicesFile.

For example, if the google services file was added to the root of the app, the Expo file would look like this:

{
  "expo": {
    "android": {
      "googleServicesFile": "./google-services.json"
    }
  }
}

# Adding Deeplinks

Deep linking allows users to navigate to specific screens in your app using URLs.

To set up deep linking in your Expo application, configure deep links in Iterable, then follow these instructions.

# iOS

To add deeplinks to your Expo app for use with Iterable on iOS devices, add associated domains to your app.json under the iOS configuration.

For example:

{
  "expo": {
    "ios": {
      "associatedDomains": [
          "applinks:expo.dev",
          "applinks:iterable.com",
          "applinks:links.anotherone.com"
       ]
    }
  }
}

This is the equivalent of adding them through Signing & Capabilities in Xcode, as described in step 5 of Iterables iOS Universal Links Documentation.

Learn more about how Expo sets up iOS Universal Links.

# Android

To add deeplinks to your Expo app for use with Iterable on Android devices, add URL schemes and intent filters to your app.json under the Android configuration. These would be in expo.android.intentFilters.

For example:

{
  "expo": {
    "android": {
      "intentFilters": [
        {
          "action": "MAIN",
          "category": ["LAUNCHER"],
          "autoVerify": true,
        },
        {
          "action": "VIEW",
          "autoVerify": true,
          "data": [
            {
              "scheme": "https",
              "host": "links.example.com",
              // Deep links coming from Iterable are prefixed by "/a/", so include this as the "pathPrefix".
              "pathPrefix": "/a/"
            }
          ],
          "category": ["BROWSABLE", "DEFAULT"]
        }
      ]
    }
  }
}

Learn more about how Expo sets up Android App Links.

# Configuring Proguard

If you're using Proguard when building your Android app, add this line of ProGuard configuration to your build: -keep class org.json.** { *; }.

To do this using Expo:

1. Add the expo-build-properties plugin by running:

   npx expo install expo-build-properties
   

2. Add the plugin to your app.json file.

3. Then add {android:{extraProguardRules:"-keep class org.json.** { *; }"}} to the plugin option.

The overall code in your app.json file should look something like this:

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "extraProguardRules": "-keep class org.json.** { *; }"
          }
        }
      ]
    ]
  }
}

Learn more in the Configure Proguard section of Iterables Android SDK setup docs.

# Troubleshooting

# Native Module Not Found

If you encounter the error "Your JavaScript code tried to access a native module that doesn't exist in this development client", try:

1. Clean your project.

rm -rf node_modules
rm -rf ios/Pods
yarn cache clean

2. Reinstall dependencies.

yarn install

3. Rebuild native projects.

npx expo prebuild --clean
cd ios && pod install && cd ..

# Failed to delete [ios|android] code: ENOTEMPTY: directory not empty

Sometimes this error appears when running npx expo prebuild --clean. The error generally resolves when you run the same command a second time, so just try again.

# License

MIT

# Further reading

• Installing Iterable's React Native SDK
• Expo docs