Carrot quest для Flutter

SDK CarrotQuest для Flutter позволяет разработчикам интегрировать сервисы CarrotQuest в свои приложения Flutter. Данная документация содержит подробное руководство по использованию методов SDK.

Содержание

• Установка
• Инициализация
• Авторизация пользователей
• Свойства пользователей и события
• Чат с оператором
• Уведомления
• Дополнительная информация об iOS
• Demo-приложение (example)

Установка

Команда для установки пакета через Flutter:

 $ flutter pub add carrotquest_sdk

Это добавит в pubspec.yaml вашего проекта строку следующего содержания (и запустит flutter pub get):

dependencies:
  carrotquest_sdk: <latest-version>

Импортирование

В Dart коде, добавьте следующую строку:

import 'package:carrotquest_sdk/carrotquest_sdk.dart';

Дополнительная настройка для Android

В Android-части вашего проекта нужно включить поддержку multiDex. Для этого в файл build.gradle добавьте строку:

android {
    ...
    defaultConfig {
        ...
        multiDexEnabled true
    }
}

Если вы используете proguard, то, возможно, для корректной работы в файл proguard-rules.pro нужно добавить следующие строчки:

-keep class **.R$* { *; }
-keep class org.xmlpull.v1.** { *; }
-keep interface org.xmlpull.v1.** { *; }

Инициализация

Для работы с Carrot quest для Flutter вам понадобится API Key и User Auth Key. Вы можете найти эти ключи на вкладке Настройки > Разработчикам:

Для инициализации Carrot quest вам нужно выполнить следующий код, например, сразу после запуска приложения:

Carrot.setup(apiKey, appGroup: _appGroup);  

На Android у Вас может возникнуть ошибка при попытке инициализации SDK (например когда Flutter приложение перезапустилось после долгого нахождения в фоне в то время как Android часть нет). Для избежания таких случаев, убедитесь что проверили статус инициализации SDK:

final isInit = await Carrot.isInit();
if (isInit) return;

Авторизация пользователей

Если в вашем приложении присутствует авторизация пользователей, вы можете передать id пользователя в Carrot. Существует два способа авторизации.

Напрямую передать userAuthKey

String? carrotId = await Carrot.auth(userId, userAuthKey: _userAuthKey)  

Передать hash генерируемый у вас на бэке

String? carrotId = await Carrot.auth(id, userHash: _hash)

Методы auth возвращают CarrotID, который является уникальным идентификатором пользователя в сервисе.

Вызывайте auth только после завершения инициализации SDK — например, дождавшись результата Carrot.setup(...):

final isInit = await Carrot.setup(apiKey, appGroup: appGroup);
if (isInit) {
  String? carrotId = await Carrot.auth(userId, userAuthKey: userAuthKey);
}

Так SDK не будет создавать лишних анонимных пользователей (рекомендация нативного SDK начиная с версии 3.0.0).

Чтобы сменить пользователя, нужно вызвать метод логаута:

Carrot.logOut();  

Свойства пользователей и события

Вы можете установить необходимые свойства пользователя с помощью

 Carrot.setUserProperty(userProperty);  

Для описания свойств пользователя используйте класс UserProperty

 UserProperty(String key, String value);  

Внимание!
Поле key не может начинаться с символа $.

Для установки системных свойств реализовано 2 класса CarrotUserProperty и EcommerceUserProperty.

Для отслеживания событий используйте метод trackEvent(). Вы также можете указать дополнительные параметры для события

 Carrot.trackEvent(String event, {Map<String, String>? params});  

В SDK есть возможность трекинга навигации внутри приложения для того, чтобы при необходимости запускать различные триггерные сообщения на определенных экранах. Для этого используйте метод

Carrot.trackScreen(screenName);

Для отслеживания UTM-меток из ссылок используйте метод trackUtm(). Он предназначен прежде всего для случая, когда приложение открывается по диплинку (URL Scheme / Universal Link / App Link). Передайте в метод ссылку, по которой было открыто приложение, — SDK извлечёт из неё UTM-параметры (utm_source, utm_medium, utm_campaign, utm_term, utm_content) и сохранит их для текущего пользователя.

Carrot.trackUtm(url);

Метод можно безопасно вызывать ещё до завершения Carrot.setup() — SDK обработает метки, как только будет инициализирован.

Получать диплинки во Flutter удобно, например, через пакет app_links:

final appLinks = AppLinks();

// Ссылка, по которой приложение было запущено (холодный старт)
final initialUri = await appLinks.getInitialLink();
if (initialUri != null) {
  Carrot.trackUtm(initialUri.toString());
}

// Ссылки, приходящие, пока приложение уже запущено
appLinks.uriLinkStream.listen((uri) {
  Carrot.trackUtm(uri.toString());
});

