Implement push service for Android

Update time: 2024/03/07 11:09:07

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:

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.0`，`firebase-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.

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

Xiaomi

jsonfinal 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

javafinal 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

javafinal vivoPushConfig = NIMMixPushConfig(
  vivoCertificateName: 'VIVO certificate',
);
/// Configure the settings for push service during initialization
NimCore.instance.initialize(
  NIMAndroidSDKOptions(
    appKey: appKey,
    /// Other parameters
    mixPushConfig: vivoPushConfig,
  ),
);

OPPO

javafinal 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

javafinal 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

java//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.

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.

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

javapublic 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

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

java[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.

json// 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.

javaNimCore.instance.settingsService.enablePushService(false);

Reference

Troubleshooting on push services
Flow control from third party channels. For more information, see push channel limit
To use the registered channel in the SDK for third-party vendors, see Channel information
Error codes for third-party push services
Configure payload

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

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