> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Solução de problemas do SDK Mobile

> Resolva problemas comuns do OneSignal Mobile SDK, incluindo falhas na entrega push, erros APNS e problemas de mensagens in-app no iOS, Android e frameworks cross-platform.

<Note>
  Se você está tendo problemas com seu site, consulte o [guia de Solução de Problemas de Web Push](./troubleshooting-web-push).
</Note>

## Passos para solução de problemas

### Revise as instruções de configuração e atualize o SDK

Frequentemente [lançamos atualizações](https://github.com/OneSignal/sdks) com correções de bugs, melhorias e suporte para as últimas mudanças do sistema operacional. Certifique-se de estar usando a versão mais recente do SDK e de ter seguido as instruções de configuração.

<Card title="Configuração do SDK Mobile" icon="wrench" href="./mobile-sdk-setup">
  Instruções de configuração projetadas para ajudar a prevenir problemas comuns e testar a integração.
</Card>

### Verifique os guias comuns de solução de problemas

<Columns cols={2}>
  <Card title="Notificações não exibidas ou atrasadas" icon="bell-slash" href="./notifications-show-successful-but-are-not-being-shown">
    Notificações push não estão aparecendo no dispositivo ou estão atrasadas.
  </Card>

  <Card title="Imagens de notificação não aparecem" icon="image" href="./notification-images-not-showing">
    Imagens não estão aparecendo na visualização expandida da notificação.
  </Card>

  <Card title="CTR de Notificação" icon="arrow-pointer" href="./notification-ctr">
    Poucos ou nenhum clique em notificações.
  </Card>

  <Card title="Notificações duplicadas" icon="copy" href="./duplicated-notifications">
    Notificações estão aparecendo várias vezes no dispositivo.
  </Card>

  <Card title="Solução de problemas de mensagens in-app" icon="message" href="./in-app-message-troubleshooting">
    Mensagens in-app não estão exibindo ou se comportando como esperado.
  </Card>
</Columns>

### Verifique problemas comuns no seu app

#### Métodos do OneSignal que bloqueiam a exibição de push

Verifique se seu app possui métodos como `optOut()`, por exemplo `OneSignal.User.pushSubscription.optOut()`, ou se você definiu `enabled: false` via nossas REST APIs. Isso define o status da assinatura push como `unsubscribed`. Consulte a [referência do Mobile SDK](./mobile-sdk-reference#optout-%2C-optin-%2C-optedin) para mais detalhes.

Se o app estiver aberto enquanto o push está sendo enviado, você pode estar impedindo a exibição do push via o método `preventDefault()`. Isso geralmente é definido no [Listener de Evento em Primeiro Plano](./mobile-sdk-reference#addforegroundlifecyclelistener-push) ou na [Extensão de Serviço de Notificação Android](./service-extensions).

#### Conflitos com Firebase Messaging ou outros SDKs

Se o seu app também inclui o Firebase Messaging SDK ou outros SDKs de notificação push, verifique se ele não está interceptando mensagens antes que o OneSignal possa processá-las.

Esse problema ocorre comumente quando:

* Notificações aparecem como **Entregues** no OneSignal, mas nunca aparecem no dispositivo.
* O app inclui tanto o OneSignal quanto o `firebase_messaging` (ou um `FirebaseMessagingService` personalizado).
* O push funciona quando o Firebase Messaging é removido, mas falha quando ambos os SDKs estão presentes.

1. Verifique seu `AndroidManifest.xml` em busca de receivers legados do Firebase, como `com.google.firebase.iid.FirebaseInstanceIdReceiver`, e remova-os/exclua-os condicionalmente se o OneSignal for responsável pela entrega push.

2. Verifique implementações de `FirebaseMessagingService` personalizadas (ou bibliotecas como `firebase_messaging` no Flutter) que sobrescrevam o `onMessageReceived`. Se outro serviço processar ou suprimir mensagens completamente, ele pode consumir o payload do FCM antes que o OneSignal possa exibir a notificação.

3. Evite chamar APIs de gerenciamento de token do Firebase, como: `FirebaseMessaging.getToken()` ou `FirebaseMessaging.deleteToken()`.

Se o OneSignal for responsável pela entrega push, ele deve ser o único SDK gerenciando o ciclo de vida do token push. Buscar ou gerenciar o token FCM diretamente pode levar a conflitos de propriedade do token e comportamento de entrega inconsistente.

Se você precisar do token push do dispositivo para outros sistemas, leia-o a partir do OneSignal (por exemplo, `User.pushSubscription.token`) e ouça as mudanças de assinatura/token usando as [APIs de observador do SDK](./mobile-sdk-reference#addobserver-push-subscription-changes).

### Teste o projeto de exemplo para seu SDK

Verifique se o problema é reproduzível usando o projeto de exemplo mantido pela nossa equipe de engenharia para cada SDK.

* [Projeto de exemplo iOS](https://github.com/OneSignal/OneSignal-iOS-SDK/tree/main/OneSignalSwiftUIExample)
* [Projeto de exemplo Android](https://github.com/OneSignal/OneSignal-Android-SDK/tree/main/examples)
* [Projeto de exemplo de variantes Cordova](https://github.com/OneSignal/OneSignal-Cordova-SDK/tree/main/examples)
* [Projeto de exemplo React Native](https://github.com/OneSignal/react-native-onesignal/tree/main/examples)
* [Projeto de exemplo Flutter](https://github.com/OneSignal/OneSignal-Flutter-SDK/tree/main/examples)
* [Projeto de exemplo Unity](https://github.com/OneSignal/OneSignal-Unity-SDK/tree/main/examples)
* [Projeto de exemplo .NET MAUI](https://github.com/OneSignal/OneSignal-DotNet-SDK/tree/main/examples)

### Verifique os logs de erro

Colete dados de log antes de diagnosticar mais:

* Siga o guia sobre [captura de um log de debug](./capturing-a-debug-log).
* Procure por erros, avisos ou avisos de descontinuação que possam explicar o comportamento.

<Card title="Capturando um log de debug" icon="bug" href="./capturing-a-debug-log">
  Como habilitar o log detalhado e capturar a saída do SDK para solução de problemas.
</Card>

### Entre em contato com o suporte

Se você ainda está tendo problemas, entre em contato com `support@onesignal.com` com:

* Seu OneSignal App ID
* O External ID e/ou Subscription ID do dispositivo afetado
* O ID da notificação ou um link para a notificação no painel (se aplicável)
* Um [log de debug do dispositivo](./capturing-a-debug-log) reproduzindo o problema

***

## Erros comuns

### APNS Delegate never fired

Erros como "APNS Delegate Never Fired" e "APNS 3000" são mensagens de timeout da Apple indicando que o dispositivo não conseguiu conectar aos servidores APNS da Apple. Isso é mais comum quando:

* Testando em ambientes de desenvolvimento APNS
* Usando múltiplas dependências de notificação push ou APIs push nativas do iOS junto com o OneSignal
* Um problema temporário de conectividade — geralmente se resolve da próxima vez que o usuário inicia uma nova sessão (app em segundo plano por 30+ segundos, depois reaberto)

**Passos para resolver:**

1. Remova quaisquer outras dependências de notificação push ou APIs push nativas do iOS e use apenas o OneSignal. Quando o erro for resolvido, você pode adicionar o outro código de volta. Entre em contato com `support@onesignal.com` para melhores práticas de coexistência.
2. Verifique o [log de debug do dispositivo](./capturing-a-debug-log) para mais detalhes.
3. Se o erro persistir, [entre em contato com o suporte](#passos-para-solução-de-problemas).

Se você está usando Capacitor, adicione esta configuração para permitir que o OneSignal manipule as notificações push.

<CodeGroup>
  ```json json theme={null}
  {
    "ios": {
      "handleApplicationNotifications": false
    }
  }
  ```

  ```typescript capacitor.config.ts theme={null}
  const config: CapacitorConfig = {
    // ... additional configuration

    ios: {
      // ... additional configuration
      handleApplicationNotifications: false
    }
  };
  ```
</CodeGroup>

### Aplicativo não abre quando fechado forçadamente e ao clicar em uma notificação

Certifique-se de que você não está testando em uma build `Debug`. Por exemplo, para aplicativos Flutter, você pode:

* Usar uma build de release via Flutter, por exemplo `flutter run --release` (requer um dispositivo físico)
* Atualizar o esquema do Xcode para `Release` em vez de `Debug`

***

## Páginas relacionadas

<Columns cols={2}>
  <Card title="Configuração do SDK Mobile" icon="wrench" href="./mobile-sdk-setup">
    Instruções de configuração para todos os SDKs móveis e cross-platform suportados.
  </Card>

  <Card title="Capturando um log de debug" icon="bug" href="./capturing-a-debug-log">
    Como capturar logs do SDK para solução de problemas.
  </Card>

  <Card title="Solução de problemas de Web Push" icon="globe" href="./troubleshooting-web-push">
    Solucione problemas de notificações push web.
  </Card>

  <Card title="Referência do SDK Mobile" icon="book" href="./mobile-sdk-reference">
    Referência completa da API para os SDKs Mobile do OneSignal.
  </Card>
</Columns>

***

## FAQ

### O que acontece se eu mudar meu OneSignal App ID no meu aplicativo?

Mudar o OneSignal App ID no código de inicialização do seu aplicativo criará um usuário completamente novo e uma subscription push sob o novo App ID quando o usuário atualizar e abrir o aplicativo para a versão mais recente.

Se seu iOS bundle ID e/ou Android package ID forem os mesmos, então o dispositivo continuará com o mesmo status de subscription push. Os dados do usuário serão completamente novos, ou seja, você precisará adicionar de volta seus aliases, tags, endereço de email, número de telefone no novo registro.

Se o iOS bundle ID ou Android package ID forem diferentes, então este é um aplicativo completamente novo e deve ter diferentes certificados/chaves push.

### O OneSignal pode enviar notificações push em uma rede fechada on-premise?

Isso pode funcionar contanto que os computadores na sua rede fechada tenham acesso aos servidores de gateway push que você deseja suportar:

* [https://support.apple.com/en-us/HT203609](https://support.apple.com/en-us/HT203609)
* [https://firebase.google.com/docs/cloud-messaging/concept-options#messaging-ports-and-your-firewall](https://firebase.google.com/docs/cloud-messaging/concept-options#messaging-ports-and-your-firewall)

Se a rede estiver completamente desconectada da Internet, notificações push não podem ser entregues através dos serviços padrão de OS/navegador, que é o que suportamos.

***