前言

本章節(jié)介紹移動(dòng)推送Android SDK的接入方法。

• 推薦使用Gradle管理依賴的Android Studio項(xiàng)目。

• 支持Android 4.4及以上版本。

• 本文檔僅適合移動(dòng)推送Android SDK V3.0.0及以上版本的集成操作。

移動(dòng)推送Android SDK Demo工程請(qǐng)參見：移動(dòng)推送Android Demo。

Demo工程使用Kotlin + MVVM開發(fā)，界面更美觀，功能更豐富，開發(fā)者可參考Demo更快速了解移動(dòng)推送Android SDK如何使用。

準(zhǔn)備工作

• 已創(chuàng)建項(xiàng)目和應(yīng)用。具體操作請(qǐng)參見創(chuàng)建項(xiàng)目和應(yīng)用。

• 已閱讀Android SDK版本說(shuō)明，獲取最新版本對(duì)應(yīng)關(guān)系。

第一步：將SDK添加到您的應(yīng)用

我們提供了Maven依賴和本地依賴兩種集成方式，方便您根據(jù)需要將SDK添加到您的應(yīng)用中。

1 Maven依賴方式

1.1 配置Maven倉(cāng)庫(kù)

下面分別介紹Gradle 7.0及以上推薦的dependencyResolutionManagement配置方式和Gradle 7.0之下推薦的allprojects配置方式。

1.1.1 dependencyResolutionManagement方式

在您的根級(jí)（項(xiàng)目級(jí)）Gradle 文件（<project>/settings.gradle）中，在dependencyResolutionManagement的repositories中添加Maven倉(cāng)庫(kù)地址。

dependencyResolutionManagement {
  repositories {
    maven {
      url 'https://maven.aliyun.com/nexus/content/repositories/releases/'
    }

    // 配置HMS Core SDK的Maven倉(cāng)地址，集成華為通道需要。
    maven {
      url 'https://developer.huawei.com/repo/'
    }
  }
}

1.1.2 allprojects方式

在您的根級(jí)（項(xiàng)目級(jí)）Gradle 文件（<project>/build.gradle）中，在allprojects的repositories中添加Maven倉(cāng)庫(kù)地址。

allprojects {
  repositories {
    maven {
      url 'https://maven.aliyun.com/nexus/content/repositories/releases/'
    }

    // 配置HMS Core SDK的Maven倉(cāng)地址，集成華為通道需要。
    maven {
      url 'https://developer.huawei.com/repo/'
    }
  }
}

1.2 添加SDK依賴

在您的模塊（應(yīng)用級(jí)）Gradle 文件（通常是<project>/<app-module>/build.gradl）中，在dependencies中添加SDK依賴。

dependencies {
  implementation 'com.aliyun.ams:alicloud-android-push:{pushVersion}'
}

2 本地依賴方式

2.1 下載SDK

參考下載和集成SDK，選擇移動(dòng)推送進(jìn)行下載，將SDK包內(nèi)所有文件拷貝至您的模塊（應(yīng)用級(jí)）的<project>/<app-module>/libs目錄下。

2.2 添加SDK依賴

2.2.1 配置本地SDK目錄

在您的模塊（應(yīng)用級(jí)）Gradle 文件（通常是<project>/<app-module>/build.gradle）中，添加本地SDK文件目錄地址。

repositories {
  flatDir {
    dirs 'libs'
  }
}

2.2.2 添加SDK依賴

在您的模塊（應(yīng)用級(jí)）Gradle 文件（通常是<project>/<app-module>/build.gradle）中，的dependencies中添加SDK依賴。

dependencies {
  implementation fileTree(include: ['*.jar'], dir: 'libs')
  implementation (name:'alicloud-android-push-3.x.x', ext: 'aar')
  implementation (name:'alicloud-android-accs-4.x.x', ext: 'aar')
  // 把所有的aar都添加上
  ...
  // 華為從5.0.2版本開始不再提供離線包
  implementation 'com.huawei.hms:push:x.x.x.x'
  // 魅族從4.1.4版本開始不再提供離線包
  implementation 'com.meizu.flyme.internet:push-internal:x.x.x'
}

第二步：配置使用SDK

1 配置AppKey和AppSecret

