Set up push service - Instant Messaging

Update time: 2024/01/03 02:36:23

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.

Understanding Moderator

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

Before implementing the push service, make sure:

Development requirement:
- Android 4.4 and later
- Since v6.9.0, the AndroidX support library is used. The Target API is changed to level 28 and the support library is no longer supported.
Integrated SDK.
You have created an application in the console and get the associated AppKey.
You have registered IM accounts and get accid and token.

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	IM Dev: 5.6.2 IM Stable: 5.6.2	Using Xiaomi push
Huawei	IM Dev: 6.9.0.300 IM Stable: 6.9.0.300	Using Huawei push
Honor	IM Dev: 7.0.41.301 IM Stable: 7.0.41.301	Using Honor push
OPPO	IM Dev: 3.1.0 IM Stable: 3.1.0	Using OPPO push
vivo	IM Dev: 3.0.0.4_484 IM Stable: 3.0.0.4_484	Using VIVO push
Meizu	IM Dev: 4.2.3 IM Stable: 4.2.3	Using Meizu push
FCM	IM Dev and IM Stable: `firebase-bom:28.4.2` library version: `firebase-messaging：23.0.0`，`firebase-analytics: 20.0.0`	Using FCM

Step 2: Install NIM SDK

Add third party packages for push service when installing NIM SDK.

If it is automatically integrated, you need to add relevant dependencies in dependencies.

javadependencies {
    compile fileTree(dir: 'libs', include: '*.jar')
    // Add dependencies. Note that the version numbers must be consistent.

    // Basic messaging (required)
    implementation "com.netease.nimlib:basesdk:${LATEST_VERSION}"
    // required if you integrate third party push service in the CommsEase platform.
    implementation "com.netease.nimlib:push:${LATEST_VERSION}"
}

For manual integration, you need to copy the nim-push-x.x.x.jar file from downloaded SDK to the app/libs folder of your project; then Right-click on the .jar file and add it as a dependency.

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 SDKOptions.mixPushConfig.

Xiaomi

javaMixPushConfig config = new MixPushConfig();
// Add the AppId and AppKey obtained from Xiaomi push platform
config.xmAppId = "xxxx";
config.xmAppKey = "xxxx";
// Add the certificate name configured in the CommsEase console.
config.xmCertificateName = "xxxx";
...
options.mixPushConfig = config;

Huawei

javaMixPushConfig config = new MixPushConfig();
// Add the APP ID of Huawei push
config.hwAppId = "xxxx";
// Add Huawei Push certificate name configured in the CommsEase console.
config.hwCertificateName = "xxxx";
...
options.mixPushConfig = config;

Honor

javaMixPushConfig config = new MixPushConfig();
//Add the Honor push certificate name configured in the CommsEase console and configure AppId in the AndroidManifest.xml file.
config.honorCertificateName = "xxxx";
...
options.mixPushConfig = config;

VIVO

javaMixPushConfig config = new MixPushConfig();
//Add the VIVO push certificate name configured in the CommsEase console and configure the AppId the AndroidManifest.xml file.
config.vivoCertificateName = "xxxx"; 
...
options.mixPushConfig = config;

OPPO

javaMixPushConfig config = new MixPushConfig();

config.oppoAppId = "xxxx";
config.oppoAppKey = "xxxxxx";
//Distinguish AppAppSercet and MasterSecret
config.oppoAppSercet = "xxxxxxx";
// Add OPPO push certificate name configured in the CommsEase console.
config.oppoCertificateName = "xxxx";
...
options.mixPushConfig = config;

Meizu

javaMixPushConfig config = new MixPushConfig();

config.mzAppId = "xxx";
config.mzAppKey = "xxxx";
config.mzCertificateName = "xxxx";
...
options.mixPushConfig = config;

FCM

java//Specify the FCM push certificate name configured in the CommsEase console and add the AppSecret in the AndroidManifest.xml file.
MixPushConfig config = new MixPushConfig();

config.fcmCertificateName = "xxxx";
...
options.mixPushConfig = config;

The push certificate name must not 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), NIM SDK selects the push channel recommended by IM servers.
- If NIMAndroidSDKOptions.mixPushConfig.autoSelectPushType is set to true, NIM SDK selects 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, Honor, and OPPO push services in Application#onCreate, or initialize Huawei, Honor, 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 NimApplication extends Application {
    ...
    @Override
    public void onCreate() {
        ...
        if (NIMUtil.isMainProcess(this)) {
            ...
            // Add the following code here
            com.huawei.hms.support.common.ActivityMgr.INST.init(this);
            ...
        }
    }
}

Honor

javapublic class NimApplication extends Application {
    ...
    @Override
    public void onCreate() {
        ...
        if (NIMUtil.isMainProcess(this)) {
            ...
            // Add the following code here
            HonorPushClient.getInstance().init(getApplicationContext(), true);
            ...
        }
    }
}

OPPO

javapublic class NimApplication 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

(Optional) After initialization, whether you are logged in or not, you have the option to call the registerPush method of MixPushService to acquire the push token. (The token will be obtained using the observeMixPushToken callback of MixPushServiceObserve.)

If the majority of your app users are situated overseas, and you intend to give priority to the FCM push channel, make sure to set FCM as the high priority in the CommsEase console in advance (Application Settings > More > Certificates). By taking this step, when you call this interface, the FCM token will be obtained as the primary preference.

Step 4: Test the push service

Sender:

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

java// Test account
String account = "testAccount";
// P2P chat
SessionTypeEnum sessionType = SessionTypeEnum.P2P;
String text = "this is an example";
// Create a text message.
IMMessage textMessage = MessageBuilder.createTextMessage(account, sessionType, text);
// Send messages to the recipient.
NIMClient.getService(MsgService.class).sendMessage(textMessage, false).setCallback(new RequestCallback<Void>() {
                @Override
                public void onSuccess(Void param) {

                }

                @Override
                public void onFailed(int code) {
                    
                }

                @Override
                public void onException(Throwable exception) {

                }
            });

Recipient:

The recipient will receive the offline message after logging in.

You can silence push notifications 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 enable.

javaNIMClient.getService(MixPushService.class).enable(false).setCallback(...)

Reference

Configure payload
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

FAQ

Events for triggering push notifications

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.

Events not triggering push notifications

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

A： 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

Understanding Moderator
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
Events for triggering push notifications
Events not triggering push notifications