# Packages and Configuration Options ## How it works[](#how-it-works) With our Expo plugin, you can configure the SDK in two ways: **Auto-initialization (Expo 53+):** Configure everything in your `app.json` file using the `config` object. The SDK will automatically initialize without requiring `CustomerIO.initialize()` in your app code. **Manual initialization:** Configure native settings in `app.json` and SDK runtime settings in your React Native app code using `CustomerIO.initialize()`. Both approaches require configuration in your `app.json` or `app.config.js` files that affect the native files we generate when you run the prebuild. ## Configuring the Expo Plugin[](#configuring-the-expo-plugin) To use the Expo plugin, you’ll need to add a `customerio-expo-plugin` entry to your `app.json` or `app.config.js` files. 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, you’ll also want to 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](/integrations/sdk/expo/push-notifications/multiple-push-providers) Auto-initialization (Expo 53+) #### Auto-initialization (Expo 53+)[](#Auto-initialization \(Expo 53+\)) ```json { "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": "", "siteId": "", "region": "us" }, "android": { "googleServicesFile": "./files/google-services.json" }, "ios": { "useFrameworks": "static", // must match value in expo-build-properties if set "pushNotification": { "provider": "fcm", // use "apn" for Apple Push Notification service "googleServicesFile": "", // required if provider is "fcm" and you don't use the @react-native-firebase SDK "useRichPush": true, "appGroupId": "group.com.example.myapp.cio" } } } ] ] } ``` Manual initialization #### Manual initialization[](#Manual initialization) ```json { "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 "pushNotification": { "provider": "fcm", // use "apn" for Apple Push Notification service "googleServicesFile": "", // 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": "", "region": "us" } } } } ] ] } ``` ### Auto-initialization configuration options (Expo 53+)[](#auto-initialization-configuration-options-expo-53) When using auto-initialization, include a `config` object in your plugin configuration: Option Type Default Description `config` object Container for auto-initialization settings. If present, enables auto-initialization. `config.cdpApiKey` string **Required**: Your CDP API key `config.siteId` string Optional: Your site ID for in-app messaging. Required to enable in-app messaging. `config.region` string `US` Workspace region: "US" or "EU" `config.logLevel` string `debug` Log level: "none", "error", "info", or "debug" `config.autoTrackDeviceAttributes` boolean `true` Automatically track device attributes `config.trackApplicationLifecycleEvents` boolean `true` Track app lifecycle events `config.screenViewUse` string `all` Screen view tracking: "all" (server + in-app) or "inapp" (in-app only) `config.migrationSiteId` string Previously used site id, required if migrating from earlier versions (1.X) `config.location` object Enable [location tracking](/integrations/sdk/expo/tracking/location/). Takes a `trackingMode` option: `MANUAL` (default), `ON_APP_START`, or `OFF`. ### Expo plugin configuration options[](#expo-plugin-configuration-options) Option Type Default Description `android` object Required if you want to setup Android even if it is empty. Eg (`"android": {}`). `android.googleServicesFile` string Set the path to your `google-services.json` file. `android.setHighPriorityPushHandler` boolean This is optional, if you choose to use a 3rd party plugin to handle notification permissions, but want our SDK to handle the notifications. `android.pushNotification.channel.id` string `[your package name]` (Optional) Android messaging notification channel ID `android.pushNotification.channel.name` string `[your app name] Notifications` (Optional) Android messaging notification channel name `android.pushNotification.channel.importance` integer `3` (Optional) The importance of the channel. Acceptable values are 0 (min), 1 (low), 2 (medium), 3 (default/high), and 4 (urgent). See the [Android developer documentation](https://developer.android.com/develop/ui/views/notifications/channels#importance) for more about the behavior of each importance level `ios` object **Required**: The parent object for iOS settings, including your initialization keys. `ios.useFrameworks` string (Optional) Allows the plugin to work with static libraries. Options are `static` and `dynamic` `ios.pushNotification` object **Required** Configurations for push notifications for iOS. `ios.pushNotification.env` object **Required for manual initialization only** Contains your API key (`pushNotification.env.cdpApiKey`) and region (`pushNotification.env.region` with one of `eu` or `us`) information. Optional when using auto-initialization with `config` object. `ios.pushNotification.env.cdpApiKey` string **Required**: the key to use for authentication `ios.pushNotification.env.region` `us` or `eu` `us` The region your Customer.io account is in. If you use the wrong region, your mobile traffic won’t make it into Customer.io. `ios.pushNotification.autoFetchDeviceToken` boolean `true` When `true`, the SDK automatically gets the device token. But, if you get tokens through another provider and register them with the SDK using the `CustomerIO.registerDeviceToken` method, you should set this to `false`. [Learn more](/integrations/sdk/expo/push-notifications/multiple-push-providers) `ios.pushNotification.provider` string `apn` Use `apn` for Apple Push Notification service or `fcm` for Firebase Cloud Messaging. `ios.pushNotification.googleServicesFile` string **Required** if `ios.pushNotification.provider` is `fcm`. Set the path to your `GoogleService-Info.plist` file. **Do not set this value if you use the `@react-native-firebase` SDK.** [Learn more](#avoiding-conflicts-with-the-firebase-react-native-sdk) `ios.pushNotification.useRichPush` boolean `false` Enables rich push features for iOS (images and links). `ios.pushNotification.disableNotificationRegistration` boolean `false` (Optional) Removes the `registerPushNotification` handler and allows you to control notification permission requests. We recommend that you set this to `true` if you have `customerio-reactnative` version `>= 2.2.0` installed. `ios.pushNotification.showPushAppInForeground` boolean `true` Set to `true` if you want push notifications sent by Customer.io to be shown when your app is in the foreground. `ios.pushNotification.handleDeeplinkInKilledState` boolean `false` Set to `true` if you want the Customer.io SDK to handle deep links when your app is in a killed/closed state. `ios.pushNotification.appGroupId` string (Optional) Your App Group identifier for [reliable push delivery tracking](/integrations/sdk/expo/push-notifications/app-groups/). Must start with `group.`. When set, the plugin automatically configures App Group entitlements and passes the identifier to the SDK. Requires `useRichPush: true`. `location` object Container for [location tracking](/integrations/sdk/expo/tracking/location/) plugin settings. `location.enabled` boolean `false` When `true`, the plugin adds the native location dependencies (iOS Podfile subspec and Android Gradle properties) during prebuild. Your app must add its own location permissions and privacy usage descriptions. ## SDK packages[](#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. Package Product Required? Description CustomerIO ✅ The main SDK package. Used to initialize the SDK and call the SDK’s methods. CioConfig ✅ Configure the SDK including in-app messaging support. CioRegion Used inside the `CioConfig.region` option to declare your region—EU or US. CioLogLevel Used inside the `CioConfig.logLevel` option to set the level of logs you can view from the SDK. CioLocationTrackingMode Used inside `CioConfig.location` to set the tracking mode. See [location tracking](/integrations/sdk/expo/tracking/location/) for details. ## React configuration options[](#react-configuration-options) You can determine global behaviors for the SDK in using `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, etc. Note that the `logLevel` option requires the `CioLogLevel` package and the `region` option requires the `CioRegion` package. ```javascript 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) }, []) } ``` Option Type Default Description `cdpApiKey` string **Required**: the key you'll use to initialize the SDK and send data to Customer.io `region` `CioRegion.EU` or `CioRegion.US` `CioRegion.US` ****Requires the CioRegion package.** You must set the region your account is in the EU (`CioRegion.EU`).** `apiHost` string The domain you’ll proxy requests through. You’ll only need to set this (and `cdnHost`) if you’re [proxying requests](#proxying-requests). `autoTrackDeviceAttributes` boolean `true` Automatically gathers information about devices, like operating system, device locale, model, app version, etc `cdnHost` string The domain you’ll fetch configuration settings from. You’ll only need to set this (and `apiHost`) if you’re [proxying requests](#proxying-requests). `logLevel` string `error` **Requires the `CioLogLevel` package**. Sets the level of logs you can view from the SDK. Set to `debug` or `info` to see more logging output. `migrationSiteId` string **Required if you're updating from 3.x**: the credential for previous versions of the SDK. This key lets the SDK send remaining tasks to Customer.io when your audience updates your app. `screenViewUse` `All` or `InApp` `All` `ScreenView.All` (Default): Screen events are sent to Customer.io. You can use these events to build segments, trigger campaigns, and target in-app messages. `ScreenView.InApp`: Screen view events not sent to Customer.io. You’ll *only* use them to target in-app messages based on page rules. `trackApplicationLifecycleEvents` boolean `true` Set to `false` if you don't want the app to send lifecycle events `inApp` object **Required for in-app support**. This object takes a `siteId` property, determining the workspace your in-app messages come from. `push` object Takes a single option called `PushClickBehaviorAndroid`. This object and option controls how your app behaves when your Android audience taps push notifications. `location` object Enable [location tracking](/integrations/sdk/expo/tracking/location/). Takes a `trackingMode` option from the `CioLocationTrackingMode` package. ## Proxying requests[](#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](/integrations/data-in/proxying-requests) for more information. ```javascript 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); }, []); ```