Packages and configuration options

How options take effect

The Expo plugin reads two different kinds of options out of your app.json (or app.config.js) file, and they take effect at different times.

Because the plugin compiles your plugin options and config into native code, you need to run expo prebuild again and rebuild your app after you change them. An over-the-air update can’t change them, because it only replaces your JavaScript. Changes to CioConfig apply the next time your app calls CustomerIO.initialize().

You pick one of the two runtime paths:

Auto-initialization (Expo 53+): you add a config object to your plugin options. The plugin generates native initialization code, so the SDK starts on its own and you don’t have to call CustomerIO.initialize().

JavaScript initialization: you leave config out and call CustomerIO.initialize() with a CioConfig object in your app code. Code samples label this path Manual initialization.

Build-time options apply on both paths. Runtime options don’t: the plugin only generates native initialization code when config is present; when you initialize from JavaScript, nothing reads a config object. See Initializing from JavaScript for what changes on that path.

Build-time options

To use the Expo plugin, add a customerio-expo-plugin entry to your app.json or app.config.js file. The plugin reads this entry when you run expo prebuild and uses it to generate your native projects. Before you set up your app:

• If you’re in our EU region, set the region to eu.
• To support Customer.io’s latest features, set your iOS deployment target to 15.1 or higher.

If you send notifications to iOS users through Firebase Cloud Messaging, you’ll need to:

• Set expo-build-properties.ios.useFrameworks to static.
• Set customerio-expo-plugin.ios.pushNotification.provider to fcm.
• Set customerio-expo-plugin.ios.pushNotification.googleServicesFile to the location of your GoogleService-Info.plist file. If you use @react-native-firebase with the Customer.io SDK, you should not set this value. Learn more

{
  "plugins": [
    [
      "expo-build-properties",
      {
        "ios": {
          "deploymentTarget": "15.1", // set your iOS deployment target to support Customer.io
          "useFrameworks": "static" // set if you use FCM to send push notifications to iOS devices
        }
      }
    ],
    [
      "customerio-expo-plugin",
      {
        "config": {
          "cdpApiKey": "<cdpApiKey>",
          "siteId": "<siteId>",
          "region": "us"
        },
        "android": {
          "googleServicesFile": "./files/google-services.json"
        },
        "ios": {
          "useFrameworks": "static", // must match value in expo-build-properties if set
          "appleTeamId": "YOUR_TEAM_ID", // optional: for Notification Service Extension code signing
          "pushNotification": {
            "provider": "fcm", // use "apn" for Apple Push Notification service
            "googleServicesFile": "<Path to GoogleService-Info.plist file>", // required if provider is "fcm" and you don't use the @react-native-firebase SDK
            "useRichPush": true,
            "appGroupId": "group.com.example.myapp.cio"
          }
        }
      }
    ]
  ]
}

{
  "plugins": [
    [
      "expo-build-properties",
      {
        "ios": {
          "deploymentTarget": "15.1", // set your iOS deployment target to support Customer.io
          "useFrameworks": "static" // set if you use FCM to send push notifications to iOS devices
        }
      }
    ],
    [
      "customerio-expo-plugin",
      {
        "android": {
          "googleServicesFile": "./files/google-services.json"
        },
        "ios": {
          "useFrameworks": "static", // must match value in expo-build-properties if set
          "appleTeamId": "YOUR_TEAM_ID", // optional: for Notification Service Extension code signing
          "pushNotification": {
            "provider": "fcm", // use "apn" for Apple Push Notification service
            "googleServicesFile": "<Path to GoogleService-Info.plist file>", // required if provider is "fcm" and you don't use the @react-native-firebase SDK
            "useRichPush": true,
            "appGroupId": "group.com.example.myapp.cio",
            "env": {
              "cdpApiKey": "<cdpApiKey>",
              "region": "us"
            }
          }
        }
      }
    ]
  ]
}

Android options

These options control the Android project the plugin generates.

iOS options

These options control the Xcode project the plugin generates.

iOS push notification options

Everything under ios.pushNotification shapes the push handling the plugin writes into your Xcode project, including the Notification Service Extension that renders rich push notifications.

Native module options

