DocsICP FilingConsole
官方文档
首页

Troubleshooting steps for not receiving push notifications on iOS

更新时间：
复制 MD 格式
产品详情
我的收藏

This topic describes how to troubleshoot and resolve issues when you do not receive push notifications on iOS.

Overview

This topic describes how to troubleshoot and resolve issues when you do not receive push notifications on iOS.

Prerequisites

  • You have activated the Multiexperience Development Platform (EMAS) service and created a project and an application. For more information, see Quick Start.

  • You have integrated the Mobile Push SDK as described in iOS SDK Integration.

  • You have configured the iOS push certificate as described in APNs Authentication Configuration.

Possible reasons for not receiving iOS push notifications

  • The device is expired, notification permissions are disabled, the application is in the foreground, or a deviceToken was not obtained.

  • The wrong push environment is used. [Common]

  • The push parameters are incorrect.

  • The push notification switch in Xcode is off.

  • The push certificate is expired or invalid.

  • The device is powered off.

Check the mobile device

  • You can use the troubleshooting tool in the EMAS console to check device validity. A device is deleted after 90 days of inactivity. You can also check basic device information, such as whether the Apple Push Notification service (APNs) token is registered and the status of the push notification switch.

  • For a notification to appear, the app must be in the background or closed when the notification is sent.

    • On devices running a version of iOS earlier than 10, the app does not display pop-up notifications or notifications in the notification center if it is in the foreground.

    • On devices running iOS 10 or later, after the callback for a foreground notification is processed, you can call the completionHandler to display a pop-up notification in the foreground. For more information, see Adapting to iOS 10 notifications.

  • You can check the push configuration on the mobile device. To do this, verify that the device can obtain a Device Token from the Apple APNs server.

    - (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error
{
    NSLog(@"didFailToRegisterForRemoteNotificationsWithError %@", error);
}

  • You can check if the unregisterForRemoteNotifications interface is called in your code. If this interface is called, the device cannot receive notifications from APNs.

Check the push environment

APNs push notification environments

The Apple APNs channel has two separate environments: development and production.

  1. Development environment (Sandbox)

    1. Scenario: This environment is suitable for development and testing.

    2. App installation method: Install the app directly to the device through Xcode.

    3. Push certificate: Use a Sandbox push certificate.

  2. Production environment (Production)

    1. Scenario: This environment is suitable for official release and Ad Hoc testing.

    2. App installation method: Install the app through the App Store or TestFlight.

    3. Push certificate: Use a production push certificate.

    4. For information about how to test production environment notifications, see How to test production environment push notifications for an Ad Hoc app.

Common errors

  1. BadDeviceToken: If you select an incorrect push environment or use an incorrect push certificate, the Apple APNs server considers the Device Token invalid and cannot push the notification. If the push status in the console is "failed" with the reason "BadDeviceToken", check your installation package and use the correct push environment.

  2. iOSApnsEnv: In the Advanced Push feature of the OpenAPI, the server-side can set the push environment using the iOSApnsEnv parameter.

    Important

    Note: The "i" in "iOSApnsEnv" must be lowercase. Otherwise, the parameter is invalid. The default push environment is the production environment.

Check the push parameters

  1. iOSInterruptionLevel is a new parameter in iOS 15. If you set this parameter to passive, the system adds the notification to the notification list without lighting up the screen or playing a sound, which can cause the notification to be missed. Therefore, we recommend that you set iOSInterruptionLevel to "active".

  2. Check whether the device is bound: When you push notifications by alias, account, or tag, the test device may not be bound to the specified alias, account, or tag. You can use the OpenAPI to query whether the test device is bound to the push target.

Check the IDE settings

  • Xcode 8 and later versions include a push notification switch. You must ensure that this switch is turned on.

  • If the push notification switch is off, the deviceToken registration error callback (didFailToRegisterForRemoteNotificationsWithError:) is triggered with the following error message: 

    Error Domain=NSCocoaErrorDomain Code=3000 "no valid 'aps-environment' entitlement string found for application" UserInfo=0x1740741c0 {NSLocalizedDescription="no valid 'aps-environment' entitlement string found for application"

Check the push certificate validity

  • In the EMAS console, you can check whether the push certificate is valid. For more information about certificate configuration, see iOS Push Certificate Settings.

  • You can also use third-party tools to quickly test whether your APNs push certificate information is correct. For more information, see NWPusher.

Device is powered off

If a device is powered off, Apple APNs only stores the last notification sent to it. When the device is turned on again, it receives only that last notification.

Applies to

  • Mobile Push