---
updatedAt: 2025-11-04T10:01:43.000Z
agentTools:
  projectIndex: https://docs.wonderpush.com/llms.txt
---

# Expo plugin options reference

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th style={{ textAlign: "left" }}>
        Option
      </th>

      <th style={{ textAlign: "left" }}>
        Type
      </th>

      <th style={{ textAlign: "left" }}>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td style={{ textAlign: "left" }}>
        `clientId`
      </td>

      <td style={{ textAlign: "left" }}>
        string
      </td>

      <td style={{ textAlign: "left" }}>
        The Client ID found in your WonderPush dashboard.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `clientSecret`
      </td>

      <td style={{ textAlign: "left" }}>
        string
      </td>

      <td style={{ textAlign: "left" }}>
        The Client Secret found in your WonderPush dashboard.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `senderId`
      </td>

      <td style={{ textAlign: "left" }}>
        string containing only digits
      </td>

      <td style={{ textAlign: "left" }}>
        The Sender ID found in your _Firebase Cloud Messaging_ settings.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `autoInit`
      </td>

      <td style={{ textAlign: "left" }}>
        boolean
      </td>

      <td style={{ textAlign: "left" }}>
        Allows deactivation of the automatic initialization of the SDK
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `logging`
      </td>

      <td style={{ textAlign: "left" }}>
        boolean
      </td>

      <td style={{ textAlign: "left" }}>
        Controls debug logging.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `requiresUserConsent`
      </td>

      <td style={{ textAlign: "left" }}>
        boolean
      </td>

      <td style={{ textAlign: "left" }}>
        Controls whether user consent is required for the SDK to operate.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `geolocation`
      </td>

      <td style={{ textAlign: "left" }}>
        boolean
      </td>

      <td style={{ textAlign: "left" }}>
        Controls whether geolocation is collected or not.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `allowBackgroundStart`
      </td>

      <td style={{ textAlign: "left" }}>
        boolean
      </td>

      <td style={{ textAlign: "left" }}>
        Controls whether to allow starting a React Native context in background to react to received push notifications with the WonderPush Delegate.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `ios.apsEnvironment`
      </td>

      <td style={{ textAlign: "left" }}>
        `"development"` or `"production"`
      </td>

      <td style={{ textAlign: "left" }}>
        APS environment to use for the iOS entitlements
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `android.defaultNotificationColor`
      </td>

      <td style={{ textAlign: "left" }}>
        `"#RRGGBB"` or `"#AARRGGBB"` or `"RRGGBB"` or `"AARRGGBB"`
      </td>

      <td style={{ textAlign: "left" }}>
        The default notification color on Android, as a hexadecimal value.  

        Mutually exclusive with `android.defaultNotificationColorResource`
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `android.defaultNotificationColorResource`
      </td>

      <td style={{ textAlign: "left" }}>
        `"@color/resource_name"`
      </td>

      <td style={{ textAlign: "left" }}>
        The default notification color on Android, as an Android color resource reference.  

        Mutually exclusive with `android.defaultNotificationColor`
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `android.defaultNotificationIconResource`
      </td>

      <td style={{ textAlign: "left" }}>
        `@drawable/resource_name` or `"resource_name"` or `"/path/to/resource_name.ext"`
      </td>

      <td style={{ textAlign: "left" }}>
        The default notification icon on Android, as an Android resource reference, but file names are accepted too.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `android.smallIcons`
      </td>

      <td style={{ textAlign: "left" }}>
        an array of path to image assets
      </td>

      <td style={{ textAlign: "left" }}>
        A list of image assets to include as resources in the application in the proper sizes to be used as small icons in Android notifications.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `android.largeIcons`
      </td>

      <td style={{ textAlign: "left" }}>
        an array of path to image assets
      </td>

      <td style={{ textAlign: "left" }}>
        A list of image assets to include as resources in the application in the proper sizes to be used as large icons in Android notifications.
      </td>
    </tr>
  </tbody>
</Table>

# Configuration options

The `wonderpush-expo-plugin` is configured in your `app.json` or `app.config.js` or `app.config.ts` file as follows:

```json app.json
{
  "expo": {
    // …
    "plugins": [
      // …
      [
        "wonderpush-expo-plugin",
        {
          // List the plugin options detailed in this page here.
          // For example:
          "clientId": "YOUR_CLIENT_ID",
          "clientSecret": "YOUR_CLIENT_SECRET",
          "senderId": "YOUR_SENDER_ID"
        }
      ]
    ]
  }
}
```

<Callout icon="📘" theme="info">
  The entries inside the `expo.plugins` array can be a single plugin name as a string without the mean to give options, or an array with the plugin name as first element and an object for the options as second element.

  So you need to have **an array within an array** to provide the options. Take extra care the first time you edit this.
</Callout>

## `clientId`

