Expo Pushwoosh Push Notifications module

SUPPORTED ENVIRONMENTS:

• The Expo run commands (expo run:[android|ios])

INSTALL

You need both packages: pushwoosh-expo-plugin (the config plugin, applied at prebuild) and pushwoosh-react-native-plugin (the runtime SDK you call from JS).

npx expo install pushwoosh-expo-plugin pushwoosh-react-native-plugin

CONFIGURATION IN app.json / app.config.js

Plugin

Add the plugin to the front of the plugin array.

{
  "plugins": [
    [
      "pushwoosh-expo-plugin",
      {
        "mode": "development",
      }
    ]
  ]
}

Plugin Prop

You can pass prop to the plugin config object to configure:

| Plugin prop | | | |--------------|--------------|-------------------------------------------------------------------------------| | mode | required | iOS only — configures the APNs environment entitlement. "development" or "production". Has no effect on Android. |

iOS Props

The following props can be configured under the ios key:

| iOS props | Required | Default | Description | |-----------|----------|---------|-------------| | PW_API_TOKEN | Yes | __YOUR_API_TOKEN__ | Your Pushwoosh API token for iOS. You can get the API token in the Pushwoosh control panel (Select an app -> "Settings" -> "API access" | | Pushwoosh_LOG_LEVEL | No | INFO | Log level for iOS. Possible values: NONE, ERROR, WARN, INFO, DEBUG, NOISE |

Note: Remote notifications in Background Modes are automatically configured in the Signing & Capabilities section through the withEntitlementsPlist function. You don't need to manually configure this in Info.plist.

Android Props

The following props can be configured under the android key:

| Android props | Required | Default | Description | |---------------|----------|---------|-------------| | apiToken | Yes | __YOUR_API_TOKEN__ | Your Pushwoosh API token for Android. You can get the API token in the Pushwoosh control panel (Select an app -> "Settings" -> "API access" | | logLevel | No | INFO | Log level for Android. One of: NONE, ERROR, WARN, INFO, DEBUG, NOISE | | multiNotificationMode | No | true | Can be changed to false in case you want to display only the last notification for the user | | icon | No | - | Path to a custom notification icon for Android |

Example Configuration

Here's an example of how to configure the plugin in your app.json:

{
  "expo": {
    "plugins": [
      [
        "pushwoosh-expo-plugin",
        {
          "mode": "development",
          "ios": {
            "PW_API_TOKEN": "YOUR_API_TOKEN",
            "Pushwoosh_LOG_LEVEL": "DEBUG"
          },
          "android": {
            "apiToken": "YOUR_API_TOKEN",
            "logLevel": "DEBUG",
            "icon": "./assets/notification-icon.png"
          }
        }
      ]
    ]
  }
}

Android: Firebase (FCM) setup

Android delivery goes through Firebase Cloud Messaging, so the app needs a google-services.json. The config plugin does not add it for you:

1. In the Firebase console open (or create) the project whose FCM credentials are connected to your Pushwoosh app (Pushwoosh control panel → your app → Android/Firebase configuration).
2. Register an Android app in that Firebase project whose package name matches the android.package you use in app.json, then download its google-services.json.
3. Put the file in your project and point Expo at it via android.googleServicesFile:

{
  "expo": {
    "android": {
      "package": "com.yourcompany.yourapp",
      "googleServicesFile": "./google-services.json"
    }
  }
}

During expo prebuild Expo copies the file into the native project and applies the com.google.gms.google-services Gradle plugin automatically. Without it Firebase cannot initialize, no push token is registered, and notifications silently never arrive.

On Android 13+ the SDK requests the POST_NOTIFICATIONS runtime permission on first launch.

Initialize Pushwoosh

import Pushwoosh from 'pushwoosh-react-native-plugin';

// pw_appid — your Pushwoosh Application Code (e.g. "XXXXX-XXXXX"),
// from the Pushwoosh control panel → your app → Settings.
Pushwoosh.init({ pw_appid: 'YOUR_PUSHWOOSH_APP_CODE' });
Pushwoosh.register();

The FCM Sender ID is read from google-services.json (Android) — do not pass a project_number to init; that legacy GCM parameter is no longer used.

See the Pushwoosh React Native integration guide for the full JS API.

Prebuild (optional)

Prebuilding within Expo entails the generation of native runtime code for the project, resulting in the construction of the 'ios' and 'android' directories. Through prebuilding, the native modules that utilize CocoaPods, autolinking, and other configuration plugins are automatically linked and configured. You can conceptualize prebuild as a bundler for native code.

Executing expo prebuild initiates a custom managed workflow that combines the advantages of both bare workflows and managed workflows simultaneously.

Why is prebuilding recommended?

Prebuilding locally can be beneficial for inspecting changes in config plugins and assisting in the debugging of issues.

Running

npx expo prebuild

RUN

Executing the provided commands will prebuild and run your application. It's important to note that push notifications will not function in the iOS Simulator.

# Build and run your native iOS project
npx expo run:ios

# Build and run your native Android project
npx expo run:android

LICENCE

Copyright © 2024 Pushwoosh. This project is MIT licensed.