Flutter SDK

Requisiti#

• Dart >=3.4.0 <4.0.0.
• Flutter >=3.16.0 (la linea 3.x).
• Dart puro: nessun bridge nativo, nessun pod install, nessuna modifica a Gradle. Le dipendenze transitive sono normali package Dart (http, web_socket_channel, uuid).

Installazione#

Aggiungi il package da pub.dev:

dependencies:
  respondo_sdk: ^0.1.2

import 'package:respondo_sdk/respondo_sdk.dart';

Inizializzazione#

Collega Respondo.navigatorKey al tuo MaterialApp così l’SDK può aprire lo sheet della chat senza il tuo BuildContext, chiama Respondo.init una volta, poi 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();

  // La directory di storage dei file viene da un plugin dell'app host; l'SDK resta puro.
  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, // richiesto affinché l'SDK possa aprire la chat
      home: Scaffold(
        body: Center(
          child: FilledButton(
            onPressed: () => Respondo.open(),
            child: const Text('Support'),
          ),
        ),
      ),
    );
  }
}

Tutti i metodi della facade sono idempotenti, sicuri da chiamare prima di init (accodano e riproducono) e non sollevano mai eccezioni nella tua app.

Identificare gli utenti#

Per impostazione predefinita ogni visitatore è anonimo. Al primo avvio l’SDK genera un visitor_id stabile e lo conserva nello storage locale, così un utente che torna ritrova la sua conversazione. Non c’è alcuna chiave API da incorporare — ogni conversazione è protetta da un token di sessione per conversazione che il backend emette e fa avanzare a ogni messaggio, così un visitatore anonimo non deve mai autenticarsi di nuovo.

Chiama identify non appena l’utente è autenticato. Questo collega la sua identità reale, così la sua cronologia lo segue tra dispositivi e reinstallazioni, e il suo nome ed email compaiono accanto alla conversazione nella tua inbox invece di un visitatore anonimo.

Lo userHash è una firma che il tuo backend calcola a partire dall’ identity_secret dell’agente — HMAC-SHA256(secret, userId) (o l’email quando non c’è userId), codificata in esadecimale minuscolo. Il secret dimostra che l’identità è autentica, quindi deve risiedere solo sul tuo backend e non va mai incluso nell’app. Consulta la pagina Verifica dell’identità per la formula completa e gli esempi lato server.

// 1. Autentica sul tuo backend e leggi l'hash precalcolato
//    (per esempio, un campo restituito insieme alla risposta di login).
final session = await api.login(email, password);

// 2. Passa lo userHash già pronto all'SDK — non calcolarlo mai nell'app.
Respondo.identify(RespondoIdentity(
  userId: session.userId,
  email: session.email,
  name: session.fullName,
  userHash: session.respondoUserHash,
));

// 3. Al logout: revoca la sessione e avvia un nuovo visitatore anonimo.
Respondo.reset();

Se l’hash manca o è errato, non viene sollevata alcuna eccezione: il backend mantiene silenziosamente il visitatore anonimo, la chat continua a funzionare e si perde semplicemente il collegamento tra dispositivi finché non viene fornito un hash valido. La verifica viene eseguita solo quando l’agente ha un identity_secret impostato — lascialo vuoto durante lo sviluppo e userId / email vengono accettati così come sono.

Observable & callback#

Tutto è disponibile come Stream broadcast, come setter di callback e come getter del valore corrente.

// Stream reattivo dei conteggi dei non letti (per un badge).
Respondo.unreadCountStream.listen((n) => setBadge(n));

// Oppure un setter di callback.
Respondo.onUnreadChanged = (n) => setBadge(n);

// Intercetta link/CTA; restituisci true se l'host ha aperto l'URL da solo.
Respondo.onUrlRequested = (url) {
  openInAppBrowser(url);
  return true;
};

Tracciamento delle schermate#

Segnala la schermata corrente a ogni navigazione, così i teaser proattivi e il targeting a livello di pagina possono farvi riferimento. Passa null per cancellarla; a ogni cambio il teaser proattivo viene rivalutato per la nuova schermata.

Respondo.setCurrentScreen('pricing');

Prossimi passi#

Aggiungi le Notifiche push e la Verifica dell’identità. L’intera superficie delle API, le superfici di engagement e la risoluzione dei problemi sono trattate nella guida introduttiva del Flutter SDK sulla pagina del package su pub.dev.