Overview

This section shows how to install the CleverTap React Native SDK in your Expo app, configure the CleverTap Expo plugin, and track your first user event—all within the managed Expo workflow.

Set Up CleverTap in Expo App

Set up CleverTap in your Expo project by installing dependencies and updating the app.jsonfile. The CleverTap Expo Plugin automates native configurations and maintains your project in the managed workflow while enabling features such as push notifications and In-App messaging.

Installation and Configuration

To start using CleverTap Expo, install the necessary dependencies and update your project configuration.

Install CleverTap React Native SDK

npm install clevertap-react-native

Install CleverTap Expo Plugin

npx expo install @clevertap/clevertap-expo-plugin

🚧

Credentials and Access

The CleverTap Account ID and CleverTap Token appear as Project ID and Project Token on the CleverTap dashboard.

To view these, go to the CleverTap dashboard, then navigate to Settings > Project.

Only users with Admin access can view the Passcode and Project Token. Member and Creator roles do not have permission to access these credentials.

Add Region Code

To learn more about adding a region code, refer to Region Codes.

Add Plugin Configuration in app.json

Modify your app.json file to include the CleverTap Expo Plugin configuration:

{
  "expo": {
    "plugins": [
      [
        "@clevertap/clevertap-expo-plugin",
        {
          "accountId": "YOUR_ACCOUNT_ID", // Required: CleverTap Account ID
          "accountToken": "YOUR_ACCOUNT_TOKEN", // Required: CleverTap Account Token
          "accountRegion": "YOUR_REGION_CODE", // Required: CleverTap account region (e.g., "in1", "us1")
          "disableAppLaunchedEvent": false, // Optional: Disable "App Launched" event
          "logLevel": 0, // Logging level (-1: off, 0: minimal, 2: debug, 3: verbose)
          "encryptionLevel": 1, // Optional: Encrypt PII data
          "proxyDomain": "analytics.example.com", // Optional: Custom proxy domain
          "spikyProxyDomain": "spiky.example.com", // Optional: Proxy for push impressions
          "customIdentifiers": "Email,Phone", // Required if using custom IDs

          "android": {
            "features": {
              "enablePush": true, // Required: Enable push notifications
              "enablePushTemplates": true, // Optional: Enable rich push templates
              "enableInApp": true, // Required: Enable in-app messages
              "enableInbox": true, // Required: Enable App Inbox
              "enableMediaForInAppsInbox": true, // Optional: Enable media in inbox & in-apps
              "enableInstallReferrer": true, // Optional: Enable install tracking
              "enableHmsPush": false, // Required for Huawei push (HMS)
              "enableGoogleAdId": false // Optional: Use Google Ad ID
            },
            "customNotificationSound": ["notification.mp3"], // Optional: Custom sound files
            "backgroundSync": "1", // Optional: Enable background push sync
            "defaultNotificationChannelId": "default_channel", // Required: Default push channel
            "inAppExcludeActivities": "SplashActivity", // Optional: Exclude in-apps from screens
            "sslPinning": "1", // Optional: Enable SSL pinning
            "registerActivityLifecycleCallbacks": true // Recommended: Track session events
          },

          "ios": {
            "mode": "development", // Required: APNs mode ("development" or "production")
            "disableIDFV": false, // Optional: Disable IDFV collection
            "enableFileProtection": true, // Optional: Enable file security
            "enableURLDelegateChannels": [0, 1, 2], // Optional: Handle deep links
            "notifications": {
              "enableRichMedia": true, // Optional: Enable rich push media
              "enablePushImpression": true, // Optional: Track push impressions
              "enablePushTemplate": true, // Optional: Enable push templates
              "enablePushInForeground": true, // Optional: Show push when app is open
              "iosPushAppGroup": "group.com.clevertap.expoDemo", // Required for push tracking
              "notificationCategories": [
                {
                  "identifier": "CTNotification",
                  "actions": [{ "identifier": "action1", "title": "title1" }] // Optional: Custom actions
                }
              ]
            }
          }
        }
      ]
    ]
  }
}

