Capacitor SDK Basic integration guide

This section contains information on how to integrate the Pushwoosh Capacitor SDK into your application.

Prerequisites

To integrate the Pushwoosh Capacitor SDK into your app, you will need the following:

Requirements

• A Pushwoosh account.
• A Pushwoosh project set up in your account.
• For iOS integration:
  • An iOS platform configured to send push notifications. We recommend using the Token-Based Authentication configuration as the simplest approach.
  • Set the Gateway to Sandbox to send pushes to a simulator.
  • To add the plugin with Swift Package Manager: Capacitor 7 or 8. To migrate a CocoaPods project to Swift Package Manager: @capacitor/cli 7.4.0 or later.
• For Android integration:
  • A configured Android platform
  • The google-services.json file and package name from your Firebase project.
  • A Firebase project connected to your Android application. Follow the Firebase setup guide if needed.
• Your Pushwoosh Application Code and Pushwoosh Device API Token from the Pushwoosh Control Panel for your application.

Integration steps

1. Add Pushwoosh Capacitor SDK Dependency

Add the Pushwoosh Capacitor SDK dependency to your project:

npm install pushwoosh-capacitor-plugin

Sync the Capacitor configuration:

npx cap sync

1.1 Choose the iOS package manager

npx cap sync installs the iOS part of the plugin with the package manager your Capacitor project uses: Swift Package Manager or CocoaPods. Both ship the same native Pushwoosh SDK version and Inbox UI. Swift Package Manager is supported with Capacitor 7 and Capacitor 8.

An existing project keeps its package manager: if ios/App/CapApp-SPM exists, the Capacitor CLI uses Swift Package Manager, otherwise CocoaPods. For a new iOS platform:

Capacitor 8

Capacitor 8 creates a Swift Package Manager project by default:

npx cap add ios

To use CocoaPods instead, run npx cap add ios --packagemanager CocoaPods.

Capacitor 7

Capacitor 7 creates a CocoaPods project by default. To use Swift Package Manager, run:

npx cap add ios --packagemanager SPM

The command creates the project and then stops with an ENOENT ... Podfile error while trying to run pod install. The project is created correctly. Finish the setup with:

npx cap sync ios

With Swift Package Manager, the Capacitor CLI adds the plugin to ios/App/CapApp-SPM, and the plugin brings in the Pushwoosh iOS SDK and Inbox UI. Don’t add the Pushwoosh SDK to the app a second time, as a pod or as a package with a different version.

CocoaPods deprecation

CocoaPods trunk becomes read-only on December 2, 2026, and Pushwoosh moves the iOS SDK to Swift Package Manager. Plugin releases after that date will use the Swift package only. Until then, pod install and the Xcode build of a CocoaPods project show a warning about it. The warning doesn’t affect the build.

To migrate an existing CocoaPods project, run npx cap spm-migration-assistant, then follow the manual Xcode step it links to. The command needs @capacitor/cli 7.4.0 or later.

2. Capacitor SDK Initialization

In your main JavaScript file, import and initialize the Pushwoosh SDK:

index.js

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

// Initialize the SDK
Pushwoosh.onDeviceReady({
    appid: "__YOUR_APP_CODE__"
});

// Register for push notifications
Pushwoosh.registerDevice()
    .then(result => {
        console.log("Push token:", result.pushToken);
        // Handle successful registration
    })
    .catch(error => {
        console.error("Failed to register device:", error);
        // Handle registration error
    });

Where:

• __YOUR_APP_CODE__ is the application code from the Pushwoosh Control Panel.

3. iOS Native Setup

3.1 Capabilities

To enable Push Notifications in your project, you need to add certain capabilities.

In the Signing & Capabilities section, add the following capabilities:

• Push Notifications
• Background Modes. After adding this capability, check the box for Remote notifications.

If you intend to use Time Sensitive Notifications (iOS 15+), also add the Time Sensitive Notifications capability.

3.2 Info.plist

In your ios/App/App/Info.plist set the __PUSHWOOSH_DEVICE_API_TOKEN__ key to the Pushwoosh Device API Token:

info.plist

<key>Pushwoosh_API_TOKEN</key>
<string>__PUSHWOOSH_DEVICE_API_TOKEN__</string>

3.3 Message delivery tracking