配置AppKey和AppSecret有兩種方式，AndroidManifest文件配置和代碼配置兩種方式。請(qǐng)根據(jù)您的需求選擇其中一種方式進(jìn)行配置即可。

1.1 AndroidManifest文件配置方式

在AndroidManifest.xml文件中配置AppKey、AppSecret。按下面的方式，在application節(jié)點(diǎn)添加相應(yīng)的meta-data。

<application android:name="*****">
    <!-- 請(qǐng)?zhí)顚懩阕约旱腶ppKey -->
    <meta-data android:name="com.alibaba.app.appkey" android:value="*****"/> 
    <!-- 請(qǐng)?zhí)顚懩阕约旱腶ppSecret -->
    <meta-data android:name="com.alibaba.app.appsecret" android:value="****"/> 
</application>

1.2 代碼配置方式

除了在AndroidManifest中配置AppKey和AppSecret的方式，您也可以在代碼中進(jìn)行配置。

val pushInitConfig = PushInitConfig.Builder()
    .application(application)
    .appKey(appKey)    //請(qǐng)?zhí)顚懩阕约旱腶ppKey
    .appSecret(appSecret)    //請(qǐng)?zhí)顚懩阕约旱腶ppSecret
    .build()

PushInitConfig pushInitConfig = new PushInitConfig.Builder()
        .application(application)
        .appKey(appKey)    //請(qǐng)?zhí)顚懩阕约旱腶ppKey
        .appSecret(appSecret)    //請(qǐng)?zhí)顚懩阕约旱腶ppSecret
        .build();

更多配置接口請(qǐng)查看基礎(chǔ)配置接口和高階配置接口。

2 SDK初始化

為了盡量降低對(duì)App啟動(dòng)速度的影響，初始化可以分階段進(jìn)行。

2.1 必須在Application onCreate中執(zhí)行的邏輯

此階段初始化用于初始化一些推送參數(shù)，沒(méi)有啟動(dòng)推送邏輯，必須在Application onCreate中執(zhí)行。

根據(jù)上一節(jié)中選擇的配置AppKey和AppSecret的方式，這里初始化代碼也有兩種方式。

AndroidManifest文件配置方式

PushServiceFactory.init(context)

PushServiceFactory.init(context);

代碼配置方式

PushServiceFactory.init(pushInitConfig)

PushServiceFactory.init(pushInitConfig);

2.2 可以延遲執(zhí)行的邏輯

此階段初始化用于建立推送的長(zhǎng)連接，可以根據(jù)業(yè)務(wù)需要和合規(guī)要求延遲執(zhí)行。

val pushService = PushServiceFactory.getCloudPushService()
pushService.register(this, object : com.alibaba.sdk.android.push.CommonCallback {
    override fun onSuccess(success: String) {}
    override fun onFailed(errorCode: String, errorMessage: String) {}
})

CloudPushService pushService = PushServiceFactory.getCloudPushService();
pushService.register(this, new com.alibaba.sdk.android.push.CommonCallback() {
    @Override
    public void onSuccess(String success) {

    }

    @Override
    public void onFailed(String errorCode, String errorMessage) {
        
    }
});

3 消息接收配置

到這一步說(shuō)明您已經(jīng)完成了SDK的初始化，推送長(zhǎng)連接已經(jīng)成功建立，但是要接收推送消息，還需要進(jìn)行一些配置。

我們提供了MessageReceiver/AliyunMessageIntentService兩種方式，方便您攔截通知，接收消息，獲取推送中的擴(kuò)展字段。或者在通知打開或刪除的時(shí)候，切入進(jìn)行后續(xù)處理。

您可以任選一種方式處理推送的消息。具體查看MessageReceiver/AliyunMessageIntentService相關(guān)接口。

4 NDK配置

在您的模塊（應(yīng)用級(jí)）Gradle 文件（通常是<project>/<app-module>/build.gradle）中，在android的defaultConfig節(jié)點(diǎn)下添加NDK配置。

android {
    defaultConfig {
        ndk {
            //選擇要添加的對(duì)應(yīng)cpu類型的.so庫(kù)。此處僅為示意，推送支持所有主流類型，請(qǐng)根據(jù)實(shí)際需求選擇
            abiFilters 'arm64-v8a', 'armeabi-v7a', 'x86', 'x86_64'
        }
    }
}

