Integrate the Mobile Push component for Android - Mobile Platform as a Service

This topic describes how to integrate the Mobile Push Service component into an Android client. MPS supports two integration methods: native AAR and componentized (Portal & Bundle) integration.

Prerequisites

You have integrated mPaaS into your project.
- If you use the native AAR integration method, you must first add mPaaS to your project add mPaaS to your project.
- If you use the component-based integration method, you must first complete the integration process component-based integration process.
You have obtained the .config configuration file from the mPaaS console. For more information about generating and downloading the configuration file, see Step 3 Add the configuration file to your project Add the configuration file to your project.
The MPPushMsgServiceAdapter method in this topic applies only to baseline 10.1.68.32 and later. If your baseline version is earlier than 10.1.68.32, you must upgrade it by following the instructions in the mPaaS 10.1.68 upgrade guide mPaaS upgrade guide.
Note
The AliPushRcvService method from earlier versions is still supported. To view the documentation for earlier versions, click here to download.

Procedure

To use the Mobile Push Service, complete the following steps:

Add the Push SDK dependency and configure the AndroidManifest file.
1. Add the SDK dependency. Follow the instructions for your integration method:
  - Native AAR: In your project, use Component Management (AAR) to install the Mobile Push (PUSH) component. For more information, see Manage component dependencies (native AAR)Manage component dependencies (native AAR).
  - Component-based: In your Portal and Bundle projects, use Component Management to install the Mobile Push (PUSH) component. For more information, see Integration process Add component dependencies.
2. Add the configuration for AndroidManifest by adding the following content to the AndroidManifest.xml file:
  Note
  If you use the component-based integration method, add the AndroidManifest configuration in the Portal project.
```
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

<service
    android:name="com.alipay.pushsdk.push.NotificationService"
    android:enabled="true"
    android:exported="false"
    android:label="NotificationService"
    android:process=":push">
    <intent-filter>
        <action android:name="${applicationId}.push.action.START_PUSHSERVICE" />
    </intent-filter>
</service>
<receiver
    android:name="com.alipay.pushsdk.BroadcastActionReceiver"
    android:enabled="true"
    android:exported="true"
    android:process=":push">
    <intent-filter android:priority="2147483647">
        <action android:name="android.intent.action.BOOT_COMPLETED" />
        <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
        <action android:name="android.intent.action.USER_PRESENT" />
        <action android:name="android.intent.action.ACTION_POWER_CONNECTED" />
    </intent-filter>
</receiver>
```
3. To improve message delivery rates, the MPS SDK has a built-in process keepalive feature. This feature includes the com.alipay.pushsdk.BroadcastActionReceiver, which listens for system broadcasts to start the push process, and provides for automatic restarts if the process is terminated. You can enable or disable these features as needed:
  1. To stop listening for system boot broadcasts, delete the following code:
```
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<action android:name="android.intent.action.BOOT_COMPLETED" />
```
  2. To stop listening for network transition broadcasts, delete the following code:
```
<action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
```
  3. To stop listening for user presence broadcasts, delete the following code:
```
<action android:name="android.intent.action.USER_PRESENT" />
```
  4. To stop listening for charging state change broadcasts, delete the following code:
```
<action android:name="android.intent.action.ACTION_POWER_CONNECTED" />
```
  5. If you do not need to receive all the preceding broadcasts, you can set the android:enabled property of com.alipay.pushsdk.BroadcastActionReceiver to false.
  6. To prevent the push process from automatically restarting after it is terminated, add the following configuration under the application node:
```
<meta-data
		android:name="force.kill.push"
		android:value="on" />
```
    Note
    This configuration is valid only for baseline version 10.2.3.21 and later.
Initialize the push service to establish a persistent connection between the client and the Mobile Push gateway. The Push SDK maintains this persistent connection, which is a self-built channel.
Follow the instructions for your integration method:
- Native AAR
  - If you have already completed the process in Initialize mPaaS in the Application, call the following method after the MP.init() method:
```
 MPPush.init(this);
```
  - If you have not called the mPaaS initialization method, call the following methods in the Application:
```
  MPPush.setup(this);
  MPPush.init(this);
```
- Component-based
  Call the following method in the postInit method of LauncherApplicationAgent or LauncherActivityAgent:
```
MPPush.init(context);
```

Create a service that inherits MPPushMsgServiceAdapter and override the onTokenReceive method to receive the device ID (token) from the self-built channel.

public class MyPushMsgService extends MPPushMsgServiceAdapter {

    /**
     * Callback for receiving the token from the self-built channel
     *
     * @param token The token for the self-built channel
     */
    @Override
    protected void onTokenReceive(String token) {
        Log.d("Received token for self-built channel: " + token);
    }

}

Declare this service in the AndroidManifest.xml file:

<service
    android:name="com.mpaas.demo.push.MyPushMsgService"
    android:exported="false">
    <intent-filter>
        <action android:name="${applicationId}.push.action.MESSAGE_RECEIVED" />
        <action android:name="${applicationId}.push.action.REGISTRATION_ID" />
        <category android:name="${applicationId}" />
    </intent-filter>
</service>

After you complete this step, you can push messages to specific devices from the console using the device dimension. The required device ID is the token that you received.

Attach a user ID. This user ID is developer-defined. It can be a user identity from your user system or another parameter that can be mapped to each user, such as an account or mobile phone number.
After you receive the token, you can attach the token to a user ID:
```
String userId = "custom_user_id";
ResultPbPB bindResult = MPPush.bind(context, userId, token);
Log.d("Attach user ID " + (bindResult.success ? "succeeded" : ("failed: " + bindResult.code)));
```
If you have already called MPLogger to set a user ID, you can omit the user ID when you attach the token. For example:
```
MPLogger.setUserId("custom_user_id");
ResultPbPB bindResult = MPPush.bind(context, token);
```
To detach a user ID, for example, when a user logs out, call the following method:
```
ResultPbPB unbindResult = MPPush.unbind(context, userId, token);
ResultPbPB unbindResult = MPPush.unbind(context, token);
```
After you complete this step, you can push messages to specific users from the console using the user dimension. The required user identity is your custom user ID.
(Optional) Attach a user mobile phone number.
Important
Currently, the supplemental text message service is available only in the China (Hangzhou) region for non-financial services.
After you receive the token, you can also attach the token to a user's mobile phone number. You can attach the token to both a user ID and a mobile phone number at the same time. After you attach a mobile phone number, the user can receive push notifications as text messages on that number.
```
String userId = "custom_user_id";
String phoneNumber = "138xxxxxxxx"
ResultPbPB bindResult = MPPush.bind(context, userId, token,phoneNumber);
Log.d("Attach user ID " + (bindResult.success ? "succeeded" : ("failed: " + bindResult.code)));
```

Related operations

To improve message delivery rates, integrate third-party push channels provided by Android phone manufacturers. Huawei, Xiaomi, OPPO, and vivo channels are supported. For more information, see Integrate third-party channels.
By default, when a message is received, the SDK displays a notification that opens a webpage when clicked. To redirect to an in-app page using a custom deep link or to otherwise customize the notification click behavior, see Handle notification clicks.

For more information about other features, see Advanced Features.

Code example

To download the sample code package, click here.

What to do next

After the integration is complete, you can call a RESTful API on the server-side to push messages. For more information, see Configure the server-side.