!@iterable/expo-plugin

@iterable/expo-plugin


This config plugin automatically configures your Expo app to work with
@iterable/react-native-sdk when
the native code is generated through expo prebuild.

- @iterable/expo-plugin
- 🚀 Quick Start
- 🔧 Configuration
- Plugin Options
- Disabling New Architecture
- Adding push capabilities
- iOS
- Android
- Adding Deeplinks
- iOS
- Android
- Configuring ProGuard
- Configuring for EAS Builds
- iOS EAS Build Configuration
- Finding Your EAS Project ID
- Troubleshooting EAS Build Issues
- ✅ Requirements and Limitations
- 🎉 Features
- Push Notifications
- iOS
- Android
- Deep Links
- iOS
- Android
- ⁉️ Troubleshooting
- Native Module Not Found
- [Failed to delete \[ios|android\] code: ENOTEMPTY: directory not empty](#failed-to-delete-iosandroid-code-enotempty-directory-not-empty)
- 👏 Contributing
- 📝 License
- 💬 Support
- 📚 Further Reading

🚀 Quick Start

1. Install the plugin and @iterable/react-native-sdk by running the following in your terminal:

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

2. Add the plugin to to your app.json or app.config.js

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

3. After installing and configuring the plugin, rebuild your native projects:

`bash
npx expo prebuild --clean
`

WARNING: prebuild will delete everything in your ios/android directories.

4. Run your ios or android simulator:

- ios:

`bash
npx expo run:ios
`

- android:

`bash
npx expo run:android
`

5. Import @iterable/react-native-sdk and use as needed. EG:

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

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

🔧 Configuration

Add the plugin to your app.json or app.config.js:

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

$3

| Option | Type | Default | Description |
| ---------------------------------------- | --------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| appEnvironment | 'development' \| 'production' | 'development' | The environment of your app |
| autoConfigurePushNotifications | boolean | true | Whether to automatically configure push notifications. Set to false if you want to configure push notifications manually.

WARNING: Iterable cannot guarantee compatibility with custom push notification configurations. |
| enableTimeSensitivePush | boolean | true | Whether to enable time-sensitive push notifications (iOS only) |
| requestPermissionsForPushNotifications | boolean | false | Whether to request permissions for push notifications (iOS only) |

$3

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

`json
{
"expo": {
"newArchEnabled": false
}
}
`

$3

#### iOS

- Configure push notifications for iOS in Iterable

#### Android

- Configure push notifications for Android in Iterable
- Place your google-services.json file in the root of the _example_
directory
- In app.json, add the path to the google-services.json file to
expo.android.googleServicesFile. EG:

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

$3

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 the below 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.

EG:

`json
{
"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 Univeral Links
Documentation

See further documentation about how expo setup of iOS Universal Links
here.

#### 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.

EG:

`json
{
"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"]
}
]
}
}
}
`

See further documentation about how expo setup of Android App Links
here.

$3

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

Below is how to do this using Expo:

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

`bash
npx expo install expo-build-properties
`

2. Add the plugin to your _app.json_ file
3. To the plugin options, add {"android":{"extraProguardRules":"-keep class org.json.* { ; }"}}

The overall code in your _app.json_ file should look something like this:

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

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

$3

When building your app with EAS Build, you may encounter signing errors related to the IterableExpoRichPush notification service extension target that this plugin creates. This target needs to be properly configured in your app.json file for EAS builds to succeed.

#### iOS EAS Build Configuration

To resolve signing issues with the IterableExpoRichPush target, you need to add the app extension configuration to your app.json file. Add the following to your expo.extra.eas configuration:

`json
{
"expo": {
"ios": {
"bundleIdentifier": "your.app.bundle.id"
},
"extra": {
"eas": {
"projectId": "YOUR_EAS_PROJECT_ID",
"build": {
"experimental": {
"ios": {
"appExtensions": [
{
"targetName": "IterableExpoRichPush",
"bundleIdentifier": "your.app.bundle.id.IterableExpoRichPush"
}
]
}
}
}
}
}
}
}
`

Example Configuration:
If your EAS project ID is abc123 and your bundle identifier is com.myapp:

`json
{
"expo": {
"ios": {
"bundleIdentifier": "com.myapp"
},
"extra": {
"eas": {
"projectId": "abc123",
"build": {
"experimental": {
"ios": {
"appExtensions": [
{
"targetName": "IterableExpoRichPush",
"bundleIdentifier": "com.myapp.IterableExpoRichPush"
}
]
}
}
}
}
}
}
}
`

#### Finding Your EAS Project ID

To find your EAS project ID, run:
`bash
eas project:info
`

#### Troubleshooting EAS Build Issues

If you encounter the error "Signing for 'IterableExpoRichPush' requires a development team" after adding the above configuration:

1. Ensure your EAS credentials are properly configured:
`bash
eas credentials
`

2. Verify that your Apple Developer account has the necessary capabilities for push notifications

3. Try clearing the build cache:
`bash
eas build --platform ios --profile development --clear-cache
`

4. If issues persist, ensure your bundle identifier follows the correct pattern: your.main.bundle.id.IterableExpoRichPush

✅ Requirements and Limitations

- From v2.0.2,@iterable/react-native-sdk supports React Native's New
Architecture](https://reactnative.dev/architecture/landing-page) through the
Interop Layer. We are in the process of updating the SDK to fully support the
New Architecture, and suggest using the legacy architecture in the meantime.
TLDR; Use the New Architecture at your own risk -- you may encounter
significant issues.
- See Disabling New Architecture for
instructions on how to disable new architecture in your app.
- 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 are reliant on native code, which Expo Go does not
support.
- @iterable/iterable-expo-plugin is intended for managed workflows, and will
overwrite the files in your ios and android directories. Any manual
changes to those directories will be overwritten on the next build.
- This plugin has been tested on Expo version 52+. While it may work on
previous versions, they are not supported.

🎉 Features

$3

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

#### iOS

- Adds bridge to native Iterable code
- Sets up notification service extension
- Configures required entitlements
- Handles notification permissions

#### Android

- Adds bridge to native Iterable code
- Configures Firebase integration
- Sets up notification handling
- Manages notification permissions

$3

The plugin configures deep linking capabilities for both platforms.

#### iOS

- Sets up Universal Links
- Configures associated domains

#### Android

- Configures App Links
- Sets up intent filters

⁉️ Troubleshooting

$3

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:

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

2. Reinstall dependencies:

`bash
yarn install
`

3. Rebuild native projects:

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

$3

Sometimes this error appears when running npx expo prebuild --clean`. It seems
to be an intermittent bug within expo. It usually works upon running the same
command a second time, so just try again.

👏 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📝 License

This project is licensed under the MIT License - see the LICENSE file
for details.

💬 Support

For support, please:

1. Check the documentation
2. Open an issue
3. Contact Iterable support

📚 Further Reading

- Installing Iterables React Native
SDK
- Expo docs