Базовое руководство по интеграции Unity SDK

Это руководство проведет вас через процесс интеграции Pushwoosh Unity SDK в ваше приложение.

Предварительные требования

Аккаунт Pushwoosh.
Проект Pushwoosh, настроенный в вашем аккаунте.
Unity 2021.3 или новее.
Для iOS:
- Платформа iOS, настроенная для отправки push-уведомлений. Мы рекомендуем использовать аутентификацию на основе токена как самый простой подход.
- Установите Gateway на Sandbox, чтобы отправлять пуши в симулятор.
Для Android:
- Настроенная платформа Android.
- project number (также известный как Sender ID), файл google-services.json и package name из вашего проекта Firebase.
- Проект Firebase, подключенный к вашему Android-приложению. При необходимости следуйте руководству по настройке Firebase.
Ваш Pushwoosh Application Code и Pushwoosh Device API Token из панели управления Pushwoosh.

Шаги интеграции

1. Добавьте Pushwoosh Unity SDK

Добавьте следующее в ваш 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"]
    }
  ]
}

Добавляйте только те пакеты платформ, которые вам нужны. Например, опустите com.pushwoosh.unity.android, если вы ориентируетесь только на iOS.

В Unity перейдите в Window > Package Manager > + > Add package from git URL и добавьте следующие URL-адреса один за другим:

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

Скачайте Pushwoosh.unitypackage из GitHub Releases и импортируйте через Assets > Import Package > Custom Package.

2. Установите External Dependency Manager

SDK требует External Dependency Manager for Unity (EDM4U) для разрешения нативных зависимостей Android и iOS.

Добавьте следующий scoped registry в ваш Packages/manifest.json:

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

Затем добавьте пакет в ваши зависимости:

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

3. Инициализируйте SDK

Создайте скрипт PushNotificator.cs и прикрепите его к любому GameObject на сцене:

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();
    }
}

Замените:

XXXXX-XXXXX на ваш Pushwoosh Application Code.
XXXXXXXXXXXX на номер вашего проекта Firebase (только для Android).

4. Нативная настройка iOS

4.1 Capabilities

После сборки iOS-проекта из Unity откройте сгенерированный проект Xcode и добавьте следующие capabilities в Signing & Capabilities:

Push Notifications
Background Modes с отмеченным Remote notifications

Для Time Sensitive Notifications (iOS 15+), также добавьте capability Time Sensitive Notifications.

4.2 Info.plist

Добавьте Pushwoosh Device API Token в ваш Info.plist:

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

4.3 Отслеживание доставки сообщений

Добавьте таргет Notification Service Extension в ваш проект Xcode. Это необходимо для точного отслеживания доставки и Rich Media на iOS.

Следуйте нативному руководству, чтобы добавить таргет расширения.

5. Нативная настройка Android

5.1 Добавьте файл конфигурации Firebase

Поместите файл google-services.json в директорию Assets вашего проекта Unity.

5.2 Добавьте метаданные Pushwoosh

Добавьте Pushwoosh Device API Token в ваш Assets/Plugins/Android/AndroidManifest.xml внутри тега <application>:

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

6. Запустите проект

Соберите и запустите проект на целевой платформе.
Предоставьте разрешение на получение push-уведомлений при запросе.
Перейдите в панель управления Pushwoosh и отправьте push-уведомление.

Расширенная интеграция

На этом этапе вы можете отправлять и получать push-уведомления. В разделах ниже рассматривается основной функционал SDK.

Слушатели событий push-уведомлений

SDK предоставляет два слушателя событий для обработки push-уведомлений:

OnPushNotificationsReceived — срабатывает при поступлении push-уведомления
OnPushNotificationsOpened — срабатывает, когда пользователь нажимает на уведомление

Настройте этих слушателей во время инициализации SDK:

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();
}

Конфигурация пользователя

Персонализируйте push-уведомления, идентифицируя пользователей и устанавливая их свойства:

// Установить User ID для отслеживания на разных устройствах
Pushwoosh.Instance.SetUserId("user-123");

// Установить email пользователя
Pushwoosh.Instance.SetEmail("user@example.com");

// Установить пользователя с ID и email
Pushwoosh.Instance.SetUser("user-123", new List<string> { "user@example.com" });

// Установить предпочитаемый язык
Pushwoosh.Instance.SetLanguage("en");

// Строковый тег
Pushwoosh.Instance.SetStringTag("favorite_category", "electronics");

// Целочисленный тег
Pushwoosh.Instance.SetIntTag("purchase_count", 5);

// Тег-список
Pushwoosh.Instance.SetListTag("interests", new List<object> { "sports", "music", "tech" });

// Получить все теги
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);
    }
});

События

Отслеживайте действия пользователей для анализа поведения и запуска автоматизированных сообщений:

// Отследить событие входа
Pushwoosh.Instance.PostEvent("login", new Dictionary<string, object> {
    { "username", "user-123" },
    { "login_type", "email" }
});

// Отследить событие покупки
Pushwoosh.Instance.PostEvent("purchase", new Dictionary<string, object> {
    { "product_id", "SKU-001" },
    { "price", 29.99 },
    { "currency", "USD" }
});

Предпочтения по коммуникации

Позвольте пользователям программно подписываться или отписываться от push-уведомлений:

// Включить коммуникацию
Pushwoosh.Instance.SetCommunicationEnabled(true);

// Отключить коммуникацию
Pushwoosh.Instance.SetCommunicationEnabled(false);

// Проверить текущее состояние
bool isEnabled = Pushwoosh.Instance.IsCommunicationEnabled();

Управление бейджами

Управляйте числом на бейдже приложения на поддерживаемых платформах:

// Установить бейдж на определенное число
Pushwoosh.Instance.SetBadgeNumber(3);

// Увеличить бейдж
Pushwoosh.Instance.AddBadgeNumber(1);

// Очистить бейдж
Pushwoosh.Instance.SetBadgeNumber(0);

Устранение неполадок

Если у вас возникнут какие-либо проблемы в процессе интеграции, обратитесь к разделу поддержки и сообщества.