@clevertap/clevertap-expo-plugin v0.0.2

CleverTap Expo Plugin

Beta Status Notice: This plugin is currently in beta. While it is fully functional and has undergone testing, you may encounter occasional issues. We welcome your feedback to improve the plugin before its stable release.

👋 Introduction

Learn how to integrate the CleverTap SDK into your Expo React Native application. This guide explains how to set up and configure CleverTap's features using the Expo plugin.

For more information check out our website and documentation.

To get started, sign up here.

📋 Overview

Expo is a framework and platform built around React Native that helps you develop, build, and deploy React Native applications quickly. The CleverTap Expo plugin provides a streamlined way to integrate the CleverTap React Native SDK into your Expo application without writing native code. It enables customization during the prebuild phase of managed workflow builds, eliminating the need to eject to a bare workflow. Specifically tailored for CleverTap integration, this plugin simplifies the setup by automatically generating and configuring the required native code files to ensure the CleverTap React Native SDK functions seamlessly. Consider this plugin as an automated way to implement the required native configurations, saving you from manually writing platform-specific code for CleverTap integration.

🧩 Compatibility Matrix

To ensure smooth integration of the CleverTap Expo plugin, please reference the following compatibility matrix. This table outlines the supported versions of CleverTap Expo Plugin, Expo SDK, React Native, and the CleverTap React Native SDK that work together effectively.

🚀 Install and Integration

Step 1: Install the CleverTap React Native SDK

npm install clevertap-react-native

Step 2: Install the CleverTap Expo Plugin

npx expo install @clevertap/clevertap-expo-plugin

Step 3: Add the plugin to your app.json

In your app.json file, add the CleverTap Expo Plugin configuration. Below is an example configuration showing both mandatory and optional parameters with their default values where applicable:

app.json

{
  "expo" : {
    "plugins": [
      [
        "@clevertap/clevertap-expo-plugin",
        {
          "accountId": "WWW-AAA-BBBB",
          "accountToken": "AAA-BBB-CCCC",
          "accountRegion": "eu1",
          "disableAppLaunchedEvent": false,
          "logLevel": 0, 
          "encryptionLevel": 1, 
          "proxyDomain": "analytics.example.com", 
          "spikyProxyDomain": "spiky.example.com",
          "customIdentifiers": "Email,Phone", 
          "android": {
            "features": {
              "enablePush": true, 
              "enablePushTemplates": true, 
              "enableInApp": true, 
              "enableInbox": true, 
              "enableMediaForInAppsInbox": true, 
              "enableInstallReferrer": true, 
              "enableHmsPush": false, 
              "enableGoogleAdId": false 
            },
           "customNotificationSound": ["notification_sound.mp3", "alert_tone.mp3","reminder. mp3"], 
           "backgroundSync": "1", 
           "defaultNotificationChannelId": "default_channel", 
           "inAppExcludeActivities": "SplashActivity", 
           "sslPinning": "1", 
           "registerActivityLifecycleCallbacks": true 
          },
           "ios": {
            "mode": "development", //Mandatory
            "disableIDFV": true, //Optional, default: false
            "enableFileProtection": true, //Optional, default: false
            "enableURLDelegateChannels": [ 0, 1, 2 ], //Optional, default: null
            "notifications": {
              "enableRichMedia": true, 
              "enablePushImpression": true, 
              "enablePushTemplate": true, 
              "enablePushInForeground": true, 
              "iosPushAppGroup": "group.com.clevertap.expoDemo", 
              "notificationCategories": [
                {
                  "identifier": "CTNotification",
                  "actions": [ { "identifier": "action1",  "title": "title1" } ]
                }
              ] 
            }
          }
        }
      ]
    ]
  }
  }

Step 4: Configure your app.json

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

Core Configuration Options

Android-Specific Configuration

iOS-Specific Configuration

Step 5: Additional Android Configurations

Configure additional Android-specific settings in your app.json file.

Step 5.1: Android Permissions

To ensure that CleverTap functions properly, add the required permissions to your app.json:

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

• ACCESS_NETWORK_STATE: Allows CleverTap to check network connectivity before attempting data transfers
• INTERNET: Required for CleverTap to send and receive data from servers
• POST_NOTIFICATIONS: Required for Android 13+ devices to display push notifications

Step 6: Additional Android Configuration for Push Notifications (Optional)

After setting up the basic configuration in your app.json, you may need additional platform-specific setup to ensure proper functioning of push notifications on Android devices. The following sub-steps will guide you through configuring Firebase Cloud Messaging (FCM), Huawei Mobile Services (HMS) Push, and custom notification icons.

Step 6.1: Firebase Cloud Messaging (FCM) Configuration

For Firebase Cloud Messaging on Android, place your google-services.json file in the assets folder and add the following to your app.json:

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

Step 6.2: Huawei Messaging Services (HMS) Push Configuration

If you've enabled HMS Push support by setting android.features.enableHmsPush to true, place your agconnect-services.json file in the assets folder of your project. No specific property needed for agconnect-services.json, just ensure it's placed in the assets folder.

Step 6.3: Custom Notification Icon

You can customize your notification icon using the standard Expo configuration. Add the following to your app.json:

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

The CleverTap Expo plugin will automatically use this icon for notifications. Ensure that your icon follows Android's guidelines for notification icons.