Готовый пример смотрите в example/lib/main.dart (там же — настройка URL-схемы в AndroidManifest.xml и Info.plist).

Вы можете получить количество диалогов, содержащих непрочитанные сообщения

 Carrot.getUnreadConversationsCount();  

Также можно подписаться на изменения количества таких диалогов

 Carrot.getUnreadConversationsCountStream();  

Чат с оператором

Вы можете дать пользователю мобильного приложения возможность перейти в чат с оператором из любого места. Для этого используйте

 Carrot.openChat();  

Уведомления

Для работы с push-уведомлениями SDK использует сервис Firebase Cloud Messaging. В связи с этим необходимо получить ключ и отправить его в Carrot. Вы можете найти поле для ввода ключа на вкладке Настройки > Разработчикам. Процесс настройки сервиса Firebase Cloud Messaging описан здесь

Для работы push-уведомлений вам необходимо выполнить следующие шаги:

1. Если вы еще не используете в своем проекте FCM, то добавьте в свой проект зависимости firebase_core и firebase_messaging:

   dependencies:
     flutter:
       sdk: flutter
     
     # Firebase
     firebase_core: ^2.15.0
     firebase_messaging: ^14.6.5

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

   flutterfire configure

   Более подробно о процессе установки FCM в свой Flutter-проект можно узнать в официальной документации

2. В файле main.dart перед объявлением метода main() добавить (или модифицировать, если вы уже используете FCM у себя в проекте) хэндлер для пушей, которые будут приходить в фоне, внутри которого нужно прокинуть пуши в Carrot SDK, чтобы они корректно отобразились на устройстве:

   @pragma('vm:entry-point')
   Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
       await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);
       
       bool isCarrotPush = Carrot.isCarrotQuestPush(message.data);
       if (isCarrotPush) {
           Carrot.sendFirebasePushNotification(message.data);
       }
   }

   Метод Carrot.isCarrotQuestPush(data) проверяет, отправлено ли уведомление сервисом Carrot quest. Используйте его, чтобы отделять пуши Carrot quest от остальных уведомлений вашего приложения: чужие пуши передавать в Carrot.sendFirebasePushNotification(data) не нужно.

3. После инициализации Carrot SDK нужно отправить в сервис token от Firebase, используя метод Carrot.sendFcmToken(token). Но перед тем как отправлять токен, убедитесь, что пользователь дал свое разрешение на показ уведомлений. Без этого разрешения токен не запишется в базу на сервере. Также нужно задать для Firebase ранее написанный хэндлер для уведомлений, которые будут приходить при закрытом приложении, и написать листенер для уведомлений, которые будут приходить в открытое приложение. Например, так:

   Future<void> _initCarrotSdk() {
       return Carrot.setup(_apiKey).then((isInit) async {
           if (!isInit) {
               return;
           }
   
           // NotificationService — НЕ часть SDK, а ваш собственный класс.
           // Здесь подойдёт любой способ проверить разрешение на показ
           // уведомлений: permission_handler, firebase_messaging
           // (getNotificationSettings) и т.п. Готовый пример такого класса —
           // example/lib/notification_service.dart.
           if (await NotificationService.checkPermissions()) {
               _initFcm();
           }
   
           Carrot.getUnreadConversationsCountStream().listen((count) {
               unreadConversationsCount = count;
               setState(() {});
           });
       });
   }
   
   void _initFcm() async {
       await Firebase.initializeApp(
           options: DefaultFirebaseOptions.currentPlatform);
       FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);
   
       String? token = await FirebaseMessaging.instance.getToken();
   
       if (token != null && token.isNotEmpty) {
           await Carrot.sendFcmToken(token);
   
           FirebaseMessaging.onMessage.listen((RemoteMessage message) async {
               bool isCarrotPush = Carrot.isCarrotQuestPush(message.data);
               if (isCarrotPush) {
               Carrot.sendFirebasePushNotification(message.data);
               }
           });
       }
   }

4. Чтобы получать уведомления на устройства Apple, нужно открыть iOS часть своего проекта и написать код запроса на разрешения показа уведомлений. Для этого откройте AppDelegate и в функцию application допишите следующий код:

   override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
   	GeneratedPluginRegistrant.register(withRegistry: self)
   
   	if #available(iOS 10.0, *) {
   		// For iOS 10 display notification (sent via APNS)
   		UNUserNotificationCenter.current().delegate = self
   
   		let authOptions: UNAuthorizationOptions = [.alert, .badge, .sound]
   		UNUserNotificationCenter.current().requestAuthorization(
   			options: authOptions,
   			completionHandler: { _, _ in }
   		)
   	} else {
   		let settings: UIUserNotificationSettings = UIUserNotificationSettings(types: [.alert, .badge, .sound], categories: nil)
   		application.registerUserNotificationSettings(settings)
   	}
   
   	application.registerForRemoteNotifications()
   	return super.application(application, didFinishLaunchingWithOptions: launchOptions)
   }

