This Expo plugin simplifies the integration of WebEngage into your Expo project.

It automatically applies the required native Android and iOS configuration during the Expo build process, so you do not need to manually modify native Android or iOS source files for the WebEngage integration.

What this guide completes:

• Installation: Adding webengage-expo and react-native-webengage to your project.
• Configuration: Setting your WebEngage License Code, environment, and push mode via the Expo config plugin.
• Build: Generating the native projects and running your app.
• Verification: Confirming the WebEngage SDK initialized successfully.

The plugin works together with react-native-webengage:

• react-native-webengage provides the WebEngage JavaScript APIs used in your application.
• webengage-expo configures the native Android and iOS projects during the Expo build.

Prerequisites

Before you begin, ensure you have the following:

• An existing Expo application
• For EAS Build: an active EAS account and the eas-cli installed

1. Locate your WebEngage License Code

1. Log in to your WebEngage Dashboard.
2. Navigate to Account Settings > Integration.
3. Copy your License Code.

You will use this value for the ios.WEGLicenseCode and android.manifest.com.webengage.sdk.android.key configuration keys below.

Installation

Step 1 — Install webengage-expo

npm install webengage-expo

yarn add webengage-expo

Step 2 — Install react-native-webengage

react-native-webengage is the WebEngage React Native SDK that provides JavaScript APIs for event tracking, user management, and other WebEngage functionality.

npm install react-native-webengage

yarn add react-native-webengage

How the Plugin Works

When you build your Expo application, Expo runs the WebEngage config plugin and applies the required configuration to the generated native Android and iOS projects.

The flow is:

Expo Application
       │
       ├── react-native-webengage
       │       └── WebEngage JavaScript APIs
       │
       └── webengage-expo
               └── Native WebEngage configuration
                    ├── Android
                    └── iOS

You do not need to manually edit the generated Android or iOS source files for the WebEngage integration.

Configuration

Add the plugin to your app.json or app.config.js under the plugins key:

{
  "expo": {
    "name": "YourApp",
    "slug": "your-app",
    "ios": {
      "bundleIdentifier": "com.yourcompany.yourapp"
    },
    "android": {
      "package": "com.yourcompany.yourapp"
    },
    "plugins": [
      [
        "./node_modules/webengage-expo/src/withWebEngage.js",
        {
          "push": {
            "mode": "development"
          },
          "ios": {
            "WEGLicenseCode": "YOUR_LICENSE_CODE",
            "WEGEnvironment": "DEFAULT",
            "WEGLogLevel": "VERBOSE",
            "WEGAutoRegister": true
          },
          "android": {
            "manifest": {
              "com.webengage.sdk.android.key": "YOUR_LICENSE_CODE",
              "com.webengage.sdk.android.environment": "us",
              "com.webengage.sdk.android.debug": true
            }
          }
        }
      ]
    ]
  }
}

iOS

Android

Build Your App

Config plugins only take effect when native code is generated. After installing the packages and adding the plugin configuration, build your app:

Using EAS Build

If you are using EAS Build, you do not need to run expo prebuild manually. EAS applies the configured Expo plugins during the build.

npm install -g eas-cli
eas build:configure

eas build --platform ios
eas build --platform android

Local Development Build

If you want to generate the native projects and run the application locally:

npx expo prebuild
npx expo run:ios
npx expo run:android

When should I rebuild?

You must create a new native build whenever you change:

• WebEngage plugin configuration in app.json or app.config.js
• Native dependencies
• Native configuration

JavaScript-only changes can be delivered through OTA updates if your application is configured to use Expo Updates.

Verify Integration

After building and running your app, confirm that the WebEngage SDK initialized successfully.

• Android: Look for WebEngage Successfully Initialized in Android Studio Logcat.
• iOS: Look for WebEngage SDK Initialized in the Xcode console.

Usage

After completing the setup, you can use the react-native-webengage JavaScript APIs in your application.

Track Events

import WebEngage from 'react-native-webengage';

const webengage = new WebEngage();

webengage.track('Product Viewed', {
  product_id: 'SKU-001',
  product_name: 'Running Shoes',
  price: 79.99,
});

User Identification

import WebEngage from 'react-native-webengage';

const webengage = new WebEngage();

// Identify a logged-in user
webengage.user.login('user-id-123');
webengage.user.setFirstName('John');
webengage.user.setEmail('[email protected]');

// Log out
webengage.user.logout();

For the full JavaScript API reference, use the table below — all of it applies exactly as documented, since webengage-expo only changes native setup, not the JavaScript API:

Supported Environments

Why Expo Go is not supported

Native modules such as WebEngage are not included in Expo Go. Expo Go is a precompiled application and cannot include third-party native SDKs.

To use WebEngage, create a development build or generate the native projects using the prebuild workflow.

For example:

npx expo prebuild

This generates the native android and ios directories and applies the WebEngage SDK configuration.

Troubleshooting

Build fails with "You are trying to use the WebEngage plugin without any props"

Ensure the plugin is listed in app.json or app.config.js with its configuration object — not just as a bare plugin name.

"plugins": [
  [
    "./node_modules/webengage-expo/src/withWebEngage.js",
    {
      "push": { "mode": "development" },
      "ios": { "WEGLicenseCode": "YOUR_LICENSE_CODE" },
      "android": { "manifest": { "com.webengage.sdk.android.key": "YOUR_LICENSE_CODE" } }
    }
  ]
]

Need Help?

If you have any questions or issues with the WebEngage Expo integration, contact:

[email protected]