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

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

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

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

Требования

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

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

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

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

npm install pushwoosh-capacitor-plugin

Синхронизируйте конфигурацию Capacitor:

npx cap sync

1.1 Выберите менеджер пакетов iOS

npx cap sync устанавливает iOS-часть плагина с помощью менеджера пакетов, который использует ваш проект Capacitor: Swift Package Manager или CocoaPods. Оба варианта поставляют одну и ту же версию нативного Pushwoosh SDK и Inbox UI. Swift Package Manager поддерживается в Capacitor 7 и Capacitor 8.

Существующий проект сохраняет свой менеджер пакетов: если существует ios/App/CapApp-SPM, Capacitor CLI использует Swift Package Manager, иначе — CocoaPods. Для новой платформы iOS:

Capacitor 8

Capacitor 8 по умолчанию создает проект Swift Package Manager:

npx cap add ios

Чтобы использовать CocoaPods, выполните npx cap add ios --packagemanager CocoaPods.

Capacitor 7

Capacitor 7 по умолчанию создает проект CocoaPods. Чтобы использовать Swift Package Manager, выполните:

npx cap add ios --packagemanager SPM

Команда создает проект, а затем останавливается с ошибкой ENOENT ... Podfile при попытке выполнить pod install. Проект при этом создан корректно. Завершите настройку командой:

npx cap sync ios

При использовании Swift Package Manager Capacitor CLI добавляет плагин в ios/App/CapApp-SPM, а плагин подключает Pushwoosh iOS SDK и Inbox UI. Не добавляйте Pushwoosh SDK в приложение повторно — ни как pod, ни как пакет другой версии.

Прекращение поддержки CocoaPods

CocoaPods trunk перейдет в режим только для чтения 2 декабря 2026 года, и Pushwoosh переводит iOS SDK на Swift Package Manager. Версии плагина, выпущенные после этой даты, будут использовать только Swift-пакет. До этого pod install и сборка проекта CocoaPods в Xcode показывают об этом предупреждение. Предупреждение не влияет на сборку.

Чтобы перевести существующий проект CocoaPods, выполните npx cap spm-migration-assistant, а затем выполните ручной шаг в Xcode, на который ссылается команда. Команде нужен @capacitor/cli 7.4.0 или новее.

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

В вашем основном JavaScript файле импортируйте и инициализируйте Pushwoosh SDK:

index.js

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

// Инициализация SDK
Pushwoosh.onDeviceReady({
    appid: "__YOUR_APP_CODE__"
});

// Регистрация для получения push-уведомлений
Pushwoosh.registerDevice()
    .then(result => {
        console.log("Push token:", result.pushToken);
        // Обработка успешной регистрации
    })
    .catch(error => {
        console.error("Failed to register device:", error);
        // Обработка ошибки регистрации
    });

Где:

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

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

В вашем файле ios/App/App/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 в него. Добавьте Pushwoosh SDK в таргет расширения в зависимости от менеджера пакетов:

• CocoaPods: выполните шаг Зависимости для Notification Service Extension (только для CocoaPods) из руководства по нативной интеграции. В ios/App/Podfile добавьте pod 'PushwooshXCFramework' без версии в таргет расширения, чтобы он разрешился в ту же версию, что использует плагин, затем выполните npx cap sync ios.

• Swift Package Manager: пропустите шаг с зависимостями CocoaPods из руководства по нативной интеграции. Добавьте SDK в таргет расширения в Xcode самостоятельно, потому что таргет не наследует зависимости плагина:

  1. Откройте таргет расширения > General > Frameworks and Libraries.
  2. Добавьте продукт PushwooshFramework из пакета Pushwoosh-XCFramework. Используйте версию, которая уже указана в Package.resolved.

  Если вы перешли с CocoaPods, убедитесь, что расширение больше не получает PushwooshXCFramework как pod, чтобы SDK не попал в приложение дважды.

Затем добавьте import PushwooshFramework в код расширения. Таргету App ничего дополнительно не нужно: он получает Pushwoosh SDK через плагин.

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 Capacitor SDK есть два callback-метода для обработки push-уведомлений:

• pushReceivedCallback срабатывает при получении push-уведомления
• pushOpenedCallback срабатывает, когда пользователь открывает уведомление

Вам следует настроить эти колбэки сразу после инициализации SDK:

index.js

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

// Настройка колбэка получения пуша
await Pushwoosh.pushReceivedCallback((notification, err) => {
    if (err) {
        console.error("Failed to process received notification:", err);
    } else {
        console.log("Push received:", JSON.stringify(notification));
        // Обработка полученного уведомления
    }
});

// Настройка колбэка открытия пуша
await Pushwoosh.pushOpenedCallback((notification, err) => {
    if (err) {
        console.error("Failed to process opened notification:", err);
    } else {
        console.log("Push opened:", JSON.stringify(notification));
        // Обработка открытого уведомления
    }
});

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

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

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

class Registration {
  async afterUserLogin(user) {

    // Установка User ID
    Pushwoosh.setUserId(user.getId);

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

Теги

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

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

class UpdateUser {
 async afterUserUpdateProfile(user) {

    // Установка списка избранных категорий
    await Pushwoosh.setTags({
      "favorite_categories": user.getFavoriteCategoriesList()
    });

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

События

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

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

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

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

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

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