Flutter SDK

Anforderungen#

• Dart >=3.4.0 <4.0.0.
• Flutter >=3.16.0 (die 3.x-Linie).
• Reines Dart: keine nativen Bridges, kein pod install, keine Gradle-Änderungen. Transitive Abhängigkeiten sind reine Dart-Pakete (http, web_socket_channel, uuid).

Installation#

Fügen Sie das Paket von pub.dev hinzu:

dependencies:
  respondo_sdk: ^0.1.2

import 'package:respondo_sdk/respondo_sdk.dart';

Initialisieren#

Binden Sie Respondo.navigatorKey an Ihre MaterialApp, damit das SDK das Chat-Sheet ohne Ihren BuildContext öffnen kann, rufen Sie Respondo.init einmal auf und dann 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();

  // Das Verzeichnis für die Dateiablage kommt von einem Plugin der Host-App; das SDK bleibt rein.
  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, // erforderlich, damit das SDK den Chat öffnen kann
      home: Scaffold(
        body: Center(
          child: FilledButton(
            onPressed: () => Respondo.open(),
            child: const Text('Support'),
          ),
        ),
      ),
    );
  }
}

Alle Fassaden-Methoden sind idempotent, sicher vor der Init aufrufbar (sie puffern und spielen erneut ab) und werfen niemals in Ihre App hinein.

Nutzer identifizieren#

Standardmäßig ist jeder Besucher anonym. Beim ersten Start generiert das SDK eine stabile visitor_id und bewahrt sie im lokalen Speicher auf, sodass ein wiederkehrender Nutzer seine Konversation erneut findet. Es gibt keinen API-Schlüssel einzubetten — jede Konversation ist durch ein Session-Token pro Konversation geschützt, das das Backend prägt und bei jeder Nachricht weiterschiebt, sodass sich ein anonymer Besucher nie erneut authentifizieren muss.

Rufen Sie identify auf, sobald Ihr Nutzer angemeldet ist. Dies hängt seine reale Identität an, sodass sein Verlauf ihm geräte- und neuinstallationsübergreifend folgt und sein Name und seine E-Mail neben der Konversation in Ihrem Posteingang erscheinen statt eines anonymen Besuchers.

Der userHash ist eine Signatur, die Ihr Backend aus dem identity_secret des Agenten berechnet — HMAC-SHA256(secret, userId) (oder die E-Mail, wenn es keine userId gibt), kodiert als Hex in Kleinbuchstaben. Das Secret beweist, dass die Identität echt ist, daher muss es ausschließlich auf Ihrem Backend liegen und wird niemals in der App ausgeliefert. Auf der Seite Identitätsverifizierung finden Sie die vollständige Formel und serverseitige Beispiele.

// 1. Melden Sie sich gegen Ihr eigenes Backend an und lesen Sie den vorberechneten Hash
//    (zum Beispiel ein Feld, das zusammen mit der Login-Antwort zurückkommt).
final session = await api.login(email, password);

// 2. Übergeben Sie den fertigen userHash an das SDK — berechnen Sie ihn niemals in der App.
Respondo.identify(RespondoIdentity(
  userId: session.userId,
  email: session.email,
  name: session.fullName,
  userHash: session.respondoUserHash,
));

// 3. Beim Logout: Session widerrufen und neuen anonymen Besucher starten.
Respondo.reset();

Wenn der Hash fehlt oder falsch ist, wird nichts geworfen: Das Backend hält den Besucher stillschweigend anonym, der Chat funktioniert weiter, und Sie verlieren lediglich die geräteübergreifende Verknüpfung, bis ein gültiger Hash geliefert wird. Die Verifizierung läuft nur, wenn für den Agenten ein identity_secret gesetzt ist — lassen Sie es während der Entwicklung leer, und userId / E-Mail werden unverändert akzeptiert.

Observables & Callbacks#

Alles ist als Broadcast- Stream, als Callback-Setter und als Getter für den aktuellen Wert verfügbar.

// Reaktiver Stream ungelesener Zähler (für ein Badge).
Respondo.unreadCountStream.listen((n) => setBadge(n));

// Oder ein Callback-Setter.
Respondo.onUnreadChanged = (n) => setBadge(n);

// Links/CTAs abfangen; true zurückgeben, wenn der Host die URL selbst geöffnet hat.
Respondo.onUrlRequested = (url) {
  openInAppBrowser(url);
  return true;
};

Bildschirm-Tracking#

Melden Sie den aktuellen Bildschirm bei jeder Navigation, damit proaktive Teaser und Targeting auf Seitenebene dagegen abgleichen können. Übergeben Sie null, um ihn zu löschen; bei jeder Änderung wird der proaktive Teaser für den neuen Bildschirm neu ausgewertet.

Respondo.setCurrentScreen('pricing');

Nächste Schritte#

Fügen Sie Push-Benachrichtigungen und die Identitätsverifizierung hinzu. Die vollständige API-Oberfläche, die Engagement-Oberflächen und die Fehlerbehebung werden im Einstiegsleitfaden des Flutter SDK auf der pub.dev-Paketseite behandelt.