---
updatedAt: 2026-09-16T06:26:24.000Z
agentTools:
  projectIndex: https://docs.webengage.com/llms.txt
---

# Expo

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`

```bash npm
npm install webengage-expo
```
```bash yarn
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.

```bash npm
npm install react-native-webengage
```
```bash yarn
yarn add react-native-webengage
```

<Callout icon="🚧" theme="warn">
  Both `webengage-expo` and `react-native-webengage` are required.
</Callout>

***

# 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:

```text
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:

```json
{
  "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
            }
          }
        }
      ]
    ]
  }
}
```

<Callout icon="🚧" theme="warn">
  Replace placeholder values such as `YOUR_LICENSE_CODE` with your actual WebEngage License Code.
</Callout>

## iOS

| Key                   | Description                                                                                                                                                                                                                                                                                                                 | Required |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `push.mode`           | Push notification mode: `development` or `production`                                                                                                                                                                                                                                                                       | Yes      |
| `ios.WEGLicenseCode`  | Your WebEngage License Code                                                                                                                                                                                                                                                                                                 | Yes      |
| `ios.WEGLogLevel`     | Log level: `DEFAULT` or `VERBOSE`                                                                                                                                                                                                                                                                                           | Optional |
| `ios.WEGEnvironment`  | WebEngage environment: `DEFAULT`, `IN`, `KSA`, or `EUG`                                                                                                                                                                                                                                                                     | Yes      |
| `ios.WEGAutoRegister` | Controls whether the native WebEngage SDK automatically registers the device for push notifications (and requests notification permission) on app launch. Defaults to `true` if omitted. WebEngage initialization and push callback registration in the iOS AppDelegate are added automatically regardless of this setting. | Optional |

## Android

| Key                                                      | Description                                                  | Required |
| -------------------------------------------------------- | ------------------------------------------------------------ | -------- |
| `android.manifest.com.webengage.sdk.android.environment` | WebEngage environment: `us`, `in`, `ksa`, or `eug`           | Yes      |
| `android.manifest.com.webengage.sdk.android.key`         | Your WebEngage License Code                                  | Yes      |
| `android.manifest.com.webengage.sdk.android.debug`       | Enables or disables WebEngage SDK logging: `true` or `false` | Optional |

***

# 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.

```bash
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:

```bash
npx expo prebuild
npx expo run:ios
npx expo run:android
```

<Callout icon="🚧" theme="warn">
  `npx expo prebuild` generates the native `ios` and `android` directories and applies the WebEngage config plugin.
</Callout>

## 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.

<Callout icon="🚧" theme="warn">
  OTA updates cannot apply native changes. If a change requires the WebEngage native SDK or native project configuration to change, you must create a new native build.
</Callout>

***

# 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.

<Callout icon="🚧" theme="warn">
  If you do not have access to Xcode or Android Studio, you can verify the integration by checking for active user sessions in **WebEngage Dashboard > Users > Live Users**.
</Callout>

***

# Usage

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

## Track Events

```javascript
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

```javascript
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('john@doe.com');

// 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:

| Guide                                                                                   | What it covers                                                                               |
| :-------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------- |
| [Tracking Users](https://docs.webengage.com/docs/react-native-tracking-users)           | User identification & attributes                                                             |
| [Tracking Events](https://docs.webengage.com/docs/react-native-tracking-events)         | Custom event tracking (`webengage.track`)                                                    |
| [In-App Messaging](https://docs.webengage.com/docs/react-native-in-app-messaging)       | In-app messages, incl. screen tracking                                                       |
| [App In-line Content](https://docs.webengage.com/docs/react-native-app-in-line-content) | In-line content, incl. screen tracking                                                       |
| [App Inbox](https://docs.webengage.com/docs/copy-to-notification-inbox-react-native)    | Copy push notifications into the in-app inbox                                                |
| [Callbacks](https://docs.webengage.com/docs/react-native-callbacks)                     | Push / in-app / anonymous-ID lifecycle callbacks                                             |
| [Advanced](https://docs.webengage.com/docs/react-native-advanced)                       | Native linking options (SPM/CocoaPods) — informational only, the plugin already handles this |
| [Troubleshooting](https://docs.webengage.com/docs/react-native-troubleshooting)         | Common integration errors                                                                    |
| [Expo Push Integration Guide](./final_expo_push.md)                                     | **Push works differently on Expo** — follow this guide, not the RN push doc                  |

***

# Supported Environments

| Environment           | Supported |
| --------------------- | --------- |
| **Expo Go**           | No        |
| **Expo Snack**        | No        |
| **EAS Build**         | Yes       |
| **Prebuild Workflow** | Yes       |
| **Custom Dev Client** | Yes       |

## 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:

```bash
npx expo prebuild
```

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

<Callout icon="🚧" theme="warn">
  `npx expo prebuild --clean` deletes and regenerates the native `android` and `ios` directories. Use `--clean` only when you intentionally want to regenerate the native projects from scratch.
</Callout>

***

# 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.

```json
"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" } }
    }
  ]
]
```

<br />

***

# Need Help?

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

<support@webengage.com>

<br />