Step 7: Additional iOS Configuration for Notification Extensions

Step 7.1: Additional iOS Configuration for Provisioning Profiles Setup When Extensions Are Enabled

After configuring the basic settings in your app.json, if you want to use Notification Service Extension or Notification Content Extension, you must add the extra property inside app.json as shown below. Ensure that you have created the appropriate App IDs and provisioning profiles for each extension.

{
  "expo": {
   ….
    "extra": {
      "eas": {
        "projectId": “xxxx”,
        "build": {
          "experimental": {
            "ios": {
              "appExtensions": [
                {
                  "targetName": "NotificationService",
                  "bundleIdentifier": “xxxx”,
                  "entitlements": {
                    "com.apple.security.application-groups": [
                      "group.xxxx”
                    ]
                  }
                },
                {
                  "targetName": "NotificationContent",
                  "bundleIdentifier": “xxxx”,
                  "entitlements": {
                    "com.apple.security.application-groups": [
                      "group.xxxx”
                    ]
                  }
                }
              ]
            }
          }
        }
      }
    }
…
}

Step 7.2: Additional iOS Configuration for Push Impressions (Optional)

After configuring the basic settings in your app.json, the next step is to create an App Group Identifier to enable data sharing between your main app and the Notification Service Extension. This app group will be assigned to both the main target and the Notification Service Extension target during the prebuild phase. For detailed steps on App Group configuration, refer to this (documentation)https://developer.apple.com/documentation/xcode/configuring-app-groups.

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

Within your app, you'll need to save profile data—such as Name, Identity, Email, and Phone in UserDefaults. Our example app includes sample code demonstrating this process. The stored profile data will then be retrieved by the Notification Service Extension (NSE) to send it to CleverTap's servers. You can find more details here: React Native Push Notification – (iOS Push Impression)https://developer.clevertap.com/docs/react-native-push-notification#push-impression-in-ios.

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

Step 8: Prebuild your application

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

npx expo prebuild

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

Step 9: Import and use CleverTap React Native SDK APIs in your application

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

CleverTap.recordEvent('testEvent');

CleverTap.setLocation(34.15, -118.2);

Step 10: Testing Your Integration

To verify your CleverTap integration is working properly:

• Install and run your app
• Call the onUserLogin method with a test user profile
• Record a few test events
• Check the CleverTap dashboard to ensure the user profile and events are being tracked
• Test push notifications by sending a test campaign from the CleverTap dashboard

📣 Important Notes and Recommendations for Android

File Locations

• HMS Configuration File: The agconnect-services.json file must be placed at the root level of your project's assets folder for HMS push integration to function correctly.
• Notification Sound Files: All custom notification sound files must be placed at the root level of your project's assets folder. These cannot be in subdirectories.
• Other Files: Files like google-services.json and notification icons can be placed in subdirectories within your assets folder if referenced properly in your app.json configuration.

Google Services Configuration

• google-services.json: This file is required if you enable Firebase Cloud Messaging (android.features.enablePush = true). It must be placed in your project's assets folder and referenced in app.json using the googleServicesFile property.
• Obtaining the File: Download this file from your Firebase console project settings. Without a valid configuration, push notifications will not work correctly.
• Testing: After integration, send a test push from the CleverTap dashboard to verify proper setup.

Huawei Push Services

• agconnect-services.json: Required if you enable Huawei Mobile Services push (android.features.enableHmsPush = true). This file must be placed at the root level of your project's assets folder.
• No Explicit Reference Needed: Unlike google-services.json, you don't need to reference this file in app.json, but it must be present in the assets folder.
• AppGallery Connect: Generate this file from the Huawei AppGallery Connect console for your application.

Custom Notification Sounds

• Sound File Formats: Use .mp3, .wav, or .ogg files for notification sounds.
• Asset Placement: Place sound files at the root level of your assets folder. Subdirectories are not supported for sound files.
• Channel Registration: After the prebuild, you must register a notification channel with your custom sound in your application code:

  CleverTap.createNotificationChannel(
   "channel_id",
   "Channel Name",
   "Channel Description",
   5, 
   true, 
   "sound_file.mp3" 
  );

Custom Notification Icons

• Icon Requirements: Your notification icon should follow Android's guidelines. More info here

• Icon Configuration: Use Expo's standard notification configuration in app.json:

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

Feature Dependencies

• Push Templates: To use push templates, android.features.enablePush must also be enabled. Push templates are not supported through custom implementations.

• Media Support: Enable android.features.enableMediaForInAppsInbox for video content in in-app messages and app inbox.

🆕 Changelog

Refer to the CleverTap Expo plugin Change Log.

🎬 Sample App

To see a React Native Expo app running with the CleverTap SDK, check out our sample app on GitHub.

📝 Beta Feedback

Since this plugin is in beta, we highly value your feedback to improve its stability and functionality. If you encounter any issues, have suggestions, or want to share your experience with the plugin, please:

1. Submit detailed bug reports through GitHub Issues
2. Include specific steps to reproduce any problems
3. Share your environment details (Expo version, React Native version, device information)
4. Suggest enhancements or features you'd like to see in future releases

Your input is crucial for the success of this plugin and will help us prepare for the stable release.

⁉️ Help and Questions?

If you have questions or concerns, you can reach out to the CleverTap support team from the CleverTap Dashboard.