Flutter SDK

Wymagania#

• Dart >=3.4.0 <4.0.0.
• Flutter >=3.16.0 (linia 3.x).
• Czysty Dart: brak natywnych mostów, brak pod install, brak edycji Gradle. Zależności przechodnie to zwykłe pakiety Dart (http, web_socket_channel, uuid).

Instalacja#

Dodaj pakiet z pub.dev:

dependencies:
  respondo_sdk: ^0.1.2

import 'package:respondo_sdk/respondo_sdk.dart';

Inicjalizacja#

Powiąż Respondo.navigatorKey ze swoim MaterialApp, aby SDK mogło otworzyć arkusz czatu bez Twojego BuildContext, wywołaj Respondo.init raz, a następnie 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();

  // Katalog pamięci plikowej pochodzi z wtyczki aplikacji hosta; SDK pozostaje czyste.
  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, // wymagane, aby SDK mogło otworzyć czat
      home: Scaffold(
        body: Center(
          child: FilledButton(
            onPressed: () => Respondo.open(),
            child: const Text('Support'),
          ),
        ),
      ),
    );
  }
}

Wszystkie metody fasady są idempotentne, bezpieczne do wywołania przed inicjalizacją (buforują i odtwarzają) i nigdy nie zgłaszają wyjątków do Twojej aplikacji.

Identyfikacja użytkowników#

Domyślnie każdy odwiedzający jest anonimowy. Przy pierwszym uruchomieniu SDK generuje stabilny visitor_id i przechowuje go w pamięci lokalnej, dzięki czemu powracający użytkownik odnajduje swoją rozmowę. Nie ma klucza API do osadzenia — każda rozmowa jest chroniona tokenem sesji przypisanym do rozmowy, który backend generuje i przesuwa do przodu przy każdej wiadomości, więc anonimowy odwiedzający nigdy nie musi się ponownie uwierzytelniać.

Wywołaj identify, gdy użytkownik się zaloguje. Powiązuje to jego prawdziwą tożsamość, dzięki czemu historia podąża za nim między urządzeniami i po ponownej instalacji, a jego imię i e-mail pojawiają się obok rozmowy w Twojej skrzynce zamiast anonimowego odwiedzającego.

userHash to podpis, który Twój backend oblicza z identity_secret agenta — HMAC-SHA256(secret, userId) (lub e-mail, gdy nie ma userId), zakodowany jako małe litery hex. Sekret dowodzi autentyczności tożsamości, więc musi żyć wyłącznie na Twoim backendzie i nigdy nie jest dostarczany w aplikacji. Pełny wzór i przykłady po stronie serwera znajdziesz na stronie Weryfikacja tożsamości.

// 1. Zaloguj się na własnym backendzie i odczytaj wstępnie obliczony hash
//    (na przykład pole zwracane wraz z odpowiedzią logowania).
final session = await api.login(email, password);

// 2. Przekaż gotowy userHash do SDK — nigdy nie obliczaj go w aplikacji.
Respondo.identify(RespondoIdentity(
  userId: session.userId,
  email: session.email,
  name: session.fullName,
  userHash: session.respondoUserHash,
));

// 3. Przy wylogowaniu: unieważnij sesję i rozpocznij świeżego anonimowego odwiedzającego.
Respondo.reset();

Jeśli hash jest brakujący lub błędny, nic nie zgłasza wyjątku: backend po cichu utrzymuje odwiedzającego jako anonimowego, czat nadal działa, a Ty po prostu tracisz powiązanie między urządzeniami do momentu dostarczenia poprawnego hasha. Weryfikacja działa tylko, gdy agent ma ustawiony identity_secret — pozostaw go pustym podczas developmentu, a userId / e-mail są akceptowane bez zmian.

Obserwowalne i callbacki#

Wszystko jest dostępne jako rozgłoszeniowy Stream, setter callbacku oraz getter bieżącej wartości.

// Reaktywny strumień liczby nieprzeczytanych (dla plakietki).
Respondo.unreadCountStream.listen((n) => setBadge(n));

// Albo setter callbacku.
Respondo.onUnreadChanged = (n) => setBadge(n);

// Przechwytuj linki/CTA; zwróć true, jeśli host sam otworzył URL.
Respondo.onUrlRequested = (url) {
  openInAppBrowser(url);
  return true;
};

Śledzenie ekranu#

Zgłaszaj bieżący ekran przy każdej nawigacji, aby proaktywne zajawki i targetowanie na poziomie strony mogły się do niego dopasować. Przekaż null, aby go wyczyścić; przy każdej zmianie proaktywna zajawka jest ponownie oceniana dla nowego ekranu.

Respondo.setCurrentScreen('pricing');

Następne kroki#

Dodaj powiadomienia push i weryfikację tożsamości. Pełna powierzchnia API, powierzchnie zaangażowania oraz rozwiązywanie problemów są opisane w przewodniku wprowadzającym Flutter SDK na stronie pakietu pub.dev.