Solução de problemas
O chat não abre ou fica em branco
configurenão foi chamado antes de abrir o chat. No iOS, opresentpara o app com um aviso nos builds de depuração e não faz nada nos de produção; nas duas plataformas, os outros métodos falham comNOT_CONFIGURED.- Token do canal errado ou regenerado no painel. Confira o Token do widget em Editar canal › Instalação. Regenerar o token tira do ar o chat dos apps publicados com o token antigo.
- Sem conexão: a tela do chat mostra um aviso com Tentar de novo.
Para ver o que acontece dentro do chat, ligue debug nas opções e inspecione o WebView: chrome://inspect no Android, menu Desenvolver do Safari no iOS (16.4 ou mais novo). Desligue antes de publicar.
O app fecha ao tirar foto no chat (iOS)
Falta NSCameraUsageDescription no Info.plist. Sem ela, o iOS fecha o app quando o cliente escolhe a câmera. Veja Permissões e privacidade.
A tela fica preta ou o teclado cobre o campo
- Tela preta logo ao rodar pelo Xcode: o Xcode ainda está ligando o depurador ao aparelho, o que pode levar alguns segundos na primeira execução. Espere ou abra o app pelo ícone.
- Chat deslocado para cima no primeiro toque no campo (iOS): era um defeito da versão 0.1.0. Atualize para a 0.2.0.
- Teclado cobrindo o campo de mensagem no Android: se você embutiu a
AtaliaChatViewnuma tela sua, a activity precisa deandroid:windowSoftInputMode="adjustResize". A tela doAtalia.openjá vem assim.
O app fecha ao tocar na notificação (iOS)
O UNUserNotificationCenterDelegate está com as versões async de willPresent ou didReceive. Nelas, o Swift chama o completionHandler do iOS fora da main thread, e o UIKit fecha o app. Use as versões com completionHandler, marcadas nonisolated, como em Notificações push.
O toque na notificação não abre a conversa
- Android: a activity de entrada não chama
Atalia.handleNotificationTap(this, intent)noonCreatee noonNewIntent. - iOS: o
delegatedoUNUserNotificationCenternão é definido nodidFinishLaunching, ou oconfigureé chamado depois dele. - Conversa de outro visitante: o chat só abre conversas da sessão do próprio aparelho. Se a conversa não é dela (outro aparelho, outro usuário, ou o app trocou de canal ou de endereço), o chat abre na tela inicial.
- Modo webhook: o push foi enviado sem as chaves de
notification.data. Veja Push pelo seu backend.
O push não chega
Confira em Editar canal › Instalação › App mobile e notificações push:
- Avisar por notificação está ligado, com Enviar pelo Firebase e a conta de serviço enviada (ou o webhook configurado).
- Aparelhos com o app mostra o seu aparelho? Se não, o app não está chamando
Atalia.setPushToken(ousetAPNsToken). Use Enviar teste no aparelho para testar só a entrega. - Últimas notificações mostra o que a Atalia decidiu para cada mensagem:
| O painel mostra | O que significa |
|---|---|
| Não enviada · o visitante estava no chat | Esperado: com o chat aberto, a mensagem aparece nele. |
| Não enviada · agrupada com a mensagem seguinte | Esperado: a rajada virou uma notificação só, a da última mensagem. |
| Não enviada · remetente sem aviso | Esse tipo de remetente está desligado em Quem gera notificação (as mensagens do sistema, por padrão). |
| Não enviada · o visitante não tem o app | Nenhum aparelho registrado para esse cliente. |
| Não enviada · conversa do app sem aparelho registrado | A conversa começou no app, mas o aparelho nunca se registrou: o app não chama Atalia.setPushToken (ou setAPNsToken), ou a Atalia recusou o registro. O registro do SDK mostra qual dos dois. |
| Falhou · falta a credencial | A conta de serviço do Firebase (ou o webhook) não foi configurada. |
| Falhou · o Google recusou a conta de serviço | Gere uma chave nova no Firebase e envie de novo. |
| Falhou · a conta de serviço é de outro projeto do Firebase | A conta de serviço enviada no painel é de um projeto diferente do google-services.json (ou GoogleService-Info.plist) do app. Gere a chave no MESMO projeto. |
| Falhou · chave do APNs inválida no Firebase | Envie de novo a chave .p8 no Firebase (iOS). |
| Falhou · o servidor não respondeu a tempo | Webhook: responda em até 10 segundos. |
| Aparelho removido · o app foi desinstalado | O Firebase avisou que o token não vale mais; a Atalia tira o aparelho. |
No aparelho:
- Android 13 ou mais novo: a permissão
POST_NOTIFICATIONSfoi concedida? - iOS: a chave
.p8do APNs está no Firebase, e a capability Push Notifications no app? Em builds instalados pelo Xcode, o aparelho usa o ambiente de desenvolvimento do APNs. - Com o chat aberto na tela, não chega notificação: é de propósito, a mensagem aparece no chat.
Ver o registro do SDK no aparelho
Com debug ligado nas opções do configure, o SDK escreve o que faz no log do aparelho: o registro do token na Atalia (e o motivo, se a Atalia recusar), cada notificação recebida e se ela foi mostrada, o toque nela e as idas do app para o fundo. Nunca escreve texto de mensagem, JWT ou token inteiro.
- Android: Logcat do Android Studio, filtro
tag:AtaliaChat. - iOS: console do Xcode, ou o app Console do Mac com o aparelho conectado, filtro
subsystem:ai.atalia.chat. - React Native:
debug: truenoconfigure; o registro sai nos mesmos lugares, pelo app nativo.
Linhas que respondem a maioria dos casos:
| O registro mostra | O que fazer |
|---|---|
push: nenhum token ainda | O app não chama Atalia.setPushToken (ou setAPNsToken). Veja Notificações push. |
push: a Atalia recusou o registro do aparelho (HTTP ...) | Confira o token do canal e se o push está ligado no painel. |
push: aparelho registrado na Atalia | O lado do app está certo. O motivo de cada mensagem está em Últimas notificações, no painel. |
push: o sistema não mostrou a notificação | Android: permissão POST_NOTIFICATIONS negada, notificações do app desligadas ou notificationIcon colorido. |
chat: app em segundo plano, conexão fechada de propósito | Esperado. Veja a seção abaixo. |
Desligue o debug antes de publicar.
O chat fecha ou desconecta quando o app vai para o fundo
Desconectar é de propósito. Quando o app vai para o fundo, o chat fecha a conexão e avisa a Atalia que o cliente saiu. É isso que libera o push: com a conexão aberta, a Atalia entende que o cliente está lendo o chat e não manda notificação. Ao voltar, o chat reconecta e busca o que chegou.
Fechar a tela do chat não é. No Android, se o sistema encerrou o app no fundo para liberar memória, ele recria a tela do chat ao voltar. Se o Atalia.configure estiver numa Activity em vez do Application.onCreate, o SDK ainda não existe nessa hora e o chat fecha. O Logcat mostra chat fechado: Atalia.configure ainda não foi chamado (esse aviso aparece mesmo sem debug). Mova o configure para o Application.onCreate. No iOS, chame no didFinishLaunchingWithOptions.
Para reproduzir no Android: abra o chat, mande o app para o fundo e rode adb shell am kill <pacote do app>; depois volte ao app pela lista de recentes.
O número no ícone não some (iOS)
O número vem da Atalia e o iOS só o tira quando o app manda. O SDK atualiza quando o app volta para a frente e quando o cliente lê as mensagens, se o push estiver ligado no app (setPushToken ou setAPNsToken já chamado) e appBadge não estiver desligado.
Se o seu app tem contador próprio no ícone, use AtaliaOptions(appBadge: false): assim nem o SDK nem o push da Atalia mexem no número.
O identify falha
Veja a tabela de códigos de erro. Os casos mais comuns são o segredo regenerado no painel (INVALID_SIGNATURE), o relógio do servidor que assina fora de hora (EXPIRED) e o mesmo token usado duas vezes (REPLAYED).