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.
• 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.2.7",
    "com.pushwoosh.unity.android": "6.2.7",
    "com.pushwoosh.unity.ios": "6.2.7"
  },
  "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 SDK requires External Dependency Manager for Unity (EDM4U) to resolve native Android and iOS dependencies.

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. 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).

4. iOS native setup

4.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.

4.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>

4.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.

5. Android native setup

5.1 Add Firebase configuration file

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

5.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

6. 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 you encounter any issues during the integration process, refer to the support and community section.