5 自定義推送通知樣式（可選）

如果您需要自定義通知的樣式，可以查看自定義通知樣式相關(guān)接口。

6 攔截推送通知（可選）

如果您需要攔截處理推送通知，只要擴(kuò)展MessageReceiver/AliyunMessageIntentService的showNotificationNow和onNotificationReceivedInApp即可，下面以MessageReceiver的擴(kuò)展方式來(lái)舉例。

class MyMessageReceiver: MessageReceiver(){

    override fun onNotificationReceivedInApp(
        context: Context?,
        title: String?,
        summary: String?,
        map: MutableMap<String, String>?,
        openType: Int,
        openActivity: String?,
        openUrl: String?
    ) {
        //這里可以處理下發(fā)的推送通知
    }

    override fun showNotificationNow(p0: Context?, p1: MutableMap<String, String>?): Boolean {
        //false表示攔截，true表示不攔截，請(qǐng)根據(jù)進(jìn)行攔截，攔截后會(huì)執(zhí)行到 onNotificationReceivedInApp
        return false
    }
}

public class MyMessageReceiver extends MessageReceiver {
    @Override
    protected void onNotificationReceivedInApp(Context context, String title, String summary, Map<String, String> map, int openType, String openActivity, String openUrl) {
        //這里可以處理下發(fā)的推送通知
    }

    @Override
    public boolean showNotificationNow(Context context, Map<String, String> map) {
        //false表示攔截，true表示不攔截，請(qǐng)根據(jù)進(jìn)行攔截，攔截后會(huì)執(zhí)行到 onNotificationReceivedInApp
        return false;
    }
}

攔截的推送通知，點(diǎn)擊和取消事件，需要您自行上報(bào)，上報(bào)接口見自建通知統(tǒng)計(jì)上報(bào)接口。

7 處理推送消息（建議）

推送支持的消息有兩類，其中推送通知，在SDK有默認(rèn)實(shí)現(xiàn)，消息到達(dá)手機(jī)后會(huì)通過(guò)通知欄展示；而推送消息需要您擴(kuò)展API實(shí)現(xiàn)。只要擴(kuò)展MessageReceiver/AliyunMessageIntentService的onMessage接口即可。下面以MessageReceiver的擴(kuò)展方式來(lái)舉例。

class Kk: MessageReceiver() {
    override fun onMessage(context: Context?, cPushMessage: CPushMessage?) {
        val title = cPushMessage?.title
        val content = cPushMessage?.content

        if (isForeground) {
            //App處于前臺(tái)，彈窗形式顯示
        } else {
            //App處于后臺(tái)，通知形式顯示
        }
    }
}

public class MyMessageReceiver extends MessageReceiver {
    @Override
    protected void onMessage(Context context, CPushMessage cPushMessage) {
        String title = cPushMessage.getTitle();
        String content = cPushMessage.getContent();

        if (isForeground) {
            //App處于前臺(tái)，彈窗形式顯示
        } else {
            //App處于后臺(tái)，通知形式顯示
        }
    }
}

對(duì)于推送消息的點(diǎn)擊和取消事件，需要您自行上報(bào)，上報(bào)接口見自建通知統(tǒng)計(jì)上報(bào)接口。

8 使用標(biāo)簽進(jìn)行推送（可選）

除了全量推送，我們也支持使用標(biāo)簽進(jìn)行批量推送。在通過(guò)標(biāo)簽進(jìn)行推送前，SDK側(cè)需要將設(shè)備綁定上標(biāo)簽，相關(guān)接口見標(biāo)簽（tag）相關(guān)接口。代碼示例如下：

PushServiceFactory.getCloudPushService()
    .bindTag(CloudPushService.DEVICE_TARGET, arrayOf(tag), null, object : CommonCallback {
        override fun onSuccess(s: String) {}
        override fun onFailed(errorCode: String, errorMsg: String) {}
    })

PushServiceFactory.getCloudPushService().bindTag(CloudPushService.DEVICE_TARGET, new String[]{tag}, null, new CommonCallback() {
    @Override
    public void onSuccess(String s) {

    }

    @Override
    public void onFailed(String errorCode, String errorMsg) {

    }
});

