Pushwoosh React Native Plugin

Cross-platform push notifications, In-App messaging, and more for React Native applications.

Documentation

Integration Guide — step-by-step setup
API Reference — full API documentation
Sample Project — ready-to-run demo app on the current React Native (New Architecture)
Legacy Sample Project — the same demo on React Native 0.74 with the legacy architecture

Features

Push Notifications — register, receive, and handle push notifications on iOS and Android
In-App Messages — trigger and display in-app messages based on events
Tags & Segmentation — set and get user tags for targeted messaging
User Identification — associate devices with user IDs for cross-device tracking
Message Inbox — built-in UI for message inbox with customization options
Badge Management — set, get, and increment app icon badge numbers
Local Notifications — schedule and manage local notifications
Rich Media — modal and legacy Rich Media presentation styles
Huawei Push — HMS push notification support
Multi-channel — email, SMS, and WhatsApp registration
TypeScript Support — full TypeScript definitions included

Installation

npm install pushwoosh-react-native-plugin --save

iOS Setup

cd ios && pod install

Android Setup (Firebase Cloud Messaging)

Push notifications on Android require Firebase Cloud Messaging (FCM).

Option A — Android Studio (recommended): Open the android/ folder in Android Studio, then go to Tools > Firebase > Cloud Messaging > Set up Firebase Cloud Messaging. The wizard will automatically add all required configuration.

Option B — Manual setup:

Create a project in Firebase Console
Download google-services.json and place it in android/app/
Add the Google Services classpath to android/build.gradle:
```
classpath("com.google.gms:google-services:4.3.15")
```

Apply the plugin in android/app/build.gradle:

apply plugin: "com.google.gms.google-services"

The Pushwoosh plugin already includes the firebase-messaging dependency, so you do not need to add it manually.

React Native versions and the New Architecture

The plugin is a Turbo Native Module and also works on the legacy bridge. One package covers both:

React Native	Architecture	How the plugin runs
0.74 – 0.81, `newArchEnabled=false` (default)	Legacy bridge	Bridge module
0.74 – 0.81, `newArchEnabled=true` / `RCT_NEW_ARCH_ENABLED=1`	New Architecture	Codegen TurboModule
0.82 and later	New Architecture only (bridgeless)	Codegen TurboModule

No interop layer is involved on the New Architecture. Events keep their API on both architectures:

import { DeviceEventEmitter } from 'react-native';

DeviceEventEmitter.addListener('pushOpened', (push) => { /* ... */ });
DeviceEventEmitter.addListener('pushReceived', (push) => { /* ... */ });

presentInboxUI() presents a native screen (a view controller on iOS, an Activity on Android) outside the React view tree, so it does not depend on Fabric. React Native below 0.74 is supported by plugin versions 6.1.x.

Both setups ship as samples with identical screens: example/demoapp (React Native 0.87, New Architecture) and example/demoapp-legacy (React Native 0.74, legacy architecture).

AI-Assisted Integration

Integrate the Pushwoosh React Native plugin using AI coding assistants (Claude Code, Cursor, GitHub Copilot, etc.).

Requirement: Your AI assistant must have access to Context7 MCP server or web search capabilities.

Quick Start Prompts

Choose the prompt that matches your task:

1. Basic Plugin Integration

Integrate Pushwoosh React Native plugin into my React Native project.

Requirements:
- Install pushwoosh-react-native-plugin via npm
- Initialize Pushwoosh with my App ID in the app entry point
- Register for push notifications and handle pushOpened events via DeviceEventEmitter

Use Context7 MCP to fetch Pushwoosh React Native plugin documentation.

2. Tags and User Segmentation

Show me how to use Pushwoosh tags in a React Native app for user segmentation.
I need to set tags, get tags, and set user ID for cross-device tracking.

Use Context7 MCP to fetch Pushwoosh React Native plugin documentation for setTags and getTags.

3. Message Inbox Integration

Integrate Pushwoosh Message Inbox into my React Native app. Show me how to:
- Display the inbox UI with custom styling
- Load messages programmatically
- Track unread message count

Use Context7 MCP to fetch Pushwoosh React Native plugin documentation for presentInboxUI.

Quick Start

1. Initialize the Plugin

import Pushwoosh from 'pushwoosh-react-native-plugin';
import { DeviceEventEmitter } from 'react-native';

// Listen for push notification events
DeviceEventEmitter.addListener('pushOpened', (e) => {
    console.log("Push opened: " + JSON.stringify(e));
});

// Initialize Pushwoosh
Pushwoosh.init({
    pw_appid: "YOUR_PUSHWOOSH_APP_ID"
});

// Register for push notifications
Pushwoosh.register(
    (token) => {
        console.log("Registered with push token: " + token);
    },
    (error) => {
        console.error("Failed to register: " + error);
    }
);

2. Set User Tags

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

Pushwoosh.setTags(
    { username: "john_doe", age: 25, interests: ["sports", "tech"] },
    () => console.log("Tags set successfully"),
    (error) => console.error("Failed to set tags: " + error)
);

Pushwoosh.getTags(
    (tags) => console.log("Tags: " + JSON.stringify(tags)),
    (error) => console.error("Get tags error: " + error)
);

3. Post Events for In-App Messages

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

Pushwoosh.setUserId("user_12345");
Pushwoosh.postEvent("purchase_complete", {
    productName: "Premium Plan",
    amount: "9.99"
});

