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

В этом руководстве рассказывается, как интегрировать Pushwoosh Unity SDK в ваше приложение.

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

Аккаунт Pushwoosh.
Проект Pushwoosh, настроенный в вашем аккаунте.
Unity 2021.3 или более поздней версии.
Для iOS:
- Платформа iOS, настроенная для отправки push-уведомлений. Мы рекомендуем использовать аутентификацию на основе токенов как самый простой подход.
- Установите Gateway на Sandbox, чтобы отправлять push-уведомления на симулятор.
- Чтобы получать нативный iOS SDK через Swift Package Manager: Unity 2021.3.15 или новее, Target minimum iOS Version 15.0 или выше и доступ к github.com во время сборки проекта в Xcode. С Unity 2021.3.0–2021.3.14 или более низкой целевой версией iOS SDK добавляется через CocoaPods (см. Выберите способ добавления iOS SDK).
Для 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.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"]
    }
  ]
}

Добавляйте только те пакеты платформ, которые вам нужны. Например, опустите 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 и импортируйте через Assets > Import Package > Custom Package.

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

Android-части 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. Выберите способ добавления iOS SDK

По умолчанию при экспорте для iOS нативный SDK подключается из Swift-пакета Pushwoosh-XCFramework через Swift Package Manager. CocoaPods и EDM4U для iOS не нужны, и pod install запускать не требуется.

Чтобы изменить источник iOS SDK или добавить дополнительные модули, откройте Window > Pushwoosh SDK Setup в Unity Editor:

В поле iOS SDK from выберите Swift Package Manager или CocoaPods.
При использовании Swift Package Manager в разделе Modules (Swift Package Manager only) выберите дополнительные модули, которые использует ваше приложение: PushwooshLiveActivities, PushwooshInboxKit, PushwooshInApp, PushwooshVoIP, PushwooshForegroundPush, PushwooshKeychain, PushwooshGRPC, PushwooshGeozones. Модули подключаются к таргету приложения. Чтобы использовать модуль в собственном расширении приложения, добавьте его к таргету расширения в Xcode. При использовании CocoaPods экспорт выполняется без этих модулей.

Экспорт переключается на CocoaPods, а консоль Unity сообщает причину, если выполняется любое из условий:

В Window > Pushwoosh SDK Setup выбран CocoaPods.
В проекте уже есть под PushwooshXCFramework — в файле *Dependencies.xml, который читает EDM4U, или в Podfile. Чтобы перейти на Swift Package Manager, удалите этот под. Для Geozones удалите под PushwooshXCFramework/Geozones и выберите PushwooshGeozones в Window > Pushwoosh SDK Setup.
Версия Unity ниже 2021.3.15.
Target minimum iOS Version ниже 15.0.

С CocoaPods EDM4U не требуется. SDK запускает pod install после экспорта и сам генерирует Podfile, если только не установлен EDM4U, который в этом случае записывает Podfile вместо него. Если pod install завершается с ошибкой, консоль Unity показывает эту ошибку. Запустите pod install в папке экспортированного проекта Xcode.

Если среда сборки не имеет доступа к github.com, Xcode не сможет разрешить Swift-пакет. Для таких сборок выберите CocoaPods в Window > Pushwoosh SDK Setup.

При экспорте через Swift Package Manager сохраняется Unity-iPhone.xcworkspace, поэтому скрипты сборки и CI, которые собирают workspace, работают без изменений.

При обновлении до версии 6.3.0 или новее проект, который получал iOS SDK через CocoaPods или EDM4U, переходит на Swift Package Manager, если только одно из условий выше не оставляет его на CocoaPods.

Чтобы остаться на CocoaPods, выберите его в Window > Pushwoosh SDK Setup.
Если вы экспортируете проект через Swift Package Manager в папку предыдущего экспорта с CocoaPods, под Pushwoosh удаляется из Podfile, но проект Xcode по-прежнему ссылается на Pods и собирается только из Unity-iPhone.xcworkspace. Собирайте workspace или экспортируйте в новую папку, чтобы получить проект без CocoaPods.

4. Инициализируйте 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).

5. Нативная настройка для iOS

5.1 Capabilities

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

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

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

5.2 Info.plist

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

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

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

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

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

6. Нативная настройка для Android

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

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

6.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__" />

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

Соберите и запустите проект на целевой платформе.
Предоставьте разрешение на получение 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();

Управление значком приложения (badge)

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

// Установить конкретное число на значке
Pushwoosh.Instance.SetBadgeNumber(3);

// Увеличить число на значке
Pushwoosh.Instance.AddBadgeNumber(1);

// Очистить значок
Pushwoosh.Instance.SetBadgeNumber(0);

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

Если push не доставлен, найдите код ошибки для вашей платформы в разделе Ошибки отправки: там описано, что он означает и как его исправить.

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