除了使用標(biāo)簽進(jìn)行推送外，我們還支持：

• 使用賬號(hào)進(jìn)行推送

• 使用別名進(jìn)行推送

9 集成輔助通道（建議）

為了提高App離線狀態(tài)下的推送到達(dá)率，建議集成輔助通道。請(qǐng)參考輔助通道集成進(jìn)行集成。

10 混淆配置

如果您的項(xiàng)目中使用Proguard等工具做了代碼混淆，請(qǐng)保留以下配置：

-keepclasseswithmembernames class ** {
    native <methods>;
}
-keepattributes Signature
-keep class sun.misc.Unsafe { *; }
-keep class com.taobao.** {*;}
-keep class com.alibaba.** {*;}
-keep class com.alipay.** {*;}
-keep class com.ut.** {*;}
-keep class com.ta.** {*;}
-keep class anet.**{*;}
-keep class anetwork.**{*;}
-keep class org.android.spdy.**{*;}
-keep class org.android.agoo.**{*;}
-keep class android.os.**{*;}
-keep class org.json.**{*;}
-dontwarn com.taobao.**
-dontwarn com.alibaba.**
-dontwarn com.alipay.**
-dontwarn anet.**
-dontwarn org.android.spdy.**
-dontwarn org.android.agoo.**
-dontwarn anetwork.**
-dontwarn com.ut.**
-dontwarn com.ta.**

第三步：接入驗(yàn)證

1 打開SDK日志

val pushService = PushServiceFactory.getCloudPushService()
//僅適用于Debug包，正式包不需要此行
pushService.setLogLevel(CloudPushService.LOG_DEBUG)

CloudPushService pushService = PushServiceFactory.getCloudPushService();
//僅適用于Debug包，正式包不需要此行
pushService.setLogLevel(CloudPushService.LOG_DEBUG);      

2 啟動(dòng)正常確認(rèn)方法

• 回調(diào)方法callback.onSuccess()被調(diào)用。在logcat日志中，輸入tag：MPS：

2024-07-03 10:34:48.630 14509-9747  [MPS]                   com.aliyun.emas.pocdemo              I  agoo init success.
2024-07-03 10:34:48.631 14509-9749  [MPS]                   com.aliyun.emas.pocdemo              D  register agoo result 錯(cuò)誤碼：PUSH_00000, 錯(cuò)誤：success
2024-07-03 10:34:48.631 14509-9749  MPS:AppRegister         com.aliyun.emas.pocdemo              I  connState=2;estimatedTime=384;response{msg: success, code: PUSH_00000}
2024-07-03 10:34:48.631 14509-9749  MPS:AppRegister         com.aliyun.emas.pocdemo              D  Looping handleMessage: 1
2024-07-03 10:34:48.631 14509-14509 [MPS]                   com.aliyun.emas.pocdemo              I  errorCode:錯(cuò)誤碼：PUSH_00000, 錯(cuò)誤：success

• 確認(rèn)cloud channel初始化正常，在logcat日志中，輸入awcn關(guān)鍵字：

2024-07-03 10:36:57.464  8890-10129 EMASNAccs_NetworkSdk    com.aliyun.emas.pocdemo              I  [awcn.TnetSpdySession]  statusCode:200
2024-07-03 10:36:57.465  8890-10129 EMASNAccs_NetworkSdk    com.aliyun.emas.pocdemo              I  [awcn.TnetSpdySession]  response headers:{date=[Wed, 03 Jul 2024 02:36:57 GMT], content-length=[0], server=[Tengine/Aserver/3.0.413_20221027005707], s-accs-retcode=[SUCCESS], :status=[200], x-workerid=[360290169770599862], x-at=[ZoS4k5ejQckDADGQGBlEBBUB3347866231719988617]}
2024-07-03 10:36:57.467  8890-10129 EMASNAccs_NetworkSdk    com.aliyun.emas.pocdemo              E  [awcn.Session]|[seq:334786623.AWCN1_1] notifyStatus status:AUTH_SUCC

• 確認(rèn)deviceId獲取正常：在初始化成功后使用cloudPushService.getDeviceId()可以成功獲取deviceId。

