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

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

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

Для интеграции Pushwoosh Cordova SDK в ваше приложение вам потребуется следующее:

Требования

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

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

1. Добавьте зависимость Pushwoosh Cordova SDK

Добавьте зависимость Pushwoosh Cordova SDK в ваш проект:

cordova plugin add pushwoosh-cordova-plugin

2. Инициализация Cordova SDK

В корневом компоненте вашего файла index.js добавьте следующий код внутри обработчика события deviceready. Выполняйте шаги в точном порядке:

index.js

document.addEventListener('deviceready', function() {
    var pushwoosh = cordova.require("pushwoosh-cordova-plugin.PushNotification");

    // 1. Зарегистрируйте колбэки уведомлений перед инициализацией
    document.addEventListener('push-receive', function(event) {
        var notification = event.notification;
        console.log("Push received: " + JSON.stringify(notification));
    });

    document.addEventListener('push-notification', function(event) {
        var notification = event.notification;
        console.log("Push opened: " + JSON.stringify(notification));
    });

    // 2. Инициализируйте Pushwoosh
    pushwoosh.onDeviceReady({
        appid: "__YOUR_APP_ID__"
    });

    // 3. Зарегистрируйте устройство для получения push-уведомлений
    pushwoosh.registerDevice(
        function(status) {
            var pushToken = status.pushToken;
            // Обработка успешной регистрации
        },
        function(status) {
            // Обработка ошибки регистрации
        }
    );
}, false);

Где:

• __YOUR_APP_ID__ — это код приложения из панели управления Pushwoosh.

Порядок инициализации важен

Последовательность инициализации должна строго соответствовать порядку, указанному выше:

1. Сначала зарегистрируйте обработчики событий (push-receive, push-notification)
2. Затем вызовите onDeviceReady()
3. Затем вызовите registerDevice()

Изменение этого порядка может вызвать следующие проблемы:

• Обработчики событий зарегистрированы после onDeviceReady(): Если приложение было запущено нажатием на push-уведомление (холодный запуск), onDeviceReady() немедленно доставляет полезную нагрузку уведомления о запуске в JavaScript. Если ваши обработчики еще не зарегистрированы в этот момент, уведомление о запуске будет потеряно без возможности его восстановить.
• registerDevice() вызван до onDeviceReady(): Нативный SDK может быть еще не правильно сконфигурирован с вашим App ID, что может привести к тому, что регистрация устройства завершится неудачей без уведомления или вернет ошибку.
• Обработчики событий зарегистрированы после registerDevice(): Любое push-уведомление, которое придет и будет обработано до того, как ваши обработчики будут установлены, будет отправлено как DOM-событие и молча отброшено, так как в плагине нет механизма повторной отправки.

Плагин не ставит в очередь и не буферизует пропущенные события на стороне JavaScript. DOM-события, инициированные document.dispatchEvent(), доставляются только тем обработчикам, которые уже зарегистрированы на момент отправки.

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

3.1 Capabilities

Чтобы включить Push-уведомления в вашем проекте, вам необходимо добавить определенные capabilities.

В разделе Signing & Capabilities добавьте следующие capabilities:

• Push Notifications
• Background Modes. После добавления этой capability, установите флажок для Remote notifications.

Если вы собираетесь использовать Time Sensitive Notifications (iOS 15+), также добавьте capability Time Sensitive Notifications.

3.2 Info.plist

В вашем Runner/Info.plist установите ключ __PUSHWOOSH_DEVICE_API_TOKEN__ на Pushwoosh Device API Token:

info.plist

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

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

Вы должны добавить цель Notification Service Extension в ваш проект. Это необходимо для точного отслеживания доставки и таких функций, как Rich Media на iOS.

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

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

4.1 Установка зависимостей

Убедитесь, что необходимые зависимости и плагины добавлены в ваши скрипты Gradle:

Добавьте плагин Google Services Gradle в зависимости вашего build.gradle на уровне проекта:

android/build.gradle

buildscript {
  dependencies {
    classpath 'com.google.gms:google-services:4.3.15'
  }
}

Примените плагин в вашем файле build.gradle на уровне приложения:

app/build.gradle

apply plugin: 'com.google.gms.google-services'

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

Поместите файл google-services.json в папку android/app в каталоге вашего проекта.

4.3 Добавление метаданных Pushwoosh

В вашем main/AndroidManifest.xml добавьте Pushwoosh Device API Token внутри тега <application>:

AndroidManifest.xml

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

Важно: Убедитесь, что вы предоставили токену доступ к нужному приложению в вашей панели управления Pushwoosh. Узнать больше

5. Запуск проекта

1. Соберите и запустите проект.
2. Перейдите в панель управления Pushwoosh и отправьте push-уведомление.
3. Вы должны увидеть уведомление в приложении.

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

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

Обработчики событий push-уведомлений

В Pushwoosh SDK есть два обработчика событий, предназначенных для обработки push-уведомлений:

• Событие push-receive срабатывает, когда push-уведомление получено, пока приложение находится на переднем плане.
• Событие push-notification срабатывает, когда пользователь открывает уведомление.

Эти обработчики событий должны быть зарегистрированы до вызова onDeviceReady(), как показано в шаге инициализации выше. Вы можете настроить логику обработчика в соответствии с вашими потребностями:

index.js

// Зарегистрируйте до onDeviceReady()
document.addEventListener('push-receive', function(event) {
    var message = event.notification.message;
    var payload = event.notification.userdata;
    console.log("Push received: " + message);
    // Добавьте свою кастомную логику здесь
});

document.addEventListener('push-notification', function(event) {
    var message = event.notification.message;
    var payload = event.notification.userdata;
    console.log("Push accepted: " + message);
    // Добавьте свою кастомную логику здесь (например, переход на определенный экран)
});

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

Сосредоточившись на поведении и предпочтениях отдельных пользователей, вы можете предоставлять персонализированный контент, что приведет к повышению удовлетворенности и лояльности пользователей.

class Registration {
  afterUserLogin(user) {

    // Установить ID пользователя
    pushwoosh.setUserId(user.getId());

    // Установка дополнительной информации о пользователе в качестве тегов для Pushwoosh
    pushwoosh.setTags({
      "age": user.getAge(),
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }
}

Теги

Теги — это пары ключ-значение, присваиваемые пользователям или устройствам, позволяющие сегментировать их по атрибутам, таким как предпочтения или поведение, что обеспечивает целевую рассылку сообщений.

class UpdateUser {
  afterUserUpdateProfile(user) {

    // Установить список любимых категорий
    pushwoosh.setTags({
      "favorite_categories": user.getFavoriteCategoriesList()
    });

    // Установить платежную информацию
    pushwoosh.setTags({
      "is_subscribed": user.isSubscribed(),
      "payment_status": user.getPaymentStatus(),
      "billing_address": user.getBillingAddress()
    });
  }
}

События

События — это конкретные действия или происшествия пользователя в приложении, которые можно отслеживать для анализа поведения и запуска соответствующих сообщений или действий.

class Registration {

  // Отслеживать событие входа
  afterUserLogin(user) {
    pushwoosh.postEvent("login", {
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }

  // Отслеживать событие покупки
  afterUserPurchase(product) {
    pushwoosh.postEvent("purchase", {
      "product_id": product.getId(),
      "product_name": product.getName(),
      "price": product.getPrice(),
      "quantity": product.getQuantity()
    });
  }
}

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

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