SDK Flutter

Prérequis#

• Dart >=3.4.0 <4.0.0.
• Flutter >=3.16.0 (la série 3.x).
• Dart pur : aucun pont natif, aucun pod install, aucune modification Gradle. Les dépendances transitives sont de simples paquets Dart (http, web_socket_channel, uuid).

Installation#

Ajoutez le paquet depuis pub.dev:

dependencies:
  respondo_sdk: ^0.1.2

import 'package:respondo_sdk/respondo_sdk.dart';

Initialiser#

Liez Respondo.navigatorKey à votre MaterialApp pour que le SDK puisse ouvrir la feuille de chat sans votre BuildContext, appelez Respondo.init une fois, puis 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();

  // Le répertoire de stockage des fichiers vient d'un plugin de l'app hôte ; le SDK reste pur.
  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, // requis pour que le SDK puisse ouvrir le chat
      home: Scaffold(
        body: Center(
          child: FilledButton(
            onPressed: () => Respondo.open(),
            child: const Text('Support'),
          ),
        ),
      ),
    );
  }
}

Toutes les méthodes de la façade sont idempotentes, sûres à appeler avant l’initialisation (elles mettent en tampon et rejouent) et ne lèvent jamais d’exception dans votre application.

Identifier les utilisateurs#

Par défaut, chaque visiteur est anonyme. Au premier lancement, le SDK génère un visitor_id stable et le conserve dans le stockage local, si bien qu’un utilisateur de retour retrouve sa conversation. Aucune clé d’API à intégrer — chaque conversation est protégée par un jeton de session propre à la conversation, que le backend émet et fait glisser à chaque message, de sorte qu’un visiteur anonyme n’a jamais à se réauthentifier.

Appelez identify une fois votre utilisateur connecté. Cela rattache son identité réelle, de sorte que son historique le suit d’un appareil à l’autre et après réinstallation, et que son nom et son e-mail apparaissent à côté de la conversation dans votre boîte de réception au lieu d’un visiteur anonyme.

Le userHash est une signature que votre backend calcule à partir de l’ identity_secret de l’agent — HMAC-SHA256(secret, userId) (ou l’e-mail lorsqu’il n’y a pas de userId), encodée en hexadécimal minuscule. Le secret prouve que l’identité est authentique ; il doit donc résider uniquement sur votre backend et n’est jamais livré dans l’application. Consultez la page Vérification d’identité pour la formule complète et des exemples côté serveur.

// 1. Connectez-vous auprès de votre propre backend et lisez le hash précalculé
//    (par exemple, un champ renvoyé avec la réponse de connexion).
final session = await api.login(email, password);

// 2. Transmettez le userHash finalisé au SDK — ne le calculez jamais dans l'application.
Respondo.identify(RespondoIdentity(
  userId: session.userId,
  email: session.email,
  name: session.fullName,
  userHash: session.respondoUserHash,
));

// 3. À la déconnexion : révoquez la session et démarrez un nouveau visiteur anonyme.
Respondo.reset();

Si le hash est manquant ou incorrect, rien n’est levé : le backend garde silencieusement le visiteur anonyme, le chat continue de fonctionner, et vous perdez simplement le lien inter-appareils jusqu’à ce qu’un hash valide soit fourni. La vérification ne s’exécute que lorsque l’agent a un identity_secret défini — laissez-le vide pendant le développement et userId / e-mail sont acceptés tels quels.

Observables et callbacks#

Tout est disponible sous forme de Stream broadcast, de setter de callback et de getter de valeur courante.

// Flux réactif des nombres de messages non lus (pour un badge).
Respondo.unreadCountStream.listen((n) => setBadge(n));

// Ou un setter de callback.
Respondo.onUnreadChanged = (n) => setBadge(n);

// Interceptez les liens/CTA ; renvoyez true si l'hôte a ouvert l'URL lui-même.
Respondo.onUrlRequested = (url) {
  openInAppBrowser(url);
  return true;
};

Suivi d’écran#

Signalez l’écran courant à chaque navigation pour que les accroches proactives et le ciblage par page puissent s’y référer. Passez null pour l’effacer ; à chaque changement, l’accroche proactive est réévaluée pour le nouvel écran.

Respondo.setCurrentScreen('pricing');

Étapes suivantes#

Ajoutez les Notifications push et la Vérification d’identité. La surface d’API complète, les surfaces d’engagement et le dépannage sont couverts dans le guide de démarrage du SDK Flutter sur la page du paquet sur pub.dev.