### Install customerio-expo-plugin Source: https://docs.customer.io/integrations/sdk/expo/1.x/getting-started Install the customerio-expo-plugin using your preferred package manager. ```bash expo install customerio-expo-plugin ``` ```bash npm install customerio-expo-plugin ``` ```bash yarn add customerio-expo-plugin ``` -------------------------------- ### Example Lifecycle Event Data Source: https://docs.customer.io/integrations/sdk/expo/tracking/lifecycle-events This JSON object represents the data structure for an 'Application Installed' lifecycle event, including user ID, event type, event name, and specific properties like version and build. ```json { "userId": "app.installer@example.com", "type": "track", "event": "Application Installed", "properties": { "version": "3.2.1", "build": "247" } } ``` -------------------------------- ### Install customerio-reactnative SDK Source: https://docs.customer.io/integrations/sdk/expo/1.x/getting-started Install the customerio-reactnative SDK, ensuring to use version 3.9.1 or earlier as required by the Expo plugin. ```bash expo install customerio-reactnative@3.9.1 ``` ```bash npm install customerio-reactnative@3.9.1 ``` ```bash yarn add customerio-reactnative@3.9.1 ``` -------------------------------- ### Configure SDK with Options Source: https://docs.customer.io/integrations/sdk/expo/1.x/getting-started Configure SDK behaviors like log level and automatic tracking before initializing. This example shows how to enable debug logging and automatic device attribute tracking. ```javascript import { CustomerIO, CustomerioConfig } from 'customerio-reactnative'; const data = new CustomerioConfig() data.logLevel = CioLogLevel.debug data.autoTrackDeviceAttributes = true // In-app messages are optional and disabled by default // To enable in-app messages, set enableInApp to true data.enableInApp = true // `env` is the environment constant you used // to initialize the SDK in the previous section CustomerIO.initialize(env, data) ``` -------------------------------- ### Install Customer.io Expo Plugin v3.0.0 with npm Source: https://docs.customer.io/integrations/sdk/expo/whats-new/3.x-upgrade Use this command to update the Customer.io Expo plugin to version 3.0.0 using npm. ```bash npm install customerio-expo-plugin@3.0.0 ``` -------------------------------- ### Install Customer.io Expo Plugin and React Native SDK Source: https://docs.customer.io/integrations/sdk/expo/quick-start-guide Use this command to install the necessary packages for integrating Customer.io with your Expo React Native application. ```bash npx expo install customerio-expo-plugin customerio-reactnative ``` -------------------------------- ### Install Customer.io Expo Plugin v3.0.0 with yarn Source: https://docs.customer.io/integrations/sdk/expo/whats-new/3.x-upgrade Use this command to update the Customer.io Expo plugin to version 3.0.0 using yarn. ```bash yarn add customerio-expo-plugin@3.0.0 ``` -------------------------------- ### Configure Plugin in app.config.js Source: https://docs.customer.io/integrations/sdk/expo/1.x/getting-started Add the customerio-expo-plugin to your app.config.js configuration. This example demonstrates setting up Android and iOS push notifications with API credentials. ```javascript export default { ... plugins: [ ... [ "customerio-expo-plugin", { android: { googleServicesFile: "./files/google-services.json" }, ios: { pushNotification: { useRichPush: true, env: { siteId: "", apiKey: "", region: "" } } } } ] ] }; ``` -------------------------------- ### Expo Plugin Manual Initialization Configuration Source: https://docs.customer.io/files/expo-sdk-docs.md Configure the Customer.io SDK manually using app.json. This setup requires initializing the SDK in your app code. Includes settings for build properties, region, and push notifications. ```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 "appleTeamId": "YOUR_TEAM_ID", // optional: for Notification Service Extension code signing "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" } } } } ] ] } ``` -------------------------------- ### Configure Plugin in app.json Source: https://docs.customer.io/integrations/sdk/expo/1.x/getting-started Add the customerio-expo-plugin to your app.json configuration. This example shows how to set up Android and iOS push notifications with API credentials. ```json { ... "plugins": [ ... [ "customerio-expo-plugin", { "android": { "googleServicesFile": "./files/google-services.json" }, "ios": { "pushNotification": { "useRichPush": true, "env": { "siteId": "", "apiKey": "", "region": "" } } } } ] ] } ``` -------------------------------- ### Track Push Metrics with expo-notifications Source: https://docs.customer.io/integrations/sdk/expo/1.x/push-notifications/push-metrics Example of fetching the Customer.io payload and tracking push metrics using expo-notifications. This includes listeners for both received notifications and user interactions. ```javascript // Listener called when a push notification is received Notifications.addNotificationReceivedListener(notification => { ... // Fetch Customer.io payload from the push notification const payload = notification.request.trigger.payload CustomerIO.pushMessaging.trackNotificationReceived(payload) ... }); // Receives response when user interacts with the push notification Notifications.addNotificationResponseReceivedListener(response => { ... // Fetch Customer.io payload from the push notification response const payload = response.notification.request.trigger.payload CustomerIO.pushMessaging.trackNotificationResponseReceived(payload) ... }); ``` -------------------------------- ### Fetch and Track Push Metrics with expo-notifications Source: https://docs.customer.io/integrations/sdk/expo/push-notifications/push-metrics Example of fetching the Customer.io payload from push notifications received or responded to using `expo-notifications` and then tracking the corresponding metrics. ```javascript // Listener called when a push notification is received Notifications.addNotificationReceivedListener(notification => { ... // Fetch Customer.io payload from the push notification const payload = notification.request.trigger.payload CustomerIO.pushMessaging.trackNotificationReceived(payload) ... }); // Receives response when user interacts with the push notification Notifications.addNotificationResponseReceivedListener(response => { ... // Fetch Customer.io payload from the push notification response const payload = response.notification.request.trigger.payload CustomerIO.pushMessaging.trackNotificationResponseReceived(payload) ... }); ``` -------------------------------- ### FCM Test Payload Source: https://docs.customer.io/integrations/sdk/expo/1.x/push-notifications/push Example payload for testing FCM (Firebase Cloud Messaging) rich push notifications. Ensure the image URL starts with 'https://'. ```json { "message": { "apns": { "payload": { "CIO": { "push": { "link": "remote-habits://deep?message=hello&message2=world", "image": "https://thumbs.dreamstime.com/b/bee-flower-27533578.jpg" } }, "aps": { "mutable-content": 1, "alert": { "title": "Title of your push goes here!", "body": "Body of your push goes here!" } } } } } } ``` -------------------------------- ### Initialize Customer.io SDK with Configuration Source: https://docs.customer.io/files/expo-sdk-docs.md Initialize the Customer.io SDK with essential configuration options such as API keys, region, and logging level. Ensure configuration is set before initializing the SDK. ```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) }, []) } ``` -------------------------------- ### APNs Test Payload Source: https://docs.customer.io/integrations/sdk/expo/1.x/push-notifications/push Example payload for testing APNs (Apple Push Notification service) rich push notifications. Ensure the image URL starts with 'https://'. ```json { "CIO": { "push": { "link": "remote-habits://deep?message=hello&message2=world", "image": "https://thumbs.dreamstime.com/b/bee-flower-27533578.jpg" } }, "aps": { "mutable-content": 1, "alert": { "title": "Title of your push goes here!", "body": "Body of your push goes here!" } } } ``` -------------------------------- ### Initialize Customer.io SDK with Configuration Source: https://docs.customer.io/integrations/sdk/expo/getting-started/packages-options Initialize the Customer.io SDK with essential configuration options including API keys, region, log level, and in-app messaging settings. Ensure configuration is provided before SDK initialization. ```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) }, []) } ``` -------------------------------- ### Initialize the SDK Source: https://docs.customer.io/integrations/sdk/expo/1.x/getting-started Initialize the Customer.io SDK with your Site ID, API Key, and optionally specify the region. This code should be placed in your main App file. ```javascript import React, {useEffect} from 'react'; import { CustomerIO, CustomerIOEnv, Region } from 'customerio-reactnative'; const App = () => { useEffect(() => { const env = new CustomerIOEnv() env.siteId = "YourSiteId" env.apiKey = "YourAPIKey" // Region is optional, defaults to Region.US. // Use Region.EU for EU-based workspaces. env.region = Region.US CustomerIO.initialize(env) }, []) } ``` -------------------------------- ### Manual Initialization Configuration in app.json Source: https://docs.customer.io/integrations/sdk/expo/getting-started/auth Set up the app.json file for manual initialization of the Customer.io SDK, specifying configurations for Android and iOS environments. ```json { "expo": { "plugins": [ [ "customerio-expo-plugin", { "android": { "googleServicesFile": "./files/google-services.json", "setHighPriorityPushHandler": true }, "ios": { "pushNotification": { "useRichPush": true, "env": { "cdpApiKey": "", "region": "us" } } } } ] ] } } ``` -------------------------------- ### Inbox Message Payload Example Source: https://docs.customer.io/integrations/sdk/expo/in-app-messages/inbox An example of the JSON payload structure for an inbox message. This includes message metadata and custom properties for display. ```json { "messageId": "1234567890", "sentAt": "2026-02-05T12:00:00Z", "expiresAt": "2026-02-05T12:00:00Z", "opened": false, "topics": ["orders", "shipping"], "type": "order_shipped", "properties": { "title": "Hey Cool Person, your order shipped!", "body": "You can track your order #1234567890 here:", "link": "https://example.com/orders/1234567890" } } ``` -------------------------------- ### Initialize Customer.io SDK with CioConfig Source: https://docs.customer.io/integrations/sdk/expo/whats-new/2.x-upgrade Use CioConfig to initialize the SDK, replacing the older CustomerioConfig. Pay attention to changes like migrationSiteId and the simplified inApp configuration. ```javascript import { CioLogLevel, CioRegion, CustomerIO, CioConfig } from 'customerio-reactnative'; const config: CioConfig = { cdpApiKey: 'cdp_api_key', // Mandatory migrationSiteId: 'site_id', // For migration region: CioRegion.US, logLevel: CioLogLevel.Debug, trackApplicationLifecycleEvents: true, inApp: { siteId: 'site_id', // this removes the use of enableInApp and simplifies in-app configuration } }; CustomerIO.initialize(config) ``` -------------------------------- ### Initialize SDK with Proxy Configuration Source: https://docs.customer.io/integrations/sdk/expo/getting-started/packages-options Initialize the Customer.io SDK with custom apiHost and cdnHost values to proxy requests through your domain. Ensure these hosts are set to the same URL. The cdpApiKey can be a placeholder for client-side initialization. ```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); }, []); ``` -------------------------------- ### Update Expo Plugin to Version 3.0.0 Source: https://docs.customer.io/files/expo-sdk-docs.md Install version 3.0.0 or later of the customerio-expo-plugin. This version requires the React Native new architecture. ```bash npm install customerio-expo-plugin@3.0.0 # or yarn add customerio-expo-plugin@3.0.0 ``` -------------------------------- ### Configure Customer.io SDK with Manual Initialization Source: https://docs.customer.io/integrations/sdk/expo/quick-start-guide Set your CDP API Key and Site ID as environment variables in your `.env` file for manual initialization of the Customer.io SDK. This method is suitable for older Expo versions or when manual control is preferred. ```env EXPO_PUBLIC_CDP_API_KEY= EXPO_PUBLIC_SITE_ID= ``` -------------------------------- ### Manual Initialization in App Code Source: https://docs.customer.io/integrations/sdk/expo/getting-started/auth Initialize the Customer.io SDK manually in your app's code using the provided configuration object. Ensure all mandatory fields are included. ```typescript import { CioRegion, CustomerIO, CioConfig } 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, inApp: { siteId: '', }, }; CustomerIO.initialize(config); }, []); }; ``` -------------------------------- ### Run Expo Prebuild Command Source: https://docs.customer.io/integrations/sdk/expo/1.x/getting-started Execute the `expo prebuild` command to prepare your project after configuring the SDK. Use the `--clean` flag to remove existing iOS and Android folders before prebuilding. ```shell # Run prebuild expo prebuild # Delete ios and android folders before prebuild expo prebuild --clean ``` -------------------------------- ### Get Inbox Instance Source: https://docs.customer.io/integrations/sdk/expo/in-app-messages/inbox Access the inbox functionality through the `inbox()` method on the in-app messaging module. This is the entry point for managing inbox messages. ```javascript const inbox = CustomerIO.inAppMessaging.inbox(); ``` -------------------------------- ### Get Push Permission Status Source: https://docs.customer.io/integrations/sdk/expo/1.x/push-notifications/push Call this method to retrieve the current push notification permission status for the user. It returns a promise that resolves with the status as a string. ```javascript CustomerIO.getPushPermissionStatus().then(status => { console.log("Push permission status is - " + status) }) ``` -------------------------------- ### Update Expo Plugin and React Native Dependency Source: https://docs.customer.io/files/expo-sdk-docs.md Install version 3.3 of the customerio-expo-plugin and version 6.4.0 of customerio-reactnative. This is recommended for improved push delivery metric tracking on iOS. ```bash npm install customerio-expo-plugin@3.3 customerio-reactnative@6.4.0 # or yarn add customerio-expo-plugin@3.3 customerio-reactnative@6.4.0 ``` -------------------------------- ### Configure SDK with Site ID in app.json Source: https://docs.customer.io/integrations/sdk/expo/getting-started/auth Use this JSON configuration within your app.json file to automatically initialize the Customer.io SDK with your site ID for Expo 53 and later. Ensure you replace placeholder values with your actual API key and region. ```json { "expo": { "plugins": [ [ "customerio-expo-plugin", { "config": { "cdpApiKey": "", "region": "us", "siteId": "" } } ] ] } } ``` -------------------------------- ### Prebuild Expo Application for Native Files Source: https://docs.customer.io/integrations/sdk/expo/quick-start-guide Run this command after configuring your `app.json` to generate the native files required for push notifications and in-app messaging. This step is crucial for the Customer.io plugin to function correctly. ```bash npx expo prebuild ``` -------------------------------- ### Fetch Device Token Source: https://docs.customer.io/integrations/sdk/expo/push-notifications/push Retrieves the currently stored device token. This method returns a promise that resolves to the APN/FCM token as a string. Use this token within your app, for example, by saving it to state. ```javascript let token = await CustomerIO.pushMessaging.getRegisteredDeviceToken() if (token) { // Use the token as required in your app for example save in a state setDeviceToken(token); } ``` -------------------------------- ### Get Push Notification Permission Status Source: https://docs.customer.io/files/expo-sdk-docs.md Retrieve the current push notification permission status for the user using the `CustomerIO.getPushPermissionStatus()` method. This is useful for checking existing permissions without prompting the user. ```APIDOC ## Get User's Push Notification Permission Status ### Description Retrieves the current authorization status for push notifications for the user. This method returns a promise that resolves with the status without displaying a prompt. ### Method `CustomerIO.getPushPermissionStatus()` ### Returns A promise that resolves with a string indicating the current authorization status: - `"Granted"`: Push permission is granted. - `"Denied"`: App is not authorized to receive push notifications. - `"NotDetermined"`: Push permission status is not determined (iOS only). ### Request Example ```javascript CustomerIO.getPushPermissionStatus().then(status => { console.log("Push permission status is - " + status) }) ``` ``` -------------------------------- ### Rebuild App After Configuration Source: https://docs.customer.io/integrations/sdk/expo/push-notifications/app-groups After updating your `customerio-expo-plugin` configuration with the `appGroupId`, run this command to prebuild your app and apply the changes. ```bash npx expo prebuild --clean ``` -------------------------------- ### Handle Custom Actions in Inline In-App Messages Source: https://docs.customer.io/files/expo-sdk-docs.md Register a callback with your inline view to handle custom actions when a user taps a button or the message. This example demonstrates handling different 'actionValue' cases. ```jsx import { InlineInAppMessageView } from 'customerio-reactnative'; function MyComponent() { const handleActionClick = (message, actionValue, actionName) => { // Perform some logic when people tap an action button. // Example code handling button tap: switch (actionValue) { case "enable-auto-renew": // Perform the action to enable auto-renew enableAutoRenew(actionName); break; // You can add more cases here for other actions default: // Handle unknown actions or do nothing console.log("Unknown action:", actionValue); } }; return ( ); } ``` -------------------------------- ### Auto-initialization Configuration in app.json Source: https://docs.customer.io/integrations/sdk/expo/getting-started/auth Configure the Customer.io SDK for auto-initialization by adding your API keys and site IDs to the app.json file. This method is available for Expo 53+. ```json { "expo": { "plugins": [ [ "customerio-expo-plugin", { "config": { "cdpApiKey": "", "region": "us", // use "eu" if in EU region "siteId": "", // Required for in-app messaging "migrationSiteId": "" // Required if migrating from an earlier version }, "android": { "googleServicesFile": "./files/google-services.json", "setHighPriorityPushHandler": true }, "ios": { "pushNotification": { "useRichPush": true } } } ] ] } } ``` -------------------------------- ### Send Custom Lifecycle Event Source: https://docs.customer.io/integrations/sdk/expo/tracking/lifecycle-events Use the `track` method to send custom lifecycle events, following the 'Application EventName' convention. This example shows how to track an 'Application Crashed' event with associated properties. ```javascript CustomerIO.track("Application Crashed", { url: "/page/in/app" }); ``` -------------------------------- ### Configure Push Notifications (Manual initialization) Source: https://docs.customer.io/integrations/sdk/expo/quick-start-guide Configure push notifications for iOS and Android by updating your `app.json` file with the manual initialization plugin configuration. ```json { "expo": { ...Other options "plugins": [ [ "customerio-expo-plugin", { "android": { "googleServicesFile": "./files/google-services.json" }, "ios": { "pushNotification": { "useRichPush": true, "env": { "cdpApiKey": "", "region": "us" // us or eu } } } } ] ] } } ``` -------------------------------- ### Configure Location Tracking Mode (Manual Initialization) Source: https://docs.customer.io/integrations/sdk/expo/tracking/location Import `CioLocationTrackingMode` and set the `trackingMode` in your `CioConfig` object for manual initialization. This allows programmatic control over location capture. ```javascript import { CustomerIO, CioConfig, CioLocationTrackingMode } from 'customerio-reactnative'; const config: CioConfig = { cdpApiKey: 'your-cdp-api-key', // ...other config options location: { trackingMode: CioLocationTrackingMode.Manual, }, }; CustomerIO.initialize(config); ``` -------------------------------- ### Custom Push Click Handling (React Native) Source: https://docs.customer.io/integrations/sdk/expo/1.x/push-notifications/push-metrics Use this example with `react-native-push-notification` to receive callbacks when users click a push notification. This allows for processing custom data within the push payload. Remember to call `completion()` after processing. ```javascript import { Notifications } from 'react-native-notifications'; Notifications.events().registerNotificationOpened((notification: Notification, completion) => { // Process custom data attached to payload, if you need: let pushPayload = notification.payload; // Important: When you're done processing the push notification, you're required to call completion(). // Even if you do not process a push, this is still a requirement. completion(); }); ``` -------------------------------- ### Enable Deep Linking in Killed State for iOS Expo Source: https://docs.customer.io/integrations/sdk/expo/getting-started/troubleshooting Configure the Expo plugin to handle deep links when the iOS app is in a killed state. This is a workaround for a known issue where the native click event fires before the React app lifecycle starts. ```json { "plugins": [ [ "customerio-expo-plugin", { "...": "other config" "ios": { "...": "other config" "pushNotification": { "...": "other config" "handleDeeplinkInKilledState": true, "...": "other config" } } } ] ] } ``` -------------------------------- ### Configure Customer.io Expo Plugin with Manual Initialization Source: https://docs.customer.io/integrations/sdk/expo/getting-started/packages-options This configuration is for manual SDK initialization. Native settings are configured in app.json, and runtime settings are managed via CustomerIO.initialize() in your React Native app code. Ensure 'useFrameworks' in 'expo-build-properties' matches the 'customerio-expo-plugin' setting if both are specified. ```json { "plugins": [ [ "expo-build-properties", { "ios": { "deploymentTarget": "15.1", "useFrameworks": "static" } } ], [ "customerio-expo-plugin", { "android": { "googleServicesFile": "./files/google-services.json" }, "ios": { "useFrameworks": "static", "appleTeamId": "YOUR_TEAM_ID", "pushNotification": { "provider": "fcm", "googleServicesFile": "", "useRichPush": true, "appGroupId": "group.com.example.myapp.cio", "env": { "cdpApiKey": "", "region": "us" } } } } ] ] } ```