Cordova SDK: Руководство по базовой интеграции

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

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

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

Требования

• Аккаунт Pushwoosh.
• Проект Pushwoosh, настроенный в вашем аккаунте.
• Для интеграции с 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 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__",
        projectid: "__YOUR_FCM_SENDER_ID__"
    });

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

Где:

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

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

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

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

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

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

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

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

3.1 Capabilities

Чтобы включить Push Notifications в вашем проекте, вам нужно добавить определенные 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) {

    // Установить 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()
    });
  }
}

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

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