Unity SDK basic integration guide

This guide walks you through integrating the Pushwoosh Unity SDK into your application.

Prerequisites

Requirements

• A Pushwoosh account.
• A Pushwoosh project set up in your account.
• Unity 2021.3 or later.
• For iOS:
  • An iOS platform configured to send push notifications. We recommend using Token-Based Authentication as the simplest approach.
  • Set the Gateway to Sandbox to send pushes to a simulator.
  • To get the native iOS SDK with Swift Package Manager: Unity 2021.3.15 or later, Target minimum iOS Version set to 15.0 or later, and access to github.com when Xcode builds the project. With Unity 2021.3.0–2021.3.14 or a lower iOS target, the SDK is added with CocoaPods (see Choose how the iOS SDK is added).
• For Android:
  • A configured Android platform.
  • The project number (also known as Sender ID), 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.

Integration steps

1. Add Pushwoosh Unity SDK

UPM via Scoped Registry (recommended)

Add the following to your Packages/manifest.json:

Packages/manifest.json

{
  "dependencies": {
    "com.pushwoosh.unity.core": "6.3.0",
    "com.pushwoosh.unity.android": "6.3.0",
    "com.pushwoosh.unity.ios": "6.3.0"
  },
  "scopedRegistries": [
    {
      "name": "npmjs",
      "url": "https://registry.npmjs.org",
      "scopes": ["com.pushwoosh"]
    }
  ]
}

Add only the platform packages you need. For example, omit com.pushwoosh.unity.android if you only target iOS.

UPM via Git URL

In Unity, go to Window > Package Manager > + > Add package from git URL and add the following URLs one by one:

https://github.com/Pushwoosh/pushwoosh-unity.git?path=com.pushwoosh.unity.core
https://github.com/Pushwoosh/pushwoosh-unity.git?path=com.pushwoosh.unity.android
https://github.com/Pushwoosh/pushwoosh-unity.git?path=com.pushwoosh.unity.ios

.unitypackage

Download Pushwoosh.unitypackage from GitHub Releases and import via Assets > Import Package > Custom Package.

2. Install External Dependency Manager

The Android part of the SDK requires External Dependency Manager for Unity (EDM4U) to resolve native Android dependencies. Skip this step if you only target iOS.

Add the following scoped registry to your Packages/manifest.json:

{
  "scopedRegistries": [
    {
      "name": "package.openupm.com",
      "url": "https://package.openupm.com",
      "scopes": ["com.google.external-dependency-manager"]
    }
  ]
}

Then add the package to your dependencies:

"com.google.external-dependency-manager": "1.2.183"

3. Choose how the iOS SDK is added

By default, the iOS export gets the native SDK from the Swift package Pushwoosh-XCFramework with Swift Package Manager. You don’t need CocoaPods or EDM4U for iOS, and you don’t run pod install.

To change the source of the iOS SDK or add optional modules, open Window > Pushwoosh SDK Setup in the Unity Editor:

• In iOS SDK from, select Swift Package Manager or CocoaPods.
• With Swift Package Manager, under Modules (Swift Package Manager only), select the optional modules your app uses: PushwooshLiveActivities, PushwooshInboxKit, PushwooshInApp, PushwooshVoIP, PushwooshForegroundPush, PushwooshKeychain, PushwooshGRPC, PushwooshGeozones. The modules are linked to the app target. To use a module in your own app extension, add it to the extension target in Xcode. With CocoaPods, the export goes without these modules.

The export falls back to CocoaPods, and the Unity console states the reason, when any of these applies:

• CocoaPods is selected in Window > Pushwoosh SDK Setup.
• The project already has a PushwooshXCFramework pod, in a *Dependencies.xml file read by EDM4U or in the Podfile. To switch to Swift Package Manager, remove the pod. For Geozones, remove the PushwooshXCFramework/Geozones pod and select PushwooshGeozones in Window > Pushwoosh SDK Setup.
• The Unity version is earlier than 2021.3.15.
• Target minimum iOS Version is below 15.0.

With CocoaPods, EDM4U isn’t required. The SDK runs pod install after the export and generates the Podfile itself, unless EDM4U is installed and writes the Podfile instead. If pod install fails, the Unity console shows the error. Run pod install in the exported Xcode project folder.

If your build environment can’t reach github.com, Xcode can’t resolve the Swift package. Select CocoaPods in Window > Pushwoosh SDK Setup for such builds.

The Swift Package Manager export keeps Unity-iPhone.xcworkspace, so build scripts and CI that build the workspace work without changes.

Updating from a CocoaPods setup

When you update to 6.3.0 or later, a project that got the iOS SDK through CocoaPods or EDM4U switches to Swift Package Manager, unless one of the conditions above keeps it on CocoaPods.

• To keep CocoaPods, select it in Window > Pushwoosh SDK Setup.
• If you export with Swift Package Manager into the folder of a previous CocoaPods export, the Pushwoosh pod is removed from the Podfile, but the Xcode project still references Pods and builds only from Unity-iPhone.xcworkspace. Build the workspace, or export into a new folder to get a project without CocoaPods.

4. Initialize the SDK