• 如果注冊(cè)服務(wù)器連接失敗，則調(diào)用callback.onFailed()方法，并且自動(dòng)進(jìn)行重新注冊(cè)，直到onSuccess為止（重試規(guī)則會(huì)由網(wǎng)絡(luò)切換等時(shí)機(jī)自動(dòng)觸發(fā)）。在onFailed()方法中，會(huì)由相應(yīng)的錯(cuò)誤碼返回，可參考錯(cuò)誤處理。

注意事項(xiàng)

1 Android 8+適配

請(qǐng)參考Android 8.0以上設(shè)備接收不到推送通知。

2 Android 13適配

Android 13新增了POST_NOTIFICATIONS權(quán)限，推送3.8.4 SDK已經(jīng)添加了該權(quán)限，如果業(yè)務(wù)方的APP的targetSdk低于33，只需要升級(jí)至3.8.4版本即可，應(yīng)用啟動(dòng)后系統(tǒng)會(huì)自動(dòng)彈出授權(quán)框；如果targetSdk是33，則需要業(yè)務(wù)方APP在運(yùn)行時(shí)主動(dòng)申請(qǐng)POST_NOTIFICATIONS權(quán)限。

非手機(jī)場(chǎng)景說(shuō)明

在一些特定設(shè)備上，使用場(chǎng)景和手機(jī)場(chǎng)景不同，可以進(jìn)行一些特別的配置，主要分為兩類：一類指類似手機(jī)應(yīng)用，當(dāng)用戶使用時(shí)應(yīng)用才會(huì)運(yùn)行，用戶不使用時(shí)，可能會(huì)被系統(tǒng)回收，另一類是系統(tǒng)級(jí)別應(yīng)用，會(huì)長(zhǎng)時(shí)間運(yùn)行。

類手機(jī)應(yīng)用配置

這種場(chǎng)景，可以開啟channel進(jìn)程心跳，提高通道的穩(wěn)定性。

val pushInitConfig = PushInitConfig.Builder()
    .application(application)
    // 開啟channel進(jìn)程
    .disableChannelProcess(false)
    // 開啟channel進(jìn)程心跳
    .disableChannelProcessHeartbeat(false)
    .build()

PushServiceFactory.init(pushInitConfig)

val pushService = PushServiceFactory.getCloudPushService()
pushService.register(this, object : com.alibaba.sdk.android.push.CommonCallback {
    override fun onSuccess(success: String) {}
    override fun onFailed(errorCode: String, errorMessage: String) {}
})

PushInitConfig pushInitConfig = new PushInitConfig.Builder()
        .application(application)
        // 開啟channel進(jìn)程
        .disableChannelProcess(false)
        // 開啟channel進(jìn)程心跳
        .disableChannelProcessheartbeat(false)
        .build()

PushServiceFactory.init(pushInitConfig);

CloudPushService pushService = PushServiceFactory.getCloudPushService();
pushService.register(applicationContext, new CommonCallback() {
    @Override
    public void onSuccess(String response) {
        
    }
    @Override
    public void onFailed(String errorCode, String errorMessage) {
        
    }
});

如果系統(tǒng)不支持JobService（Android API版本低于21），還需要添加WAKE_LOCK權(quán)限。

<!-- 設(shè)備 Android API版本低于21 添加WAKE_LOCK權(quán)限 -->
<uses-permission android:name="android.permission.WAKE_LOCK"/>

長(zhǎng)時(shí)間運(yùn)行的系統(tǒng)應(yīng)用

此類應(yīng)用因?yàn)槭且恢边\(yùn)行的，根據(jù)系統(tǒng)性能要求，可以考慮不使用channel進(jìn)程推送通道，完全使用應(yīng)用內(nèi)推送通道。

val pushInitConfig = PushInitConfig.Builder()
    .application(application)
    // 根據(jù)情況禁止channel進(jìn)程
    .disableChannelProcess(false)
    // 禁止channel進(jìn)程心跳
    .disableChannelProcessHeartbeat(false)
    .build()

PushServiceFactory.init(pushInitConfig)

