Pushwoosh

Pushwoosh Cordova Plugin

GitHub release npm license

Cross-platform push notifications, In-App messaging, and more for Cordova / PhoneGap applications.

## Table of Contents - [Documentation](#documentation) - [Features](#features) - [Installation](#installation) - [AI-Assisted Integration](#ai-assisted-integration) - [Quick Start](#quick-start) - [API Reference](#api-reference) - [Plugin Preferences](#plugin-preferences) - [Support](#support) - [License](#license) ## Documentation - [Integration Guide](https://docs.pushwoosh.com/platform-docs/pushwoosh-sdk/cross-platform-frameworks/cordova/integrating-cordova-plugin) — step-by-step setup - [API Reference](https://docs.pushwoosh.com/platform-docs/pushwoosh-sdk/cross-platform-frameworks/cordova/cordova-plugin-api-reference) — full API documentation ## 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 - **VoIP Calls** — CallKit (iOS) and ConnectionService (Android) integration for VoIP push calls - **Huawei Push** — HMS push notification support - **TypeScript Support** — full TypeScript definitions included ## Installation Using npm: ```bash cordova plugin add pushwoosh-cordova-plugin@8.3.70 ``` Using git: ```bash cordova plugin add https://github.com/Pushwoosh/pushwoosh-phonegap-plugin.git#8.3.70 ``` ## AI-Assisted Integration Integrate the Pushwoosh Cordova plugin using AI coding assistants (Claude Code, Cursor, GitHub Copilot, etc.). > **Requirement:** Your AI assistant must have access to [Context7](https://context7.com/) MCP server or web search capabilities. ### Quick Start Prompts Choose the prompt that matches your task: --- #### 1. Basic Plugin Integration ``` Integrate Pushwoosh Cordova plugin into my Cordova project. Requirements: - Install pushwoosh-cordova-plugin via npm - Initialize Pushwoosh with my App ID in deviceready event - Register for push notifications and handle push-receive and push-notification events Use Context7 MCP to fetch Pushwoosh Cordova plugin documentation. ``` --- #### 2. Tags and User Segmentation ``` Show me how to use Pushwoosh tags in a Cordova 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 Cordova plugin documentation for setTags and getTags. ``` --- #### 3. Message Inbox Integration ``` Integrate Pushwoosh Message Inbox into my Cordova 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 Cordova plugin documentation for presentInboxUI. ``` --- ## Quick Start ### Initialization ```javascript document.addEventListener('deviceready', function() { var pushwoosh = cordova.require("pushwoosh-cordova-plugin.PushNotification"); // 1. Register notification callbacks before initialization document.addEventListener('push-receive', function(event) { var notification = event.notification; console.log("Push received: " + JSON.stringify(notification)); }); document.addEventListener('push-notification', function(event) { var notification = event.notification; console.log("Push opened: " + JSON.stringify(notification)); }); // 2. Initialize Pushwoosh pushwoosh.onDeviceReady({ appid: "XXXXX-XXXXX" // Pushwoosh Application ID }); // 3. Register the device to receive push notifications pushwoosh.registerDevice( function(status) { console.log("Registered with push token: " + status.pushToken); }, function(error) { console.error("Failed to register: " + error); } ); }, false); ``` ### User ID and Events ```javascript var pushwoosh = cordova.require("pushwoosh-cordova-plugin.PushNotification"); pushwoosh.setUserId("user_123"); pushwoosh.postEvent("purchase", { product: "Premium Plan", price: "9.99" }); ``` ### Tags ```javascript var pushwoosh = cordova.require("pushwoosh-cordova-plugin.PushNotification"); // Set tags pushwoosh.setTags( { age: 25, name: "John", favorite_categories: ["sports", "news"] }, function() { console.log("Tags set successfully"); }, function(error) { console.error("Failed to set tags: " + error); } ); // Get tags pushwoosh.getTags( function(tags) { console.log("Tags: " + JSON.stringify(tags)); }, function(error) { console.error("Failed to get tags: " + error); } ); ``` ## API Reference ### Initialization & Registration | Method | Description | |--------|-------------| | `onDeviceReady(config)` | Initialize the plugin. Call on every app launch | | `registerDevice(success, fail)` | Register for push notifications | | `unregisterDevice(success, fail)` | Unregister from push notifications | | `getPushToken(success)` | Get the push token | | `getPushwooshHWID(success)` | Get Pushwoosh Hardware ID | ### Tags & User Data | Method | Description | |--------|-------------| | `setTags(tags, success, fail)` | Set device tags | | `getTags(success, fail)` | Get device tags | | `setUserId(userId)` | Set user identifier for cross-device tracking | | `setLanguage(language)` | Set custom language for localized pushes | | `setEmail(email, success, fail)` | Register email for the user | | `setEmails(emails, success, fail)` | Register multiple emails | ### Notifications | Method | Description | |--------|-------------| | `getRemoteNotificationStatus(success, fail)` | Get push notification permission status | | `getLaunchNotification(success)` | Get notification that launched the app | | `createLocalNotification(config, success, fail)` | Schedule a local notification | | `clearLocalNotification()` | Clear all pending local notifications (Android) | | `clearNotificationCenter()` | Clear all notifications from notification center (Android) | ### Badge Management | Method | Description | |--------|-------------| | `setApplicationIconBadgeNumber(badge)` | Set badge number | | `getApplicationIconBadgeNumber(success)` | 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 | | `addJavaScriptInterface(name)` | Add JS interface for Rich Media communication | ### Message Inbox | Method | Description | |--------|-------------| | `presentInboxUI(params)` | Open inbox UI with optional style customization | | `loadMessages(success, fail)` | Load inbox messages programmatically | | `unreadMessagesCount(success)` | Get unread message count | | `messagesCount(success)` | Get total message count | | `readMessage(id)` | Mark message as read | | `deleteMessage(id)` | Delete a message | | `performAction(id)` | Perform the action associated with a message | ### Communication Control | Method | Description | |--------|-------------| | `setCommunicationEnabled(enable, success, fail)` | Enable/disable all Pushwoosh communication | | `isCommunicationEnabled(success)` | Check if communication is enabled | ### Events | Event | Description | |-------|-------------| | `push-receive` | Fired when a notification is received while the app is active | | `push-notification` | Fired when a notification is opened by the user | ## Plugin Preferences Configure these in your `config.xml`: ```xml ``` | Preference | Default | Description | |-----------|---------|-------------| | `LOG_LEVEL` | `DEBUG` | Logging level | | `IOS_FOREGROUND_ALERT_TYPE` | `ALERT` | iOS foreground notification display type | | `ANDROID_FOREGROUND_PUSH` | `true` | Show notifications when app is in foreground (Android) | | `PW_VOIP_IOS_ENABLED` | `false` | Enable VoIP calling features on iOS | | `PW_VOIP_ANDROID_ENABLED` | `false` | Enable VoIP calling features on Android | ## VoIP in Capacitor This plugin works in Capacitor apps. Capacitor does not execute Cordova hooks, so VoIP dependencies must be added manually to your native projects. ### iOS Add the VoIP pod to `ios/App/Podfile`: ```ruby pod 'PushwooshXCFramework/PushwooshVoIP' ``` Then run `pod install` in the `ios/App/` directory. ### Android Add the property to `android/gradle.properties`: ```properties PW_VOIP_ANDROID_ENABLED=true ``` These changes persist across `cap sync` since Capacitor does not regenerate native projects. ## Forwarding VoIP events to a secondary WebView (iOS) VoIP events (`answer`, `hangup`, `reject`, `voipPushPayload`, etc.) are delivered to the JavaScript callbacks you register with `registerEvent`. If your app presents the call UI in a **secondary native WebView / view controller** on top of the main Cordova (or Capacitor) WebView, the main WebView is backgrounded and its JavaScript engine is suspended, so those callbacks do not run and the event is missed. To cover this, the plugin also broadcasts every VoIP event through `NSNotificationCenter`, independent of WebView state. Observe it in the view controller that owns your secondary WebView and inject the event into that WebView yourself. **Notification** - Name: `PushwooshVoIPEventDispatched` - `userInfo`: - `eventName` (`NSString`) — the event name, same values as `registerEvent` (`"answer"`, `"hangup"`, `"reject"`, `"voipPushPayload"`, ...) - `payload` (`NSDictionary`) — the event payload, identical to the data delivered to JavaScript **Example (Swift)** ```swift NotificationCenter.default.addObserver( forName: Notification.Name("PushwooshVoIPEventDispatched"), object: nil, queue: .main ) { [weak webView] note in guard let webView = webView, let name = note.userInfo?["eventName"] as? String, let payload = note.userInfo?["payload"] as? [String: Any], let data = try? JSONSerialization.data(withJSONObject: payload), let json = String(data: data, encoding: .utf8) else { return } // `window.__pushwooshDispatch` is your own glue inside the secondary WebView's page, // routing the event to your call UI. webView.evaluateJavaScript("window.__pushwooshDispatch('\(name)', \(json))") } ``` The notification fires for every VoIP event and is a no-op when no observer is registered, so it is safe to leave enabled. ## Support - [Documentation](https://docs.pushwoosh.com/) - [Support Portal](https://support.pushwoosh.com/) - [Report Issues](https://github.com/Pushwoosh/pushwoosh-phonegap-plugin/issues) ## License Pushwoosh Cordova Plugin is available under the MIT license. See [LICENSE](LICENSE.md) for details. --- Made with ❤️ by [Pushwoosh](https://www.pushwoosh.com/)