customerio-expo-plugin

Power automated communication that people like to receive.

Customer.io Expo Plugin

This is the official Customer.io Expo plugin, supporting mobile apps.

You'll find our complete SDK documentation at https://customer.io/docs/sdk/expo. This readme only contains basic information to help you install the plugin and handle the pre-build.

The Expo plugin takes advantage of our React Native SDK, and requires very little setup. It extends the Expo config to let you customize the prebuild phase of managed workflow builds, which means you don't need to eject to a bare workflow.

After you add the plugin to your project, you'll need to install our React Native SDK and run prebuild. The plugin automatically generates and configures the necessary native code files required to make our React Native SDK to work on your project. We've tested with Expo SDK versions 45 and 46, Using eas build with EAS managed credentials and a limited set of Android and iOS versions.

By default, the plugin expects to use Apple's Push Notification service (APNs) for iOS and Firebase Cloud Messaging (FCM) for Android. We plan to add FCM support for iOS in a future release.

Install and configure the plugin

1. Run an installation command:

   • expo install customerio-expo-plugin
   • npm install customerio-expo-plugin
   • yarn add customerio-expo-plugin

2. Add customerio-expo-plugin plugin in your app.json or app.config.js and set configuration options. In most cases, you'll want to stick to our default options. When you configure the plugin, you can pass options. In most cases, you'll want to stick with the defaults, which enables all the SDK features. However you might want to disable rich push for iOS.

   // app.json
   {
      ...
      "plugins": [
         ...
         [
         "customerio-expo-plugin",
         {
               "android": {
                  "googleServicesFile": "./files/google-services.json",
               },
               "ios": {
                  "pushNotification": {
                     "useRichPush": true
                  }
               }
            }
         ]
      ]
   }
   

3. Set the iOS build target. Our React Native SDK requires iOS deployment target 13. You can install expo-build-properties and add the following to app.json or app.plugin.js to set your build target.

   {
      ...
      "plugins": [
         ...
         [
         "expo-build-properties",
         {
            "ios": {
               "deploymentTarget": "13.0"
            }
         }
         ]
      ]
   }
   

4. Add an import statement to your project for the react native library. We haven't included it below, but you can import CioLogLevel to set log outputs to something other than error; this may help you debug your application.

   import { CustomerIO, CustomerioConfig, CustomerIOEnv, Region } from ‘customerio-reactnative’;
   

5. In useEffect, initialize the package with your CustomerioConfig options and CustomerIOEnv variables. You can find your Site ID and API Key credentials—or create new ones—under Data & Integrations > Integrations > Customer.io API:

   useEffect(() => {
      const data = new CustomerioConfig()
      data.logLevel = CioLogLevel.debug
   
      const env = new CustomerIOEnv()
      env.siteId = Env.siteId
      env.apiKey = Env.apiKey
      env.organizationId = Env.organizationId
      //organizationId is used to send in-app messages.
      env.region = Region.US
      //Region is optional, defaults to Region.US. Use Region.EU for EU-based workspaces.
   
      CustomerIO.initialize(env, data)
   }, [])
   

Plugin configuration options

The customerio-expo-plugin supports the following configuration options. In most cases, you'll want to use the default options shown in the installation instructions.

Option	Type	Default	Description
android	object	undefined	Required if you want to setup Android even if it is empty. Eg ("android": {}).
ios	object	undefined	Required if you want to setup iOS even if it is empty. Eg ("ios": {}).
android.googleServicesFile	string	undefined	Set the path to your google-services.json file.
ios.pushNotification	object	undefined	Enables push notifications for iOS, even if it is an empty object
ios.pushNotification.useRichPush	boolean	false	Enables rich push for iOS
ios.pushNotification.env	object	undefined	Set environment variables to use for rich push workaround. This field should be filled when enabling rich push. Expected values: `siteId`: `string`,`apiKey`: `string`, `region`: `us` or `eu`
ios.useFrameworks	string	undefined	This is optional, it allows the plugin to work with static libraries. Options are static and dynamic

Run the prebuild

After you install and configure the plugin, run the prebuild.

# Run prebuild
expo prebuild

# Delete ios and android folders before prebuild
expo prebuild --clean

Now your project is ready to use the React Native SDK.

Enable Rich Push on iOS

For now, you'll need to add a short workaround to take advantage of rich push features. Add the following to ios/NotificationService/NotificationService.swift after you run prebuild --clean.

...
import CioTracking // <== Add import

@objc
public class NotificationServiceCioManager : NSObject {

    public override init() {}

    @objc(didReceive:withContentHandler:)
    public func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
      CustomerIO.initialize(siteId: "<YourSiteId>", apiKey: "<YourApiKey>", region: Region.US) // <== Workaround code
      ...

More information

See our complete SDK documentation at https://customer.io/docs/sdk/expo/

Contributing

Thanks for taking an interest in our project! We welcome your contributions.

We value an open, welcoming, diverse, inclusive, and healthy community for this project. We expect all contributors to follow our code of conduct.

License

MIT

Changelog

1.0.0-beta.3 (2023-02-20)

Bug Fixes

• hot fixes (#37) (4e1953c)