The Client ID found in your WonderPush dashboard. Follow the [(XXX) Expo Push Notifications](https://docs.wonderpush.com/docs/expo-push-notifications) quickstart guide.

This option is mandatory unless you have an integration use case that requires determining this value at run time. In such case you will need to call `WonderPush.initializeAndRememberCredentials("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")` during your application startup.

## `clientSecret`

The Client Secret found in your WonderPush dashboard. Follow the [(XXX) Expo Push Notifications](https://docs.wonderpush.com/docs/expo-push-notifications) quickstart guide.

This option is mandatory unless you have an integration use case that requires determining this value at run time. In such case you will need to call `WonderPush.initializeAndRememberCredentials("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")` during your application startup.

## `senderId`

The Sender ID found in your *Firebase Cloud Messaging* settings. Follow the [(XXX) Expo Push Notifications](https://docs.wonderpush.com/docs/expo-push-notifications) quickstart guide.

If your application integrates the Google Services, this can be automatically determined. It is recommended to explicit set this option anyways, otherwise your push tokens will be tied to WonderPush and won't be portable.

## `autoInit`

Permits to deactivate the automatic initialization of the SDK. The default is `true`.

## `logging`

Controls debug logging. The default is `false`.

You can enable it for debug builds but you should disable it for release builds.

## `requiresUserConsent`

Controls whether user consent is required before doing anything. The default is `false`.

## `geolocation`

Controls whether geolocation is collected or not. The default is `true`.

The system permission is required for the collection to be effective. WonderPush does not automatically prompt your users for this permission. The collection is hence only opportunistic, if your app already uses it.

## `allowBackgroundStart`

If you use `WonderPush.setDelegate()` to receive events from WonderPush when a notification is received or to alter the deeplink, you need to opt into WonderPush starting a React Native context of your application in the background.

Make sure your app does not run code that assumes the application is is foreground until it actually is in the foreground, as starting a React Native context will evaluate the JavaScript of your application.

If you do not activate this, the WonderPush Delegate will only call your code if the events happen while your application is already running.

The default is `false`.

## `ios.apsEnvironment`

Allows you to force que value of the `aps-environment` entitlement for iOS if ever need be.

The default is `"development"`, like Xcode configures when activating the Push notifications capability.

The dot in this option name refers to a sub-field. Give this option as `"ios": { "apsEnvironment": "development" }`, for example.

## `android.defaultNotificationColor`

Selects the default color for your Android notifications, used for tinting the notification small icon.

Accepts values in hexadecimal format with optional `#` and alpha channel (which is replaced by full opacity by Android anyway): `"#RRGGBB"` or `"#AARRGGBB"` or `"RRGGBB"` or `"AARRGGBB"`.

This option is mutually exclusive with `android.defaultNotificationColorResource`.

The dot in this option name refers to a sub-field. Give this option as `"android": { "defaultNotificationColor": "#FF8000" }`, for example for an orange tint.

## `android.defaultNotificationColorResource`

If you already have `@color` resources in your application, you can use this option instead of the easier `android.defaultNotificationColor` to reference it.

Accepts `"@color/resource_name"` values.

This option is mutually exclusive with `android.defaultNotificationColor`, which is often the simpler alternative for most setups.

The dot in this option name refers to a sub-field. Give this option as `"android": { "defaultNotificationColorResource": "…" }`.

## `android.defaultNotificationIconResource`

Selects the default icon you want to use for your Android notifications instead of the default bell icon.

This references a drawable resource resource in your Android application. Use the `android.smallIcons` option to add the necessary image assets as drawable resources and reference the name of the one you want to use by default.

Values are expected to be like `"@drawable/resource_name"`.\
For convenience, we also accept `"resource_name"` or file references like `"/path/to/resource_name.ext"` and transform them accordingly.

```json app.json
{
  "expo": {
    // …
    "plugins": [
      // …
      [
        "wonderpush-expo-plugin",
        {
          "android": {
            "defaultNotificationIconResource": "@drawable/my_notification_icon_mask",
            "smallIcons": ["./my_notification_icon_mask.png"]
          }
        }
      ]
    ]
  }
}
```

## `android.smallIcons`

Accepts a list of paths to image assets to include into your Android application as assets.\
Avoid `-` in file names and prefer `_`.

Images should be 96×96 px, white on transparent, used as masks by Android.
Each image will be resized to the appropriate size variants.

You can use the base name of the file as the resource name. For example if you give the list `["./assets/logo_notification_icon_mask.png", "./assets/coupon_notification_icon_mask.png"]` then the resources `@drawable/logo_notification_icon_mask` and `@drawable/coupon_notification_icon_mask` are now valid resources you can use, for instance in the `android.defaultNotificationIconResource` option described above.

The dot in this option name refers to a sub-field. Give this option as `"android": { "smallIcons": ["…", …] }`.

## `android.largeIcons`

<Callout icon="📘" theme="info">
  You most likely *do not need* this option. It's here for completeness.

  Usually notifications are sent with a URL to an image as the notification large icon for Android, field instead of referencing a resource bundled inside application.
</Callout>

Accepts a list of paths to image assets to include into your Android application as assets.\
Avoid `-` in file names and prefer `_`.

Images should be 256×256 px.
Each image will be resized to the appropriate size variants.

You can use the base name of the file as the resource name. For example if you give the list `["./assets/logo_large_notification_icon.png", "./assets/super_deal_large_notification_icon.png"]` then the resources `@drawable/logo_large_notification_icon` and `@drawable/super_deal_large_notification_icon` are now valid resources you can use.

Those resources are not meant for use in the `android.defaultNotificationIconResource` option described above as it expects white on transparent masks instead.

The dot in this option name refers to a sub-field. Give this option as `"android": { "largeIcons": ["…", …] }`.

<br />