Implement push service for Android

Update time: 2023/10/11 16:29:17

To enhance message delivery rates, CommsEase has integrated push services from third-party providers. The advantage of integrating push services from vendors like Xiaomi, Huawei, Vivo, OPPO, Meizu, etc., is their stable system-level persistent connections, enabling real-time receipt of notifications.

Overview

The NIM SDK supports the push notification service.

In scenarios where a user terminates the application process (either by suspension or actively closing it), or when the client SDK encounters network instability, push notifications from mobile system vendors will be sent to alert the user about pending messages.

By integrating the push notification SDKs offered by different mobile system vendors with the NIM SDK, you can enable push notification service.

How it works

The following diagram shows how the push service works:

Push_diagram.png

Prerequisites

  • You have created an application in the console and get the associated AppKey.
  • You have registered an IM account and get the accid and token.
  • Development requirement:
    • Flutter-dart 2.17.0 or later
    • Android Studio 3.5 or later
    • Android 4.4 API level 19 or later
    • 1.5.21 or later for kotlin-gradle-plugin

Workflow

Step 1: Integrate third-party push services

See the specific vendor's integration documentation for integrating the push SDK provided by third-party vendors and accessing their offline push services.

The following third-party vendors are supported:

Vendor Compatible version Guide
Xiaomi MiPush_SDK_Client_5_1_0 Using Xiaomi push
Huawei com.huawei.hms:push: 6.5.0.300 Using Huawei push
OPPO com.heytap.msp-push-3.1.0.aar Using OPPO push
VIVO vivo_pushsdk_v3.0.0.4_484 Using VIVO push
Meizu com.meizu.flyme.internet:push-internal:4.1.0 Using Meizu push
FCM firebase-bom:28.4.2
specific version: firebase-messaging:23.0.0firebase-analytics: 20.0.0
Using FCM

Step 2: Install NIM SDK

See Install NIM SDK.

Step 3: Initialize NIM SDK

When Initializing NIM SDK, configure the push certificate provided by the vendor and select the appropriate push channel.

  1. The push certificate must be configured in the initialization parameter NIMAndroidSDKOptions.mixPushConfig.

    Xiaomi
    final xmPushConfig = NIMMixPushConfig(  
      xmAppId: 'Xiaomi AppId',
      xmAppKey: 'Xiaomi AppKey',
      xmCertificateName: 'Xiaomi Certificate',
    );
    //Configure the settings for push service during initialization
    NimCore.instance.initialize(
      NIMAndroidSDKOptions(
        appKey: appKey,
        // Other parameters
        // ...
        mixPushConfig: xmPushConfig,
      ),
    );
    
    Huawei
    final hwPushConfig = NIMMixPushConfig(  
      hwAppId: 'Huawei AppId',
      hwCertificateName: 'Huawei certificate',
    );
    //Configure the settings for push service during initialization
    NimCore.instance.initialize(
      NIMAndroidSDKOptions(
        appKey: appKey,
        // Other parameters
        // ...
        mixPushConfig: hwPushConfig,
      ),
    );
    
    VIVO
    final vivoPushConfig = NIMMixPushConfig(
      vivoCertificateName: 'VIVO certificate',
    );
    /// Configure the settings for push service during initialization
    NimCore.instance.initialize(
      NIMAndroidSDKOptions(
        appKey: appKey,
        /// Other parameters
        mixPushConfig: vivoPushConfig,
      ),
    );
    
    OPPO
    final oppoPushConfig = NIMMixPushConfig(
      oppoAppId: 'OPPOAppId',
      oppoAppKey: 'OPPOAppKey',
      oppoAppSecret: 'OPPOAppSecret',
      oppoCertificateName: 'OPPO certificate',
    );
    /// Configure the settings for push service during initialization
    NimCore.instance.initialize(
      NIMAndroidSDKOptions(
        appKey: appKey,
        /// Other parameters
        mixPushConfig: oppoPushConfig,
      ),
    );
    
    Meizu
    final mzPushConfig = NIMMixPushConfig(
      mzAppId: 'MeizuAppId',
      mzAppKey: 'MeizuAppKey',
      mzCertificateName: 'Meizu certificate',
    );
    /// Configure the settings for push service during initialization
    NimCore.instance.initialize(
      NIMAndroidSDKOptions(
        appKey: appKey,
        /// Other parameters
        mixPushConfig: mzPushConfig,
      ),
    );
    
    FCM
    //Specify the FCM push certificate name configured in the CommsEase console and add the AppSecret in the AndroidManifest.xml file.
    final fcmPushConfig = NIMMixPushConfig(
      fcmCertificateName: 'FCM certificate',
    );
    /// Configure the settings for push service during initialization
    NimCore.instance.initialize(
      NIMAndroidSDKOptions(
        appKey: appKey,
        /// Other parameters
        mixPushConfig: fcmPushConfig,
      ),
    );
    

    The push certificate name cannot exceed 32 characters in length; otherwise, an error 500 will be reported during the login process.

  2. Select the push service channel

    • If NIMAndroidSDKOptions.mixPushConfig.autoSelectPushType is set false (default), the NIM SDK select the push channel recommended by IM servers.

    • If NIMAndroidSDKOptions.mixPushConfig.autoSelectPushType is set to true, NIM SDK determines the push channel based on the actual acquired token. In this case, the push channel recommended by IM servers has the highest priority. When selecting push channels, begin by verifying if the device supports the push service. Next, request tokens from all potential push vendors. Finally, opt for the push channels with higher priority from the tokens successfully acquired.

    By default, the SDK assigns the lowest priority to Google FCM push notifications. Consequently, if you have integrated both FCM and push services from other vendors, the system will prioritize the push channels of other vendors over FCM. However, if the majority of your app users are situated overseas and you have designated FCM as the priority in the CommsEase console (Application > Settings > More > Push Certificates), then when integrating both FCM and other vendor's push SDKs, the system will prioritize the FCM push channel.

  3. Enable Huawei and OPPO push services in Application#onCreate, initialize Huawei and OPPO push services. However, for push services from other vendors, there is no need for additional initialization, and you can skip this step.

    Huawei
    public class FlutterIMApplication extends Application {
        ...
        @Override
        public void onCreate() {
            ...
            if (NIMUtil.isMainProcess(this)) {
                ...
                // Add the following code here
                com.huawei.hms.support.common.ActivityMgr.INST.init(this);
                ...
            }
        }
    }
      
    
    OPPO
    public class FlutterIMApplication extends Application {
        ...
        @Override
        public void onCreate() {
            ...
            if (NIMUtil.isMainProcess(this)) {
                ...
                // Add the following code here
                com.heytap.msp.push.HeytapPushManager.init(this, true);
                ...
            }
        }
    }
    