5. Далее, вам необходимо вставить следующий код целиком.

   import CarrotSDK
   
   extension AppDelegate {
   
       private func getAppGroup() -> String {
           return <group_id>
       }
       
       override func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
           let notificationService = CarrotNotificationService.shared
           if notificationService.canHandle(notification) {
               notificationService.show(notification, appGroudDomain: self.getAppGroup(), completionHandler: completionHandler)
           } else {
               // Логика для пользовательских уведомлений
           }
       }
       
       override func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
           let notificationService = CarrotNotificationService.shared
           if notificationService.canHandle(response) {
               notificationService.clickNotification(notificationResponse: response, appGroudDomain: self.getAppGroup())
           } else {
               // Логика для пользовательских уведомлений
           }
       }
   }

6. Обратите внимание на строчку с group_id. По идее, этот пункт является не обязательным, и group_id можно не передавать вовсе. Дело в том, что мы используем 2 канала доставки сообщений, поэтому в некоторых случаях уведомления могут дублироваться. Например: при выходе из приложения, или при очень быстром удалении уведомления, возможно получение повторного уведомления. Если вы не замечаете дублирование сообщений, можете перейти сразу к шагу 12. Для предотвращения такого поведения нужно создать Notification Service Extension. В Xcode, в списке файлов выберите свой проект, а затем File/New/Target/Notification Service Extension. Также важно установить версию iOS для Notification Service Extension такую же, как у самого приложения.

7. После чего необходимо зарегистрировать AppGroup в Apple Developer Portal. Identifier App Group должен быть уникальным, и начинаться на "group." иначе Xcode его не примет.

8. Теперь необходимо добавить Identifier в Xcode:

1. В списке файлов выберите свой проект.
2. В списке targets выберите пункт с именем вашего проекта.
3. Во вкладке "Signing & Capabilities" нажмите на "+ Capability".
4. В выпадающем списке найдите и выберите App Group.
5. На вкладке появится пустой список для идентификаторов App Group. Добавьте туда Identifier, который зарегистрировали в Apple Developer Portal ранее.
6. Вернитесь к списку Targets. Аналогичным образом добавьте App Group к вашему Notification Service Extension.

9. Внесите изменения в метод, инициализирующий библиотеку:

   Carrot.setup(apiKey, appGroup: <group_id>);

10. Теперь нужно добавить логику в ваш Notification Service Extension. В списке файлов, должна была появиться новая папка с именем вашего Notification Service Extension. Добавьте код в файл NotificationService.swift:

    import UserNotifications
    import CarrotSDK
    
    class NotificationService: CarrotNotificationServiceExtension {
        override func setup() {
            self.domainIdentifier = <group_id>
        }
        override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
            <ваша логика>
            super.didReceive(request, withContentHandler: contentHandler) 
        }
    }

11. Обновите ваш pod файл, добавьте:

    target 'NotificationService' do
     	inherit! :search_paths
    end

12. Для Android устройств можно поменять иконку у уведомлений. Для этого положите в Android часть своего проекта нужную вам иконку с названием ic_cqsdk_notification.xml.

После этого основная настройка push-уведомлений закончена.

Отписка от уведомлений

Если пользователь не хочет получать уведомления, его можно отписать. Для отписки от push-уведомлений используйте:

Carrot.pushNotificationsUnsubscribe();

Для отписки от всех push-рассылок (кампаний):

Carrot.pushCampaignsUnsubscribe();

Оба метода отписывают текущего пользователя, поэтому вызывать их нужно после инициализации SDK (и авторизации, если она используется).

Дополнительная информация об iOS

Чтобы светлая тема правильно выглядела, вам нужно разрешить контроллерам управлять цветом статус-бара. Для этого откройте нативную iOS часть своего проекта и в файле info.plist в строчке под названием UIViewControllerBasedStatusBarAppearance поменяйте false на true. Если вы открываете через Xcode, тогда эта строка называется "View controller-based status Bar appearance" и имеет значение NO. Вам необходимо поставить значение на YES.

Demo-приложение (example)

В каталоге example/ лежит готовое приложение, которое показывает все возможности SDK на практике: инициализацию, авторизацию, свойства и события, чат, push-уведомления и трекинг UTM-меток. Чтобы понять, как пользоваться SDK, чаще всего достаточно просто посмотреть код — главный файл example/lib/main.dart.

Как запустить приложение и проверить трекинг UTM-меток — описано в example/README.md.