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

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

Необходимые условия

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

Требования

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

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

1. Добавьте зависимость Wavesend Flutter SDK

Добавьте пакет pushwoosh_flutter в ваш файл pubspec.yaml:

pubspec.yaml

dependencies:
  flutter:
    sdk: flutter
  # Используйте последнюю версию с https://pub.dev/packages/pushwoosh_flutter
  pushwoosh_flutter: ^[LATEST_VERSION]

Проверьте последнюю версию на pub.dev.

Затем выполните следующую команду в корневом каталоге вашего проекта, чтобы установить зависимость:

flutter pub get

Дважды проверьте, что пакет установлен корректно:

flutter pub deps | grep pushwoosh_flutter

# Пример вывода:
# ❯ flutter pub deps | grep pushwoosh_flutter
# └── pushwoosh_flutter 2.3.11

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

В корневом компоненте вашего файла main.dart:

• Импортируйте пакет pushwoosh_flutter.
• Инициализируйте Wavesend SDK.
• Вызовите registerForPushNotifications() в вашей логике инициализации, чтобы зарегистрироваться для получения push-уведомлений.

main.dart

import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

void main() async {
  runApp(const MyApp());
  Pushwoosh.initialize({
    "app_id": "__YOUR_APP_ID__",
    "sender_id": "__YOUR_FCM_SENDER_ID__"
  });
  Pushwoosh.getInstance.registerForPushNotifications();
}

Где:

• __YOUR_APP_ID__ — это Application Code из Control Panel Wavesend.
• __YOUR_FCM_SENDER_ID__ — это номер проекта Firebase из Firebase Console.

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

3.1 Возможности

Чтобы включить Push Notifications в вашем проекте, необходимо добавить определенные возможности.

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

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

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

3.2 Info.plist

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

info.plist

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

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

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

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

Чтобы убедиться, что Notification Service Extension правильно интегрирован в ваш Flutter-проект, вам необходимо использовать следующую конфигурацию Podfile:

Podfile

target 'NotificationServiceExtension' do
  use_frameworks!
  use_modular_headers!

  pod 'PushwooshXCFramework'

  inherit! :search_paths
end

3.4 Установка зависимостей для iOS Flutter проекта

Для установки зависимостей для iOS Flutter проекта выполните следующую команду:

flutter run

или перейдите в папку ios в терминале и выполните:

pod install --repo-update

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 Добавление метаданных Wavesend

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

AndroidManifest.xml

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

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

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

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

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

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

Слушатели событий push-уведомлений

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

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

Вы должны настроить этих слушателей событий сразу после инициализации SDK при запуске приложения:

import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class PushwooshNotificationHandler {
  void setupPushListeners(Pushwoosh pushwoosh) {

    pushwoosh.onPushReceived.listen((event) {
      print("Push received: ${event.pushwooshMessage.payload}");
    });

    pushwoosh.onPushAccepted.listen((event) {
      print("Push accepted: ${event.pushwooshMessage.payload}");
    });

  }
}

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

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

import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class Registration {
  void afterUserLogin(User user) {

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

    // Установка email пользователя
    Pushwoosh().setEmail(user.getEmail());

    // Регистрация номера SMS
    // Номера SMS и WhatsApp должны быть в формате E.164 (например, "+1234567890") и быть действительными
    Pushwoosh().registerSmsNumber(user.getSmsNumber());

    // Регистрация номера WhatsApp
    Pushwoosh().registerWhatsappNumber(user.getWhatsappNumber());

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

Tags

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

import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class UpdateUser {
  void afterUserUpdateProfile(User user) {

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

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

Events

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

import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class Registration {

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

  void afterUserPurchase(Product product) {

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

Использование ProGuard

Note

Обратите внимание, что команда flutter build apk по умолчанию обфусцирует ваш код.

Таким образом, вы можете получить это исключение:

java.lang.IllegalStateException: Could not find class for name: com.pushwoosh.plugin.PushwooshNotificationServiceExtension

В этом случае есть два решения:

1. Используйте команду flutter build apk --no-shrink для компиляции кода без обфускации.
2. Или вы можете вручную включить ProGuard и добавить необходимые правила.

Чтобы включить ProGuard для вашего проекта, добавьте следующие строки в ваш файл build.gradle:

build.gradle

buildTypes {
        release {
            minifyEnabled true
            useProguard true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'

            signingConfig signingConfigs.debug
        }
    }

Затем добавьте следующие правила в android/app/proguard-rules.pro

proguard-rules.pro

#Wavesend Flutter
-keep class com.pushwoosh.plugin.PushwooshPlugin { *; }
-keep class com.pushwoosh.plugin.PushwooshNotificationServiceExtension { *; }

Troubleshooting

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