Flutter SDK

Requisitos#

• Dart >=3.4.0 <4.0.0.
• Flutter >=3.16.0 (la línea 3.x).
• Dart puro: sin puentes nativos, sin pod install, sin ediciones de Gradle. Las dependencias transitivas son paquetes de Dart simples (http, web_socket_channel, uuid).

Instalación#

Añade el paquete desde pub.dev:

dependencies:
  respondo_sdk: ^0.1.2

import 'package:respondo_sdk/respondo_sdk.dart';

Inicializar#

Vincula Respondo.navigatorKey a tu MaterialApp para que el SDK pueda abrir la hoja del chat sin tu BuildContext, llama a Respondo.init una vez y luego 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();

  // El directorio de almacenamiento de archivos proviene de un plugin de la app anfitriona; el SDK sigue siendo 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, // obligatorio para que el SDK pueda abrir el chat
      home: Scaffold(
        body: Center(
          child: FilledButton(
            onPressed: () => Respondo.open(),
            child: const Text('Support'),
          ),
        ),
      ),
    );
  }
}

Todos los métodos de la fachada son idempotentes, seguros de llamar antes de la inicialización (se almacenan en búfer y se reproducen) y nunca lanzan excepciones hacia tu aplicación.

Identificar usuarios#

Por defecto, todos los visitantes son anónimos. En el primer arranque, el SDK genera un visitor_id estable y lo conserva en el almacenamiento local, de modo que un usuario que regresa vuelve a encontrar su conversación. No hay ninguna clave de API que incrustar: cada conversación está protegida por un token de sesión por conversación que el backend acuña y desplaza hacia adelante en cada mensaje, así que un visitante anónimo nunca tiene que volver a autenticarse.

Llama a identify una vez que tu usuario haya iniciado sesión. Esto adjunta su identidad real para que su historial lo siga entre dispositivos y reinstalaciones, y su nombre y email aparezcan junto a la conversación en tu bandeja de entrada en lugar de un visitante anónimo.

El userHash es una firma que tu backend calcula a partir del identity_secret del agente — HMAC-SHA256(secret, userId) (o el email cuando no hay userId), codificada como hexadecimal en minúsculas. El secreto demuestra que la identidad es genuina, por lo que debe residir únicamente en tu backend y nunca se incluye en la aplicación. Consulta la página de Verificación de identidad para ver la fórmula completa y ejemplos del lado del servidor.

// 1. Inicia sesión contra tu propio backend y lee el hash precalculado
//    (por ejemplo, un campo devuelto junto con la respuesta de login).
final session = await api.login(email, password);

// 2. Entrega el userHash finalizado al SDK: nunca lo calcules en la aplicación.
Respondo.identify(RespondoIdentity(
  userId: session.userId,
  email: session.email,
  name: session.fullName,
  userHash: session.respondoUserHash,
));

// 3. Al cerrar sesión: revoca la sesión e inicia un nuevo visitante anónimo.
Respondo.reset();

Si el hash falta o es incorrecto, no se lanza ninguna excepción: el backend mantiene al visitante como anónimo de forma silenciosa, el chat sigue funcionando y simplemente pierdes el vínculo entre dispositivos hasta que se proporcione un hash válido. La verificación solo se ejecuta cuando el agente tiene configurado un identity_secret: déjalo vacío durante el desarrollo y el userId / email se aceptan tal cual.

Observables y callbacks#

Todo está disponible como un Stream de difusión (broadcast), un setter de callback y un getter del valor actual.

// Stream reactivo de recuentos de no leídos (para un distintivo).
Respondo.unreadCountStream.listen((n) => setBadge(n));

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

// Intercepta enlaces/CTA; devuelve true si el anfitrión abrió la URL por sí mismo.
Respondo.onUrlRequested = (url) {
  openInAppBrowser(url);
  return true;
};

Seguimiento de pantalla#

Informa de la pantalla actual en cada navegación para que los teasers proactivos y la segmentación a nivel de página puedan compararse con ella. Pasa null para borrarla; en cada cambio, el teaser proactivo se reevalúa para la nueva pantalla.

Respondo.setCurrentScreen('pricing');

Próximos pasos#

Añade las Notificaciones push y la Verificación de identidad. La superficie completa de la API, las superficies de engagement y la resolución de problemas se tratan en la guía de introducción del Flutter SDK en la página del paquete en pub.dev.