Expo SDK Basic integration guide
This section contains information on how to integrate the Pushwoosh Expo SDK into your application.
Prerequisites
Anchor link toTo integrate the Pushwoosh Expo SDK into your app, you will need the following:
Integration steps
Anchor link to1. Install the plugin
Anchor link toInstall the Pushwoosh Expo plugin using the Expo CLI
expo install pushwoosh-expo-plugin
Install Pushwoosh React Native SDK
npm install pushwoosh-react-native-plugin --save
2. Set the plugin properties
Anchor link toAdd the plugin to the front of the plugin array with the necessary properties:
{ "expo": { "plugins": [ [ "pushwoosh-expo-plugin", { "mode": "development", "ios": { "PW_API_TOKEN": "__YOUR_DEVICE_API_TOKEN__" }, "android": { "apiToken": "__YOUR_DEVICE_API_TOKEN__" } } ] ] }}
Where:
mode
is used to configure the APNs environment entitlement. “Development” or “production” values are available.PW_API_TOKEN
,apiToken
is your Pushwoosh Device API Token.
3. Initialize Pushwoosh
Anchor link toIn the root component of your application:
- Import the
pushwoosh-react-native-plugin
plugin. - Initialize the Pushwoosh SDK.
- Call
register()
in your initialization logic to register for push notifications.
import Pushwoosh from 'pushwoosh-react-native-plugin';
Pushwoosh.init({ "pw_appid": "__YOUR_APP_ID__" , "project_number": "__YOUR_FCM_SENDER_ID__"});
Pushwoosh.register();
Where:
__YOUR_APP_ID__
is the application code from the Pushwoosh Control Panel.__YOUR_FCM_SENDER_ID__
is the Firebase project number from the Firebase Console.
4. Android Native Setup
Anchor link toAdd Firebase configuration file:
- Copy your
google-services.json
file to the root directory of the project. - Set the
googleServicesFile
property to the path of yourgoogle-services.json
and specify thepackage
property:
"expo": { "name": "sample", "android": { "package": "com.pushwoosh.sample", "googleServicesFile": "./google-services.json" }, "plugins": [ [ "pushwoosh-expo-plugin", { "mode": "development", "ios": { "PW_API_TOKEN": "__YOUR_DEVICE_API_TOKEN__" }, "android": { "apiToken": "__YOUR_DEVICE_API_TOKEN__" } } ] ]}
5. iOS Native Setup
Anchor link toSet bundleIdentifier
property to the ios
object:
"expo": { "name": "sample", "ios": { "bundleIdentifier": "com.pushwoosh.sample" }, "plugins": [ [ "pushwoosh-expo-plugin", { "mode": "development", "ios": { "PW_API_TOKEN": "__YOUR_DEVICE_API_TOKEN__" }, "android": { "apiToken": "__YOUR_DEVICE_API_TOKEN__" } } ] ]}
6. Prebuild the app
Anchor link toGenerate native code and configure the dependencies for each platform by running prebuild:
npx expo prebuild
7. Run the project
Anchor link to- Build and run the project:
npx expo run:android
npx expo run:ios
- Go to the Pushwoosh Control Panel and send a push notification.
- You should see the notification in the app.
Extended integration
Anchor link toAt this stage, you have already integrated the SDK and can send and receive push notifications. Now, let’s explore the core functionality
Push notification event listeners
Anchor link toIn the Pushwoosh SDK there are two event listeners, designed for handling push notifications:
onPushReceived
event is triggered, when a push notification is receivedonPushAccepted
event is triggered, when a user opens a notification
You should set up these event listeners right after initialization of the SDK at the application start up:
import { DeviceEventEmitter } from 'react-native';import Pushwoosh from 'pushwoosh-react-native-plugin';
class PushwooshNotificationHandler { setupPushListeners(): void {
DeviceEventEmitter.addListener("pushReceived", (e) => { console.warn("Push received: " + JSON.stringify(e)); });
DeviceEventEmitter.addListener("pushOpened", (e) => { console.warn("Push opened:" + JSON.stringify(e)); });
}}
User configuration
Anchor link toBy focusing on individual user behavior and preferences, you can deliver personalized content, leading to increased user satisfaction and loyalty
import Pushwoosh from 'pushwoosh-react-native-plugin';
class Registration { afterUserLogin(user: User): void {
// Set user ID Pushwoosh.setUserId(user.getId());
// Set user email Pushwoosh.setEmails(user.getEmailList());
// Setting additional user information as tags for Pushwoosh Pushwoosh.setTags({ "age": user.getAge(), "name": user.getName(), "last_login": user.getLastLoginDate() }); }}
Tags
Anchor link toTags are key-value pairs assigned to users or devices, allowing segmentation based on attributes like preferences or behavior, enabling targeted messaging.
import Pushwoosh from 'pushwoosh-react-native-plugin';
class UpdateUser { afterUserUpdateProfile(user: User): void {
// Set list of favorite categories Pushwoosh.setTags({ "favorite_categories": user.getFavoriteCategoriesList() });
// Set payment information Pushwoosh.setTags({ "is_subscribed": user.isSubscribed(), "payment_status": user.getPaymentStatus(), "billing_address": user.getBillingAddress() }); }}
Events
Anchor link toEvents are specific user actions or occurrences within the app that can be tracked to analyze behavior and trigger corresponding messages or actions
import Pushwoosh from 'pushwoosh-react-native-plugin';
class Registration {
// Track login event afterUserLogin(user: User): void { Pushwoosh.postEvent("login", { "name": user.getName(), "last_login": user.getLastLoginDate() }); }
// Track purchase event afterUserPurchase(product: Product): void { Pushwoosh.postEvent("purchase", { "product_id": product.getId(), "product_name": product.getName(), "price": product.getPrice(), "quantity": product.getQuantity() }); }}
Message delivery tracking for iOS
Anchor link toYou must add a Notification Service Extension target to your project. This is essential for accurate delivery tracking and features like Rich Media on iOS.
Follow the native guide’s steps to add the extension target and the necessary Pushwoosh code within it.
Additional plugin properties
Anchor link toProperty | Default | Description |
---|---|---|
iOS properties | ||
Pushwoosh_LOG_LEVEL | INFO | Log level for iOS. Possible values: NONE , ERROR , WARN , INFO , DEBUG , NOISE |
Android properties | ||
logLevel | INFO | Log level for Android. One of: NONE , ERROR , WARN , INFO , DEBUG , NOISE |
multiNotificationMode | true | Can be changed to false in case you want to display only the last notification for the user |
icon | - | Path to a custom notification icon for Android |
Troubleshooting
Anchor link toIf you encounter any issues during the integration process, please refer to the support and community section.
FCM registration error: Failed to retrieve token. Is firebase configured correctly?
Anchor link toMake sure your Firebase googleServicesFile
property is set up in the Expo configuration file and the google-services.json
file is added to the root directory of your project:
"expo": { "name": "sample", "android": { "package": "com.pushwoosh.sample", "googleServicesFile": "./google-services.json" }, "plugins": [ [ "pushwoosh-expo-plugin", { "mode": "development", "ios": { "PW_API_TOKEN": "__YOUR_DEVICE_API_TOKEN__" }, "android": { "apiToken": "__YOUR_DEVICE_API_TOKEN__" } } ] ]}
TypeError: Cannot read property ‘init’ of null
Anchor link toYou might encounter the error, when attempting to run the app on a device.
To resolve the issue, make sure you’ve completed the prebuild step. It generates the native code and configures the dependencies for each platform.
npx expo prebuild