Flutter SDK

Требования#

• Dart >=3.4.0 <4.0.0.
• Flutter >=3.16.0 (линейка 3.x).
• Чистый Dart: никаких нативных мостов, никакого pod install, никаких правок Gradle. Транзитивные зависимости — обычные Dart-пакеты (http, web_socket_channel, uuid).

Установка#

Добавьте пакет из pub.dev:

dependencies:
  respondo_sdk: ^0.1.2

import 'package:respondo_sdk/respondo_sdk.dart';

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

Привяжите Respondo.navigatorKey к своему MaterialApp, чтобы SDK мог открыть лист чата без вашего BuildContext, вызовите Respondo.init один раз, затем Respondo.open().

import 'package:flutter/material.dart';
import 'package:path_provider/path_provider.dart';
import 'package:respondo_sdk/respondo_sdk.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Каталог файлового хранилища берётся из плагина хост-приложения; сам SDK остаётся чистым.
  final dir = await getApplicationSupportDirectory();

  await Respondo.init(
    RespondoConfig(
      agentId: '<agent-uuid>',
      channelId: '<channel-uuid>',
      storageDirectory: dir.path,
    ),
  );

  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: Respondo.navigatorKey, // обязательно, чтобы SDK мог открыть чат
      home: Scaffold(
        body: Center(
          child: FilledButton(
            onPressed: () => Respondo.open(),
            child: const Text('Support'),
          ),
        ),
      ),
    );
  }
}

Все методы фасада идемпотентны, их безопасно вызывать до init (они буферизуются и переигрываются) и никогда не бросают исключения в ваше приложение.

Идентификация пользователей#

По умолчанию каждый посетитель анонимен. При первом запуске SDK генерирует стабильный visitor_id и держит его в локальном хранилище, поэтому вернувшийся пользователь снова находит свой диалог. Никакого API-ключа встраивать не нужно — каждый диалог защищён session-токеном на диалог, который backend выпускает и сдвигает вперёд на каждом сообщении, так что анонимному посетителю никогда не приходится проходить аутентификацию заново.

Вызовите identify, как только пользователь вошёл. Это привязывает его настоящую личность, поэтому его история следует за ним между устройствами и переустановками, а имя и email показываются рядом с диалогом в вашем инбоксе вместо анонимного посетителя.

userHash — это подпись, которую ваш backend вычисляет из identity_secret агента — HMAC-SHA256(secret, userId) (или email, если userId нет), закодированная как hex в нижнем регистре. Секрет доказывает подлинность личности, поэтому он должен жить только на вашем backend и никогда не поставляться в приложении. Полную формулу и серверные примеры смотрите на странице Проверка личности.

// 1. Войдите через собственный backend и прочитайте предвычисленный хеш
//    (например, поле, которое возвращается вместе с ответом на логин).
final session = await api.login(email, password);

// 2. Передайте готовый userHash в SDK — никогда не вычисляйте его в приложении.
Respondo.identify(RespondoIdentity(
  userId: session.userId,
  email: session.email,
  name: session.fullName,
  userHash: session.respondoUserHash,
));

// 3. При выходе: отзовите сессию и начните нового анонимного посетителя.
Respondo.reset();

Если хеш отсутствует или неверен, ничего не падает: backend молча оставляет посетителя анонимным, чат продолжает работать, и вы просто теряете кросс-девайс-связь, пока не будет передан валидный хеш. Проверка запускается только тогда, когда у агента задан identity_secret — оставьте его пустым при разработке, и userId / email будут приняты как есть.

Наблюдаемые значения и коллбэки#

Всё доступно как broadcast- Stream, сеттер коллбэка и геттер текущего значения.

// Реактивный поток числа непрочитанных (для бейджа).
Respondo.unreadCountStream.listen((n) => setBadge(n));

// Или сеттер коллбэка.
Respondo.onUnreadChanged = (n) => setBadge(n);

// Перехват ссылок/CTA; верните true, если хост сам открыл URL.
Respondo.onUrlRequested = (url) {
  openInAppBrowser(url);
  return true;
};

Отслеживание экрана#

Сообщайте текущий экран при каждой навигации, чтобы проактивные тизеры и таргетинг уровня страницы могли по нему срабатывать. Передайте null, чтобы очистить его; при каждом изменении проактивный тизер пересчитывается для нового экрана.

Respondo.setCurrentScreen('pricing');

Дальнейшие шаги#

Добавьте Пуш-уведомления и Проверку личности. Полная поверхность API, поверхности вовлечения и решение проблем разобраны в гайде по началу работы с Flutter SDK на странице пакета pub.dev.