FAQ y solución de problemas del SDK

Preguntas habituales de integración

• ¿Puede el widget web ser anónimo? Sí. Las integraciones web pueden comenzar de forma anónima y añadir una identidad firmada de corta duración después del login del host. Las integraciones nativas necesitan un token de identidad de cliente firmado antes de las operaciones de red.
• ¿Mobile renderiza el widget web en una WebView? No. iOS, Android, Flutter, React Native, NativeScript y Capacitor presentan el widget y el transporte nativos compartidos. Capacitor puede seguir alojando el resto de la UI en su WebView normal.
• ¿Qué versiones mínimas se admiten? iOS 15.1, Android API 26, Flutter 3.22.3 o posterior con Dart 3.4 a 3.x, React Native 0.76 a 0.87 con New Architecture, NativeScript 8.9 a 9.x y Capacitor 6 a 8.
• ¿Puedo mantener varias conversaciones activas en un cliente? No. Un accountScope controla una sesión nativa activa y una outbox duradera. Termina o reinicia la sesión antes de iniciar otra y llama a logout antes de cambiar la identidad.
• ¿El SDK público transmite tokens de IA? No. La API pública devuelve snapshots tipados y resultados de wait-for-assistant. No construyas una UI token a token a partir de eventos de polling.
• ¿Push y voz vienen con el paquete base? No. Son capacidades nativas opcionales con su propia configuración de proveedor y permisos.

Relaciona los errores con la siguiente acción segura

Lee el código de error tipado y conserva la identidad de la solicitud. Los estados network, reconnecting y rate-limited se pueden reintentar según las reglas del SDK. session-expired requiere un token nuevo para la misma cuenta. field-invalid, payload-too-large y message-rejected requieren corregir el host o el cliente. idempotency-conflict significa que el host debe investigar la clave original en vez de enviar un mensaje nuevo.

import { DobroDeskSdkError } from "@dobrodesk/mobile-protocol";

try {
  await client.sendMessage(text, idempotencyKey);
} catch (error) {
  // These host functions render controls; they do not retry inside catch.
  if (!(error instanceof DobroDeskSdkError)) {
    showRecoverableSdkError(error);
    return;
  }
  switch (error.details.code) {
    case "network":
    case "rate-limited":
      showRetryControl();
      break;
    case "session-expired":
      showRefreshAndRetryControlForTheSameAccount();
      break;
    case "field-invalid":
    case "payload-too-large":
    case "message-rejected":
      showCorrection(error.details);
      break;
    case "idempotency-conflict":
      investigateOriginalRequest(error.details);
      break;
    default:
      showRecoverableSdkError(error);
  }
}

Comprueba el host antes de abrir una solicitud de soporte

1. Confirma que apiOrigin es un origin HTTPS sin path, query ni credenciales y que integrationId es la integración DobroDesk correcta.
2. Confirma que el backend del host emitió el token firmado para el cliente actual y que accountScope es estable y exclusivo de ese cliente.
3. Confirma que el presenter nativo se llama desde una pantalla en primer plano y que el host no montó un segundo cliente para la misma cuenta.
4. Confirma que el reintento reutiliza la idempotency key original y que no se llamó a logout o reset mientras la operación solo estaba sin conexión.