Configure app.json

The CleverTap Expo plugin supports a wide range of configuration options to customize your integration:

Core Configuration Options

Platform-Specific Configurations

Configure platform-specific settings to enable features such as push notifications, In-App messaging, and App Inbox.

• Android Specific Configuration
• iOS Specific Configuration

Prebuild your application

Run the following command to generate the native files required for the CleverTap Expo plugin:

npx expo prebuild

Use npx expo prebuild --clean to regenerate native code by deleting existing native directories. This is useful for major config or native code changes to ensure a fresh build.

Import and use CleverTap React Native SDK APIs in your application

After setting up the CleverTap Expo Plugin, import the CleverTap React Native SDK so you can use CleverTap's features in your mobile app, such as tracking events and user activity. Use the following APIs to record events and update user location:

const CleverTap = require('clevertap-react-native');

// Track a custom event
CleverTap.recordEvent('testEvent');

// Update user location
CleverTap.setLocation(34.15, -118.2);

Testing Your Integration

To verify your CleverTap integration is working correctly, follow these steps:

1. Install and run your app.
2. Call the onUserLogin method with a test user profile.
3. Record a few test events.
4. Check the CleverTap dashboard to ensure the user profile and events are being tracked.
5. Send a test push notification campaign from the CleverTap dashboard to verify delivery.

This helps validate that CleverTap is integrated correctly and collecting user data as expected.

Android Specific Configuration

Use the following settings to configure CleverTap for Android, including support for Firebase Cloud Messaging (FCM), App Inbox, and notification customization.

Android Configuration Options

Additional Android Configurations

Configure additional Android-specific settings in your app.json file to ensure CleverTap functions properly and supports push notifications, background services, and custom notification icons.

Android Permissions

Add the following permissions to app.json to enable CleverTap's core functionality:

{
  "expo": {
    "android": {
      "permissions": [
        "android.permission.ACCESS_NETWORK_STATE",
        "android.permission.INTERNET",
        "android.permission.POST_NOTIFICATIONS"
      ]
    }
  }
}

Permission Descriptions

The following Android permissions are required for CleverTap to function properly in your Expo app:

• ACCESS_NETWORK_STATE – Allows CleverTap to check network connectivity before sending data.
• INTERNET – Enables CleverTap to communicate with servers for data exchange.
• POST_NOTIFICATIONS – Required for Android 13+ devices to display push notifications.

Additional Android Configuration for Push Notifications (Optional)

After setting up the basic configuration in app.json, configure platform-specific settings to ensure push notifications work correctly. These steps cover Firebase Cloud Messaging (FCM), Huawei Mobile Services (HMS) Push, and custom notification icons.

Firebase Cloud Messaging (FCM) Configuration

This setting is required when integrating Firebase features such as Firebase Cloud Messaging (FCM) for push notifications, Firebase Analytics, App verification, and so on. Place the google-services.json file in your project assets folder and update app.json as follows:

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

Huawei Messaging Services (HMS) Push Configuration

If HMS Push is enabled (android.features.enableHmsPush = true), place agconnect-services.json in the assets folder. No additional configuration is required in theapp.json, but ensure the file exists for HMS Push to work.

Custom Notification Icon

Customize your push notification icon by adding the following to app.json:

{
  "expo": {
    "notification": {
      "icon": "./assets/notification-icon.png"
    }
  }
}

The CleverTap Expo Plugin automatically applies this icon to all CleverTap-created notifications. For best results, ensure the icon follows Android notification icon guidelines.

For common issues and troubleshooting, refer to FAQs for Android.

iOS Specific Configuration

Use the following settings to configure CleverTap for iOS, enabling APNs, push notifications, rich media, and App Groups for seamless user engagement.

iOS Configuration Options

