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

# Solución de problemas del SDK móvil

> Resuelve problemas comunes del SDK móvil de OneSignal, incluidos fallos en la entrega push, errores de APNS y problemas de mensajería en la app para iOS, Android y frameworks cross-platform.

<Note>
  Si tienes problemas con tu sitio web, consulta la [guía de solución de problemas de Web Push](./troubleshooting-web-push).
</Note>

## Pasos para solucionar problemas

### Revisar instrucciones de configuración y actualizar el SDK

Frecuentemente [publicamos actualizaciones](https://github.com/OneSignal/sdks) con correcciones de errores, mejoras y soporte para los últimos cambios del sistema operativo. Asegúrate de estar usando la última versión del SDK y de haber seguido las instrucciones de configuración.

<Card title="Configuración del SDK móvil" icon="wrench" href="./mobile-sdk-setup">
  Instrucciones de configuración diseñadas para ayudar a prevenir problemas comunes y probar la integración.
</Card>

### Revisar las guías comunes de solución de problemas

<Columns cols={2}>
  <Card title="Notificaciones no mostradas o retrasadas" icon="bell-slash" href="./notifications-show-successful-but-are-not-being-shown">
    Las notificaciones push no están apareciendo en el dispositivo o están retrasadas.
  </Card>

  <Card title="Imágenes de notificaciones no se muestran" icon="image" href="./notification-images-not-showing">
    Las imágenes no aparecen en la vista expandida de la notificación.
  </Card>

  <Card title="CTR de notificaciones" icon="arrow-pointer" href="./notification-ctr">
    Pocos o ningún clic en las notificaciones.
  </Card>

  <Card title="Notificaciones duplicadas" icon="copy" href="./duplicated-notifications">
    Las notificaciones aparecen varias veces en el dispositivo.
  </Card>

  <Card title="Solución de problemas de mensajes en la app" icon="message" href="./in-app-message-troubleshooting">
    Los mensajes en la app no se muestran o no se comportan como se esperaba.
  </Card>
</Columns>

### Verificar problemas comunes en tu app

#### Métodos de OneSignal que bloquean la visualización de push

Verifica si tu app tiene métodos como `optOut()`, por ejemplo `OneSignal.User.pushSubscription.optOut()`, o si configuraste `enabled: false` a través de nuestras REST APIs. Esto establece el estado de la suscripción push en `unsubscribed`. Consulta la [referencia del SDK móvil](./mobile-sdk-reference#optout-%2C-optin-%2C-optedin) para más detalles.

Si la app está abierta mientras se envía el push, es posible que estés impidiendo que el push se muestre mediante el método `preventDefault()`. Esto generalmente se configura en el [Listener de Eventos en Primer Plano](./mobile-sdk-reference#addforegroundlifecyclelistener-push) o en la [Extensión de Servicio de Notificaciones de Android](./service-extensions).

#### Conflictos con Firebase Messaging u otros SDKs

Si tu app también incluye el Firebase Messaging SDK u otros SDKs de notificaciones push, verifica que no intercepten mensajes antes de que OneSignal pueda procesarlos.

Este problema ocurre comúnmente cuando:

* Las notificaciones aparecen como **Entregadas** en OneSignal pero nunca aparecen en el dispositivo.
* La app incluye tanto OneSignal como `firebase_messaging` (o un `FirebaseMessagingService` personalizado).
* El push funciona cuando se elimina Firebase Messaging, pero falla cuando ambos SDKs están presentes.

1. Revisa tu `AndroidManifest.xml` en busca de receptores legacy de Firebase como `com.google.firebase.iid.FirebaseInstanceIdReceiver` y elimínalos/exclúyelos condicionalmente si OneSignal es responsable de la entrega push.

2. Verifica si hay implementaciones personalizadas de `FirebaseMessagingService` (o bibliotecas como `firebase_messaging` en Flutter) que anulen `onMessageReceived`. Si otro servicio procesa o suprime completamente los mensajes, puede consumir el payload de FCM antes de que OneSignal pueda mostrar la notificación.

3. Evita llamar a las APIs de gestión de tokens de Firebase como: `FirebaseMessaging.getToken()` o `FirebaseMessaging.deleteToken()`.

Si OneSignal es responsable de la entrega push, debe ser el único SDK que gestiona el ciclo de vida del token push. Obtener o gestionar el token FCM directamente puede provocar conflictos de propiedad del token y un comportamiento de entrega inconsistente.

Si necesitas el token push del dispositivo para otros sistemas, léelo desde OneSignal (por ejemplo, `User.pushSubscription.token`) y escucha los cambios de suscripción/token usando las [APIs de observador del SDK](./mobile-sdk-reference#addobserver-push-subscription-changes).

### Probar el proyecto de ejemplo para tu SDK

Verifica si tu problema es reproducible usando el proyecto de ejemplo mantenido por nuestro equipo de ingeniería para cada SDK.

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

### Verificar los registros de errores

Recopila datos de registro antes de diagnosticar más:

* Sigue la guía sobre [capturar un registro de depuración](./capturing-a-debug-log).
* Busca errores, advertencias o avisos de obsolescencia que puedan explicar el comportamiento.

<Card title="Capturar un registro de depuración" icon="bug" href="./capturing-a-debug-log">
  Cómo habilitar el registro detallado y capturar la salida del SDK para solucionar problemas.
</Card>

### Contactar soporte

Si aún tienes problemas, contacta a `support@onesignal.com` con:

* Tu App ID de OneSignal
* El External ID y/o Subscription ID del dispositivo afectado
* El ID de notificación o un enlace a la notificación en el panel (si aplica)
* Un [registro de depuración desde el dispositivo](./capturing-a-debug-log) reproduciendo el problema

***

## Errores comunes

### APNS Delegate never fired

Los errores como "APNS Delegate Never Fired" y "APNS 3000" son mensajes de tiempo de espera de Apple que indican que el dispositivo no pudo conectarse a los servidores APNS de Apple. Esto es más común cuando:

* Se prueba en entornos de desarrollo de APNS
* Se usan múltiples dependencias de notificaciones push o APIs push nativas de iOS junto con OneSignal
* Un problema de conectividad temporal — generalmente se resuelve solo la próxima vez que el usuario inicia una nueva sesión (app en segundo plano por 30+ segundos, luego reabierta)

**Pasos para resolver:**

1. Elimina cualquier otra dependencia de notificaciones push o APIs push nativas de iOS y usa solo OneSignal. Una vez que el error se resuelva, puedes volver a agregar el otro código. Contacta a `support@onesignal.com` para conocer las mejores prácticas de coexistencia.
2. Verifica el [registro de depuración desde el dispositivo](./capturing-a-debug-log) para más detalles.
3. Si el error persiste, [contacta soporte](#pasos-para-solucionar-problemas).

Si estás usando Capacitor, agrega esta configuración para permitir que OneSignal maneje las notificaciones 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>

### La app no se abre al cerrarla forzadamente y hacer clic en una notificación

Asegúrate de no estar probando en una compilación `Debug`. Por ejemplo, en apps Flutter, puedes:

* Usar una compilación de versión a través de Flutter, por ejemplo `flutter run --release` (requiere un dispositivo físico)
* Actualizar el esquema de Xcode a `Release` en lugar de `Debug`

***

## Páginas relacionadas

<Columns cols={2}>
  <Card title="Configuración del SDK móvil" icon="wrench" href="./mobile-sdk-setup">
    Instrucciones de configuración para todos los SDKs móviles y cross-platform compatibles.
  </Card>

  <Card title="Capturar un registro de depuración" icon="bug" href="./capturing-a-debug-log">
    Cómo capturar registros del SDK para solucionar problemas.
  </Card>

  <Card title="Solución de problemas de Web Push" icon="globe" href="./troubleshooting-web-push">
    Soluciona problemas de notificaciones push web.
  </Card>

  <Card title="Referencia del SDK móvil" icon="book" href="./mobile-sdk-reference">
    Referencia completa de la API para los SDKs móviles de OneSignal.
  </Card>
</Columns>

***

## Preguntas frecuentes

### ¿Qué sucede si cambio mi App ID de OneSignal en mi app?

Cambiar el App ID de OneSignal en el código de inicialización de tu app creará un usuario completamente nuevo y una suscripción push bajo el nuevo App ID cuando el usuario actualice y abra la app a la última versión.

Si tu bundle ID de iOS y/o package ID de Android son los mismos, entonces el dispositivo continuará con el mismo estado de suscripción push. Los datos del usuario serán completamente nuevos, es decir, necesitarás agregar nuevamente tus alias, tags, dirección de email, número de teléfono en el nuevo registro.

Si el bundle ID de iOS o el package ID de Android son diferentes, entonces esta es una app completamente nueva y debe tener diferentes certificados/claves push.

### ¿Puede OneSignal enviar notificaciones push en una red cerrada on-premise?

Esto puede funcionar siempre que las computadoras en tu red cerrada tengan acceso a los servidores de gateway push que deseas soportar:

* [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)

Si la red está completamente desconectada de Internet, las notificaciones push no pueden ser entregadas a través de los servicios estándar de OS/navegador, que es lo que soportamos.

***