val pushService = PushServiceFactory.getCloudPushService()
pushService.register(this, object : com.alibaba.sdk.android.push.CommonCallback {
    override fun onSuccess(success: String) {}
    override fun onFailed(errorCode: String, errorMessage: String) {}
})

PushInitConfig pushsInitConfig = new PushInitConfig.Builder()
        .application(application)
        // 根據(jù)情況禁止channel進(jìn)程
        .disableChannelProcess(true)
        // 禁止channel進(jìn)程心跳
        .disableChannelProcessheartbeat(true)
        .build();
PushServiceFactory.init(pushsInitConfig);

CloudPushService pushService = PushServiceFactory.getCloudPushService();
pushService.register(applicationContext, new CommonCallback() {
    @Override
    public void onSuccess(String response) {

    }
    @Override
    public void onFailed(String errorCode, String errorMessage) {

    }
});

長(zhǎng)時(shí)間運(yùn)行的應(yīng)用，需要關(guān)注連接是否一直連接，可以注冊(cè)自己的監(jiān)聽接口，并做一定的檢查措施。

val handler = Handler()
val controlService = PushServiceFactory.getPushControlService()
controlService.setConnectionChangeListener(object : ConnectionChangeListener {
    override fun onConnect() {}
    override fun onDisconnect(code: String, msg: String) {
        val isNetworkIssue = !isNetworkConnected()
        // 過(guò)一段時(shí)間再檢查，比如30s
        handler.postDelayed(Runnable {
            if (isNetworkConnected() && !controlService.isConnected()) {
                // 如果網(wǎng)絡(luò)沒(méi)有問(wèn)題，而且連接沒(méi)有恢復(fù)
                // 此時(shí)記錄埋點(diǎn) code 和 msg 信息，一定要記錄msg信息
                recordDisconnectEvent(code, msg)
                if (isNetworkIssue) {
                    // 剛才沒(méi)有網(wǎng)絡(luò)，嘗試重連
                    controlService.reconnect()
                } else {
                    // 網(wǎng)絡(luò)沒(méi)有問(wèn)題，或者重連也不行，進(jìn)行重置，重新進(jìn)行初始化
                    controlService.reset()
                    initCloudChannel(getContext())
                }
            }
        }, 30 * 1000)
    }
})

// 示意代碼，請(qǐng)不要直接使用，請(qǐng)根據(jù)具體的業(yè)務(wù)情況使用api
final Handler handler = new Handler();
PushControlService controlService = PushServiceFactory.getPushControlService();
controlService.setConnectionChangeListener(new PushControlService.ConnectionChangeListener() {
    @Override
    public void onConnect() {

    }

    @Override
    public void onDisconnect(final String code, final String msg) {
        final boolean isNetworkIssue = !isNetworkConnected();
        // 過(guò)一段時(shí)間再檢查，比如30s
        handler.postDelayed(new Runnable() {
            @Override
            public void run() {
                if(isNetworkConnected() && !controlService.isConnected()) {
                    // 如果網(wǎng)絡(luò)沒(méi)有問(wèn)題，而且連接沒(méi)有恢復(fù)
                    // 此時(shí)記錄埋點(diǎn) code 和 msg 信息，一定要記錄msg信息
                    recordDisconnectEvent(code, msg);
                    if (isNetworkIssue) {
                        // 剛才沒(méi)有網(wǎng)絡(luò)，嘗試重連
                        controlService.reconnect();
                    } else {
                        // 網(wǎng)絡(luò)沒(méi)有問(wèn)題，或者重連也不行，進(jìn)行重置，重新進(jìn)行初始化
                        controlService.reset();
                        initCloudChannel(getContext());
                    }

                }
            }
        }, 30 * 1000);
    }
});

常見集成問(wèn)題

1. UTDID沖突，可參考：阿里云-云產(chǎn)品SDK UTDID沖突解決方案

2. 集成Android SDK后運(yùn)行App報(bào)java.lang.NoClassDefFoundError該如何解決？

3. 移動(dòng)推送 Android 端集成失敗排查文檔

4. 推送SDK在初始化時(shí)報(bào)錯(cuò)

5. Android SDK初始化時(shí)出現(xiàn)1105和10207報(bào)錯(cuò)怎么解決？

6. 在Activity中初始化推送SDK，無(wú)法接收到推送通知