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.3.1

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.

El mismo nombre se compara con las reglas de pantalla de las encuestas emergentes, así que usa identificadores estables como «Checkout» en lugar de títulos traducidos. Las reglas de dirección de página solo se aplican en sitios web.

Respondo.setCurrentScreen('pricing');

Abrir una encuesta desde el código#

Abre al instante una encuesta emergente activa, esté donde esté el usuario, sin tener en cuenta Show on, las reglas de pantalla, el tiempo en pantalla, el evento disparador ni la audiencia. Copia el id en el editor de la encuesta (Additional ways to share). Una encuesta que el usuario ya respondió no se vuelve a mostrar.

Respondo.startSurvey('<survey-id>');

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.