You 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. Add the Pushwoosh SDK to the extension target according to your package manager:

• CocoaPods: follow the native guide’s Dependencies for the Notification Service Extension step. In ios/App/Podfile, add pod 'PushwooshXCFramework' without a version to the extension target, so it resolves to the version the plugin uses, then run npx cap sync ios.

• Swift Package Manager: skip the native guide’s CocoaPods dependencies step. Add the SDK to the extension target in Xcode yourself, because the target doesn’t inherit the plugin’s dependencies:

  1. Open the extension target > General > Frameworks and Libraries.
  2. Add the PushwooshFramework product of the Pushwoosh-XCFramework package. Use the version already in Package.resolved.

  If you migrated from CocoaPods, make sure the extension no longer gets PushwooshXCFramework as a pod, so the app doesn’t include the SDK twice.

Then import PushwooshFramework in the extension code. The App target needs nothing extra, as it gets the Pushwoosh SDK through the plugin.

4. Android Native Setup

4.1 Install dependencies

Ensure that the required dependencies and plugins are added to your Gradle scripts:

Add the Google Services Gradle plugin to your project-level build.gradle dependencies:

android/build.gradle

buildscript {
  dependencies {
    classpath 'com.google.gms:google-services:4.3.15'
  }
}

Apply the plugin in your app-level build.gradle file:

app/build.gradle

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

4.2 Add Firebase configuration file

Place the google-services.json file into android/app folder in your project directory.

4.3 Add Pushwoosh metadata

In your main/AndroidManifest.xml add Pushwoosh Device API Token inside the <application> tag:

AndroidManifest.xml

<meta-data android:name="com.pushwoosh.apitoken" android:value="__YOUR_DEVICE_API_TOKEN__" />

Important: Be sure to give the token access to the right app in your Pushwoosh Control Panel. Learn more

5. Run the Project

1. Build and run the project.
2. Go to the Pushwoosh Control Panel and send a push notification.
3. You should see the notification in the app.

Extended integration

At 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

In the Pushwoosh Capacitor SDK there are two callback methods for handling push notifications:

• pushReceivedCallback is triggered when a push notification is received
• pushOpenedCallback is triggered when a user opens a notification

You should set up these callbacks right after initialization of the SDK:

index.js

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

// Set up push received callback
await Pushwoosh.pushReceivedCallback((notification, err) => {
    if (err) {
        console.error("Failed to process received notification:", err);
    } else {
        console.log("Push received:", JSON.stringify(notification));
        // Handle the received notification
    }
});

// Set up push opened callback
await Pushwoosh.pushOpenedCallback((notification, err) => {
    if (err) {
        console.error("Failed to process opened notification:", err);
    } else {
        console.log("Push opened:", JSON.stringify(notification));
        // Handle the opened notification
    }
});

User configuration

By focusing on individual user behavior and preferences, you can deliver personalized content, leading to increased user satisfaction and loyalty

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

class Registration {
  async afterUserLogin(user) {

    // Set user ID
    Pushwoosh.setUserId(user.getId);

    // Setting additional user information as tags for Pushwoosh
    await Pushwoosh.setTags({
      "age": user.getAge(),
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }
}

Tags

Tags 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-capacitor-plugin';

class UpdateUser {
 async afterUserUpdateProfile(user) {

    // Set list of favorite categories
    await Pushwoosh.setTags({
      "favorite_categories": user.getFavoriteCategoriesList()
    });

    // Set payment information
    await Pushwoosh.setTags({
      "is_subscribed": user.isSubscribed(),
      "payment_status": user.getPaymentStatus(),
      "billing_address": user.getBillingAddress()
    });
  }
}

Events

Events 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-capacitor-plugin';

class Registration {

  // Track login event
  afterUserLogin(user) {
    Pushwoosh.postEvent("login", {
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }

  // Track purchase event
  afterUserPurchase(product) {
    Pushwoosh.postEvent("purchase", {
      "product_id": product.getId(),
      "product_name": product.getName(),
      "price": product.getPrice(),
      "quantity": product.getQuantity()
    });
  }
}

Troubleshooting

If a push isn’t delivered, find the error code for your platform in Sending errors to see what it means and how to fix it.

If you encounter any issues during the integration process, please refer to the support and community section.