4. Message Inbox

import Pushwoosh from 'pushwoosh-react-native-plugin';
import { processColor, Image } from 'react-native';

// Open inbox UI with custom styling
Pushwoosh.presentInboxUI({
    dateFormat: "dd.MM.yyyy",
    accentColor: processColor('#3498db'),
    backgroundColor: processColor('#ffffff'),
    titleColor: processColor('#333333'),
    descriptionColor: processColor('#666666'),
    listEmptyMessage: "No messages yet"
});

// Or load messages programmatically
Pushwoosh.loadMessages(
    (messages) => {
        messages.forEach((msg) => {
            console.log(msg.title + ": " + msg.message);
        });
    },
    (error) => console.error("Failed to load: " + error)
);

Pushwoosh.unreadMessagesCount((count) => {
    console.log("Unread messages: " + count);
});

5. Multi-channel Communication

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

Pushwoosh.setEmails(
    ["user@example.com"],
    () => console.log("Email set"),
    (error) => console.error(error)
);

Pushwoosh.registerSMSNumber("+1234567890");
Pushwoosh.registerWhatsappNumber("+1234567890");

6. Custom Notification Handling (iOS)

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

Pushwoosh.init({
    pw_appid: "YOUR_PUSHWOOSH_APP_ID",
    pw_notification_handling: "CUSTOM"
});

API Reference

Initialization & Registration

Method	Description
`init(config, success?, fail?)`	Initialize the plugin. Call on every app launch
`register(success?, fail?)`	Register for push notifications
`unregister(success?, fail?)`	Unregister from push notifications
`getPushToken(success)`	Get the push token
`getHwid(success)`	Get Pushwoosh Hardware ID
`getUserId(success)`	Get current user ID

Tags & User Data

Method	Description
`setTags(tags, success?, fail?)`	Set device tags
`getTags(success, fail?)`	Get device tags
`setUserId(userId, success?, fail?)`	Set user identifier for cross-device tracking
`setLanguage(language)`	Set custom language for localized pushes
`setEmails(emails, success?, fail?)`	Register emails for the user
`setUserEmails(userId, emails, success?, fail?)`	Set user ID and register emails
`registerSMSNumber(phoneNumber)`	Register SMS number (E.164 format)
`registerWhatsappNumber(phoneNumber)`	Register WhatsApp number (E.164 format)

Notifications

Method	Description
`createLocalNotification(config)`	Schedule a local notification
`clearLocalNotification()`	Clear all pending local notifications
`clearNotificationCenter()`	Clear all notifications from notification center

Badge Management

Method	Description
`setApplicationIconBadgeNumber(badge)`	Set badge number
`getApplicationIconBadgeNumber(callback)`	Get current badge number
`addToApplicationIconBadgeNumber(badge)`	Increment/decrement badge

In-App Messages & Events

Method	Description
`postEvent(event, attributes?)`	Post event to trigger In-App Messages
`setRichMediaType(type)`	Set Rich Media style (MODAL or LEGACY)
`getRichMediaType(callback)`	Get current Rich Media style

Message Inbox

Method	Description
`presentInboxUI(style?)`	Open inbox UI with optional style customization
`loadMessages(success, fail?)`	Load inbox messages programmatically
`unreadMessagesCount(callback)`	Get unread message count
`messagesCount(callback)`	Get total message count
`messagesWithNoActionPerformedCount(callback)`	Get messages with no action count
`readMessage(id)`	Mark message as read
`readMessages(ids)`	Mark multiple messages as read
`deleteMessage(id)`	Delete a message
`deleteMessages(ids)`	Delete multiple messages
`performAction(id)`	Perform the action associated with a message

Android-specific

Method	Description
`setMultiNotificationMode(on)`	Allow multiple notifications in notification center
`setLightScreenOnNotification(on)`	Turn screen on when notification arrives
`setEnableLED(on)`	Enable LED blinking on notification
`setColorLED(color)`	Set LED color (ARGB integer)
`setSoundType(type)`	Set sound type (0=default, 1=none, 2=always)
`setVibrateType(type)`	Set vibration type (0=default, 1=none, 2=always)
`setNotificationIconBackgroundColor(color)`	Set notification icon background color
`enableHuaweiPushNotifications()`	Enable Huawei HMS push support

Communication Control

Method	Description
`setCommunicationEnabled(enable, success?, fail?)`	Enable/disable all Pushwoosh communication
`isCommunicationEnabled(success)`	Check if communication is enabled

Reverse Proxy

Method	Description
`setReverseProxy(url, headers?)`	Route all SDK requests through a reverse proxy. Call before `init()`

Events (DeviceEventEmitter)

Event	Description
`pushOpened`	Fired when a notification is opened by the user
`pushReceived`	Fired when a notification is received

Support

License

Pushwoosh React Native Plugin is available under the MIT license. See LICENSE for details.

Made with ❤️ by Pushwoosh

Name		Name	Last commit message	Last commit date
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
docs		docs
example		example
scripts		scripts
src		src
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE.md		LICENSE.md
README.md		README.md
index.d.ts		index.d.ts
index.js		index.js
package.json		package.json
pushwoosh-react-native-plugin.podspec		pushwoosh-react-native-plugin.podspec
react-native.config.js		react-native.config.js

Latest commit

History

Folders and files

Repository files navigation