Location, geofencing, and Live Notifications each need native dependencies that the plugin adds during prebuild. These options sit at the top level of your plugin config rather than inside config, because they describe what the plugin builds. That’s what makes them work whether you auto-initialize or initialize from JavaScript.

Runtime configuration

Runtime options set SDK behavior—logging, automatic tracking, in-app messaging—when your app launches. Where you set them depends on how the SDK initializes.

Auto-initialization options

Add a config object to your plugin options and the plugin generates native initialization code for both platforms, so the SDK starts without a CustomerIO.initialize() call in your app. The plugin only writes that code when config is present, so these options do nothing in an app that initializes from JavaScript.

[
  "customerio-expo-plugin",
  {
    "config": {
      "cdpApiKey": "<cdpApiKey>",
      "siteId": "<siteId>",
      "region": "us",
      "logLevel": "error",
      "screenViewUse": "all",
      "location": {
        "trackingMode": "ON_APP_START"
      }
    },
    "android": {},
    "ios": {
      "pushNotification": {
        "provider": "apn"
      }
    },
    "location": {
      "enabled": true
    }
  }
]

Initializing from JavaScript

If you call CustomerIO.initialize() yourself, leave config out of your plugin options and set your runtime values in a CioConfig object instead. The manual initialization example shows the plugin options for this path. Three things work differently on this path:

• Build-time options still apply. The plugin reads android, ios, location, geofence, and liveNotifications at prebuild either way.
• ios.pushNotification.env becomes required for rich push. The Notification Service Extension needs your API key and region compiled in, and with no config object there’s nothing for the plugin to copy them from.
• Set Live Notification branding in both places. Put liveNotifications.branding in your plugin options and pass branding to CustomerIO.initialize(). The plugin compiles the value from your plugin options into the iOS widget, and the value you pass at runtime is what Android applies. The plugin generates no native initialization code on this path, so it can’t forward the value for you. You also need to set liveNotifications.enabled to true explicitly, because there’s no config.liveNotifications object to turn the feature on.

SDK packages

The SDK consists of a few packages. You must use the CioConfig and CustomerIO packages to configure and initialize the SDK in your React Native app.

CioConfig options

You determine global behaviors for the SDK using the CioConfig package. You must provide configuration options before you initialize the SDK; you cannot declare configuration changes after you initialize the SDK.

Import CioConfig and then set configuration options to configure things like your logging level and whether or not you want to automatically track device attributes. The logLevel option requires the CioLogLevel package and the region option requires the CioRegion package.

import {
  CioLogLevel,
  CioRegion,
  CustomerIO,
  CioConfig,
  PushClickBehaviorAndroid,
} from 'customerio-reactnative';

const App = () => {

useEffect(() => {
   const config: CioConfig = {
      cdpApiKey: 'CDP API Key', // Mandatory
      migrationSiteId: 'siteId', // Required if migrating from an earlier version
      region: CioRegion.US,
      logLevel: CioLogLevel.Debug,
      trackApplicationLifecycleEvents: true,
      inApp: {
         siteId: 'site_id',
      },
      push: {
         android: {
            pushClickBehavior: PushClickBehaviorAndroid.ActivityPreventRestart
         }
      }
   };
   CustomerIO.initialize(config)
   }, [])
}

Proxying requests

By default, requests go through our domain at cdp.customer.io. You can proxy requests through your own domain to provide a better privacy and security story, especially when submitting your app to app stores.

To proxy requests, you’ll need to set the apiHost and cdnHost properties in your SDKConfigBuilder. While these are separate settings, you should set them to the same URL.

While you need to initialize the SDK with a cdpApiKey, you can set this to any value you want. You only need to pass your actual key when you send requests from your server backend to Customer.io. If you want to secure requests to your proxy server, you can set the cdpApiKey to a value representing basic authentication credentials that you handle on your own. See proxying requests for more information.

import { CioConfig, CustomerIO, CioRegion } from "customerio-reactnative";

useEffect(() => {
  const config: CioConfig = {
    cdpApiKey: process.env.EXPO_PUBLIC_CDP_API_KEY,
    region: CioRegion.US,
    apiHost: "proxy.example.com",
    cdnHost: "proxy.example.com", 
    inApp: {
      siteId: process.env.EXPO_PUBLIC_SITE_ID,
    }
  };
  CustomerIO.initialize(config);
}, []);