FAQ e resolução de problemas do SDK

Perguntas comuns de integração

• O widget web pode ser anónimo? Sim. Pode começar anonimamente e associar identidade assinada após o login. SDKs nativos exigem token assinado antes da rede.
• O mobile renderiza o widget numa WebView? Não. iOS, Android, Flutter, React Native, NativeScript e Capacitor usam widget e transporte nativos. Capacitor pode manter o restante UI na WebView.
• Quais são as versões mínimas? iOS 15.1, Android API 26, Flutter 3.22.3 com Dart 3.4 a 3.x, React Native 0.76 a 0.87 com New Architecture, NativeScript 8.9 a 9.x e Capacitor 6 a 8.
• Posso ter várias conversas num cliente? Não. Um accountScope tem uma sessão ativa e outbox durável. Termine ou reinicie antes de outra e use logout ao trocar identidade.
• O SDK público transmite tokens de IA? Não. Devolve snapshots tipados e resultados wait-for-assistant. Não crie UI token a token por polling.
• Push e voice vêm no pacote base? Não. São capacidades nativas opcionais com permissões e fornecedores próprios.

Associar erros à próxima ação segura

Leia o código tipado e preserve a identidade do pedido. network, reconnecting e rate-limited podem ser repetidos conforme as regras. session-expired requer token novo da mesma conta. field-invalid, payload-too-large e message-rejected exigem correção. idempotency-conflict exige investigar a chave original.

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);
  }
}

Verificar o host antes de pedir suporte

1. Confirme apiOrigin HTTPS sem path, query ou credenciais e integrationId correto.
2. Confirme que o backend emitiu o token assinado para o cliente atual e accountScope é estável e exclusivo.
3. Confirme que o presenter é chamado em primeiro plano e que não existe outro cliente para a mesma conta.
4. Confirme que a repetição usa a idempotency key original e que logout/reset não foi chamado durante uma operação offline.