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

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

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

Аккаунт Pushwoosh.
Проект Pushwoosh, настроенный в вашем аккаунте.
Unity 2021.3 или более поздней версии.
Для iOS:
- Платформа iOS, настроенная для отправки push-уведомлений. Мы рекомендуем использовать аутентификацию на основе токенов как самый простой подход.
- Установите Gateway на Sandbox, чтобы отправлять push-уведомления на симулятор.
Для 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 и импортируйте через 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 target в ваш проект Xcode. Это необходимо для точного отслеживания доставки и Rich Media на iOS.

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

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

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

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

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

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

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

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

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