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 вбудовувати не потрібно — кожна розмова захищена посесійним токеном на розмову, який бекенд карбує й зсуває вперед на кожному повідомленні, тож анонімному відвідувачеві ніколи не доводиться повторно автентифікуватися.

Викличте identify, щойно ваш користувач залогінився. Це прив’язує його реальну особу, тож його історія супроводжує його на різних пристроях і при перевстановленнях, а його ім’я та email з’являються поруч із розмовою у вашій спільній скриньці замість анонімного відвідувача.

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

// 1. Залогіньтеся на власному бекенді й прочитайте попередньо обчислений хеш
//    (наприклад, поле, що повертається разом із відповіддю логіну).
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();

Якщо хеш відсутній або хибний, нічого не падає з винятком: бекенд мовчки залишає відвідувача анонімним, чат далі працює, і ви просто втрачаєте зв’язок між пристроями, доки не буде надано валідний хеш. Верифікація виконується лише тоді, коли в агента заданий identity_secret — залиште його порожнім під час розробки, і userId / email приймаються як є.

Обсервабли й колбеки#

Усе доступне як широкомовний 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');

Наступні кроки#

Додайте Push-сповіщення та Верифікацію особи. Повна поверхня API, поверхні залучення й розв’язання проблем описані в посібнику з початку роботи з Flutter SDK на сторінці пакета pub.dev.