Additional iOS Configuration for Push Impressions (Optional)

After configuring the basic settings in app.json, create an App Group Identifier to enable data sharing between your main app and the Notification Service Extension. The prebuild phase assigns this app group to both the main target and the Notification Service Extension target.

Update app.json

"ios": {
  "notifications": {
    "enablePushImpression": true,
    "iosPushAppGroup": "group.com.clevertap.expoDemo"
  }
}

Within your app, store profile data such as Name, Identity, Email, and Phone number in the UserDefaultsfile. The Notification Service Extension (NSE) retrieves this stored data and sends it to CleverTap’s servers.

For detailed implementation, refer to the iOS Push Impression.

Example Code for Storing Profile Data in UserDefaults

userDefaults.set("CTProfileName", 'testUserA1', "group.com.clevertap.expoDemo", (err, data) => {
  if (!err) console.log('Saved CTProfileName: testUserA1');
});
// Store additional profile data here

FAQs: Recommendations for Android

Find answers to common questions about CleverTap's Android configuration, including file placements, push notifications, and feature dependencies.

File Locations

Q: Where should I place the agconnect-services.json file for Huawei Push Services?

Place it at the root level of your assets/ folder. This is required for HMS push integration to function properly.

Q: Can I store notification sound files in subdirectories?

No, all custom notification sound files must be stored at the root level of your assets/ folder. Subdirectories are not supported.

Q: Where can I store google-services.json and notification icons?

These files can be placed in subdirectories within assets/, but they must be properly referenced in app.json.

Google Services Configuration

Q: Is google-services.json required for Firebase Cloud Messaging (FCM)?

Yes, if you enable FCM (android.features.enablePush = true), you must include google-services.json in your project.

Q: Where should I place google-services.json?

Place it in the assets/ folder and reference it in app.json as follows:

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

Q: How do I obtain google-services.json?

Download it from your Firebase console project settings.

Q: How can I verify that FCM is working correctly?

After integration, send a test push notification from the CleverTap dashboard to confirm the setup.

Huawei Push Services

Q: Is agconnect-services.json required for HMS push notifications?

Yes, this file is required if you enable HMS push (android.features.enableHmsPush = true).

Q: Where should I store agconnect-services.json?

Place it at the root level of your assets/ folder.

Q: Do I need to reference agconnect-services.json in app.json?

No, unlike google-services.json, you do not need to reference it in app.json, but the file must be present.

Q: How do I obtain agconnect-services.json?

Generate it from the Huawei AppGallery Connect console.

Custom Notification Sounds

Q: What file formats are supported for notification sounds?

You can use .mp3, .wav, or .ogg files.

Q: Where should I store custom notification sounds?

Store them at the root level of your assets/ folder. Subdirectories are not supported.

Q: How do I register a notification channel with a custom sound?

Use the following code in your app after running expo prebuild:

CleverTap.createNotificationChannel(
  "channel_id",         // Unique ID for the notification channel
  "Channel Name",       // Visible name of the channel in system settings
  "Channel Description",// Description of the channel's purpose
  5,                    // Importance level (1-5, with 5 being highest)
  true,                 // Enable vibration for notifications in this channel
  "sound_file.mp3"      // Custom sound file for notifications (must be in assets folder)
);

Custom Notification Icons

Q: What are the requirements for a custom notification icon?

The icon must follow Android notification icon guidelines.

Q: How do I configure a custom notification icon in app.json?

Add the following to app.json:

{
  "expo": {
    "notification": {
      "icon": "./assets/notification-icon.png"
    }
  }
}

This sets a custom icon that will appear in the Android notification drawer when your app receives a push notification.

Feature Dependencies

Q: What should I enable to use push notification templates?

You must enable android.features.enablePush for push templates to work.

Q: How do I enable media support in In-App messages and App Inbox?

Enable android.features.enableMediaForInAppsInbox to display video content in In-App messages and App Inbox.