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
andtoken
. - 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
.Xiaomijson
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, ), );
Huaweijava
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, ), );
VIVOjava
final vivoPushConfig = NIMMixPushConfig( vivoCertificateName: 'VIVO certificate', ); /// Configure the settings for push service during initialization NimCore.instance.initialize( NIMAndroidSDKOptions( appKey: appKey, /// Other parameters mixPushConfig: vivoPushConfig, ), );
OPPOjava
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, ), );
Meizujava
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, ), );
FCMjava
//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 totrue
, 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.Huaweijava
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); ... } } }
OPPOjava
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.
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
-
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
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.