Create a PushNotificator.cs script and attach it to any GameObject in the scene:

PushNotificator.cs

using UnityEngine;
using System.Collections.Generic;

public class PushNotificator : MonoBehaviour
{
    void Start()
    {
        Pushwoosh.ApplicationCode = "XXXXX-XXXXX";
        Pushwoosh.FcmProjectNumber = "XXXXXXXXXXXX";

        Pushwoosh.Instance.OnRegisteredForPushNotifications += (token) => {
            Debug.Log("Push token: " + token);
        };

        Pushwoosh.Instance.OnFailedToRegisteredForPushNotifications += (error) => {
            Debug.Log("Registration failed: " + error);
        };

        Pushwoosh.Instance.RegisterForPushNotifications();
    }
}

Replace:

• XXXXX-XXXXX with your Pushwoosh Application Code.
• XXXXXXXXXXXX with your Firebase project number (Android only).

5. iOS native setup

5.1 Capabilities

After building the iOS project from Unity, open the generated Xcode project and add the following capabilities in Signing & Capabilities:

• Push Notifications
• Background Modes with Remote notifications checked

For Time Sensitive Notifications (iOS 15+), also add the Time Sensitive Notifications capability.

5.2 Info.plist

Add the Pushwoosh Device API Token to your Info.plist:

Info.plist

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

5.3 Message delivery tracking

Add a Notification Service Extension target to your Xcode project. This is required for accurate delivery tracking and Rich Media on iOS.

Follow the native guide to add the extension target.

6. Android native setup

6.1 Add Firebase configuration file

Place the google-services.json file into your Unity project’s Assets directory.

6.2 Add Pushwoosh metadata

Add the Pushwoosh Device API Token to your Assets/Plugins/Android/AndroidManifest.xml inside the <application> tag:

AndroidManifest.xml

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

Caution

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

7. Run the project

1. Build and run the project on your target platform.
2. Grant permission for push notifications when prompted.
3. Go to the Pushwoosh Control Panel and send a push notification.

Extended integration

At this stage, you can send and receive push notifications. The sections below cover the core SDK functionality.

Push notification event listeners

The SDK provides two event listeners for handling push notifications:

• OnPushNotificationsReceived — triggered when a push notification arrives
• OnPushNotificationsOpened — triggered when a user taps a notification

Set up these listeners during SDK initialization:

PushNotificator.cs

void Start()
{
    Pushwoosh.ApplicationCode = "XXXXX-XXXXX";
    Pushwoosh.FcmProjectNumber = "XXXXXXXXXXXX";

    Pushwoosh.Instance.OnPushNotificationsReceived += (payload) => {
        Debug.Log("Push received: " + payload);
    };

    Pushwoosh.Instance.OnPushNotificationsOpened += (payload) => {
        Debug.Log("Push opened: " + payload);
    };

    Pushwoosh.Instance.RegisterForPushNotifications();
}

User configuration

Personalize push notifications by identifying users and setting their properties:

// Set user ID for cross-device tracking
Pushwoosh.Instance.SetUserId("user-123");

// Set user email
Pushwoosh.Instance.SetEmail("user@example.com");

// Set user with both ID and email
Pushwoosh.Instance.SetUser("user-123", new List<string> { "user@example.com" });

// Set preferred language
Pushwoosh.Instance.SetLanguage("en");

Tags

Tags are key-value pairs assigned to devices, enabling user segmentation and targeted messaging:

// String tag
Pushwoosh.Instance.SetStringTag("favorite_category", "electronics");

// Integer tag
Pushwoosh.Instance.SetIntTag("purchase_count", 5);

// List tag
Pushwoosh.Instance.SetListTag("interests", new List<object> { "sports", "music", "tech" });

// Get all tags
Pushwoosh.Instance.GetTags((tags, error) => {
    if (error != null) {
        Debug.Log("Error: " + error.Message);
        return;
    }
    foreach (var tag in tags) {
        Debug.Log(tag.Key + ": " + tag.Value);
    }
});

Events

Track user actions to analyze behavior and trigger automated messages:

// Track a login event
Pushwoosh.Instance.PostEvent("login", new Dictionary<string, object> {
    { "username", "user-123" },
    { "login_type", "email" }
});

// Track a purchase event
Pushwoosh.Instance.PostEvent("purchase", new Dictionary<string, object> {
    { "product_id", "SKU-001" },
    { "price", 29.99 },
    { "currency", "USD" }
});

Communication preferences

Allow users to opt in or out of push notifications programmatically:

// Enable communication
Pushwoosh.Instance.SetCommunicationEnabled(true);

// Disable communication
Pushwoosh.Instance.SetCommunicationEnabled(false);

// Check current state
bool isEnabled = Pushwoosh.Instance.IsCommunicationEnabled();

Badge management

Control the app badge number on supported platforms:

// Set badge to a specific number
Pushwoosh.Instance.SetBadgeNumber(3);

// Increment badge
Pushwoosh.Instance.AddBadgeNumber(1);

// Clear badge
Pushwoosh.Instance.SetBadgeNumber(0);

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, refer to the support and community section.