If you have successfully integrated third-party push services and transmitted the relevant push tokens to the NIM (NetEase IM) server, the SDK logs will record the following corresponding information. In these logs, "pushType" and "type" indicate the push type (5 for Xiaomi, 6 for Huawei, 7 for Meizu, 8 for Google FCM, 9 for VIVO, 10 for OPPO, 0 for not supported). "tokenName" represents the name of the push certificate, and "token" signifies the push token.

[ui]mix_push: after login, mix push state=MixPushState{pushType=5, hasPushed=0, lastDeviceId=''}
[ui]mix_push: commit mix push token:type 5 tokenName PUSH_CER_NAME token y7ssE..................sLxnU

Step 4: Test the push service

Sender:

Deliver a message or custom system notification to a user (offline). For more information, see send a message and custom system notification.

Using the sending of a text message as an example, you can achieve this by invoking the sendMessage method. By default, the messages you send will initiate push notifications. If you need to customize push content, badge count, or push content title, see Configure properties of push notifications.

// Test account
String account = 'testAccount';
// P2P chat
NIMSessionType sessionType = NIMSessionType.p2p;
String text = 'this is an example';
// Create and send a text message.
Future<NIMResult<NIMMessage>> result = MessageBuilder.createTextMessage(
    sessionId: account, sessionType: sessionType, text: text)
    .then((value) => value.isSuccess
    ? NimCore.instance.messageService
        .sendMessage(message: value.data!, resend: false)
    : Future.value(value));

Recipient:

The recipient will receive the offline message after logging in.

  • You can silence push notification for a specified duration. For more information, see Silence push notifications.
  • You can also configure multi-device policy for push notifications, allowing you to send messages to multiple clients associated with the same account. To learn more about this feature, see Setting multi-device push policy.

(Optional) Step 5: enable or disable the push service

The third-party push service is enabled by default and does not require a separate API call to activate it. If you decide to discontinue the use of the third-party push service, you can disable it using enablePushService.

NimCore.instance.settingsService.enablePushService(false);

Reference

FAQ

Q: What are the conditions that trigger offline push notifications?

A: Offline push notifications are triggered when the Android app is moved to the background and subsequently reclaimed by the system or when the user actively closes the app. These specific conditions must be met to initiate a push notification. Hence, if you wish to test Android push notifications, log in and close the app to ensure that the requisite conditions for push notifications are satisfied.

Q: In which situations will push notifications not be triggered?

A: Push notifications will not be triggered in the following cases: When the IM account is not logged in, is logged out, or when the user is kicked out. When the application is running in the foreground. Push notifications may be triggered only when the user is logged into the IM account and has not logged out or been kicked out.

Was this page helpful?
Yes
No
  • Overview
  • How it works
  • Prerequisites
  • Workflow
  • Step 1: Integrate third-party push services
  • Step 2: Install NIM SDK
  • Step 3: Initialize NIM SDK
  • Step 4: Test the push service
  • (Optional) Step 5: enable or disable the push service
  • Reference
  • FAQ