Guides

    Push troubleshooting

    Diagnose push failures specific to the React Native bridge. For native APNs/FCM configuration issues, this page links out to the platform guides.

    Because the React Native SDK wraps the native iOS and Android push stacks, most delivery problems are actually native configuration issues. Start with the platform-native troubleshooting guides for APNs/FCM setup, certificates, and delivery diagnostics:

    This page covers only the failures that are unique to the React Native layer.

    On this page

    Token never reaches ZMP

    If the device registers a token natively but ZMP never targets it:

    • Confirm the token is forwarded. The token must reach the SDK via ZetaClient.user.updateDeviceToken(token) — either from your native code or by listening for ZetaCoreEvents.DeviceTokenDelegate after calling ZetaClient.push.fetchToken(). See Forward the device token.
    • Verify the module is linked. Run npx react-native config and confirm zetakit_reactnative appears under dependencies. On iOS, run cd ios && pod install.
    • Check permissions. On iOS, and on Android 13+, a token is only useful once the user grants notification permission. Call ZetaClient.push.requestNotificationPermissions().

    JavaScript events never fire

    If push clicks or deep links work natively but your JS listeners are silent:

    • Register listeners early. Add your NativeEventEmitter (iOS) / DeviceEventEmitter (Android) listeners immediately after ZetaClient.initialize(). A listener registered after an event fires (for example, after a cold-start deep link) misses that event.
    • Use the right emitter per platform. Use new NativeEventEmitter(ZetaClient.bridge) on iOS and DeviceEventEmitter on Android.
    • Handle Android intents separately. On Android, deep links arrive as intents, not through DeeplinkDelegate. Read the launching intent with ZetaClient.push.getInitialIntent() and listen for ZetaCoreEvents.AndroidInitialIntent / AndroidNewIntent. See Handle Android deep links.

    Notifications arrive in the wrong environment

    If test pushes work but production pushes do not (or vice versa) on iOS:

    • Check appEnvironment. The appEnvironment field in ZTConfig (ZTAppEnvironment.SANDBOX vs ZTAppEnvironment.PRODUCTION) must match the APNs environment your build is signed for. A debug build using a production value — or a release build using sandbox — will fail to receive notifications. See iOS Push Troubleshooting.

    See also