文档

Android SDK配置(V3.0.0及以上版本)

更新时间:

本章节介绍移动推送Android SDK V3.0.0及以上版本的集成操作。

前提条件

样例代码

移动推送Android SDK 全新Demo工程请参见:移动推送Android Demo

新Demo工程使用Kotlin + MVVM开发,界面更美观,功能更丰富,开发者可参考Demo更快速了解移动推送Android SDK如何使用。

集成步骤

SDK的集成有两种方式,分别是:

  • Maven仓库

  • Android Studio本地集成

说明

建议开发者采用Maven仓库方式进行集成,Maven库快速集成,配置简单,不容易出问题,后续更新方便

方式一:Maven仓库

配置SDK的Maven仓库地址

重要

  • 使用移动推送Android SDK 3.2.0或以上版本,需同时将辅助通道SDK版本升级到3.2.0或以上版本。

7.0以下版本

打开项目根目录的build.gradle文件,在allprojectsrepositories中添加Maven仓库地址

allprojects {
  repositories {
    jcenter()
    google()
    maven {
      url 'http://maven.aliyun.com/nexus/content/repositories/releases/'
    }
    // 配置HMS Core SDK的Maven仓地址。
    maven {
      url 'https://developer.huawei.com/repo/'
    }
  }
}

7.0以上版本

打开项目根目录的settings.gradle文件,在dependencyResolutionManagementrepositores中添加Maven仓库地址

dependencyResolutionManagement {
  repositories {
    google()
    mavenCentral()
    mavenLocal()
    // 配置HMS Core SDK的Maven仓地址。
    maven {url 'https://developer.huawei.com/repo/'}
    maven {
      url 'http://maven.aliyun.com/nexus/content/repositories/releases/'
      name 'aliyun'//一定要添加这个配置
      allowInsecureProtocol = true
    }
  }
}

添加SDK依赖

打开应用模块下的build.gradle文件,在dependencies中添加SDK依赖

dependencies {
    ......
    implementation 'com.aliyun.ams:alicloud-android-push:3.x.x'
    ......
}
重要

请使用固定版本号集成,不要使用动态版本号。错误示例:3.+或者3.2.+。

NDK配置

android代码段中配置应用包名和NDK

android {
    ......
    defaultConfig {
        applicationId "com.xxx.xxx" //包名
        ......
        ndk {
            //选择要添加的对应cpu类型的.so库。此处仅为示意,推送支持所有主流类型,请根据设备硬件选择
            abiFilters 'armeabi', 'x86'
        }
        ......
    }
    ......
}

错误处理:如果在添加以上abFilter配置后Android Studio出现以下提示:

NDK integration is deprecated in the current plugin. Consider trying the new experimental plugin.

则在Project根目录的gradle.properties文件中添加:

android.useDeprecatedNdk=true

方式二:Android Studio手动集成

解压在控制台下载的SDK包,可将所有SDK拷贝到libs目录下,同时在build.gradle文件中进行如下配置:

说明

以下代码为示例代码,请参考Android SDK版本说明使用最新SDK依赖版本。

  android {
      ...
      repositories {
          flatDir {
              dirs 'libs' //this way we can find the .aar file in libs folder
          }
      }
      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

AppKey、AppSecret配置

说明

  • 使用统一接入无需进行此配置。

  • 为避免在日志中泄漏参数appkey/appsecret或App运行过程中产生的数据,建议线上版本关闭SDK调试日志。

  • 由于所有用户使用统一的SDK接入,在接入过程中需要在代码中设置appkey/appsecret参数,而此类参数与计量计费密切相关,为防止恶意反编译获取参数造成信息泄漏,建议您开启混淆,并进行App加固后再发布上线。

在AndroidManifest文件中设置AppKey、AppSecret:

  <application android:name="*****">
      <!-- 请填写你自己的- appKey -->
      <meta-data android:name="com.alibaba.app.appkey" android:value="*****"/> 
      <!-- 请填写你自己的appSecret -->
      <meta-data android:name="com.alibaba.app.appsecret" android:value="****"/> 
  </application>

com.alibaba.app.appkeycom.alibaba.app.appsecret为您在EMAS平台上的App对应信息。在EMAS控制台的应用管理中或在下载的配置文件中查看AppKey和AppSecret。

AppKey和AppSecret请务必写在application标签下,否则SDK会报找不到AppKey的错误。

说明

如果您是百川云推送用户,不能直接使用百川平台的AppKey和AppSecret,需要登录EMAS控制台,登录账号为您的百川平台账号,并使用阿里EMAS平台的AppKey和AppSecret。

消息接收Receiver配置

创建消息接收Receiver,继承自com.alibaba.sdk.android.push.MessageReceiver,并在对应回调中添加业务处理逻辑,可参考以下代码:

public class MyMessageReceiver extends MessageReceiver {
    @Override
    public void onNotification(Context context, String title, String summary, Map<String, String> extraMap) {
        // TODO处理推送通知
        Log.e("MyMessageReceiver", "Receive notification, title: " + title + ", summary: " + summary + ", extraMap: " + extraMap);
    }
    @Override
    public void onMessage(Context context, CPushMessage cPushMessage) {
            Log.e("MyMessageReceiver", "onMessage, messageId: " + cPushMessage.getMessageId() + ", title: " + cPushMessage.getTitle() + ", content:" + cPushMessage.getContent());
    }
    @Override
    public void onNotificationOpened(Context context, String title, String summary, String extraMap) {
        Log.e("MyMessageReceiver", "onNotificationOpened, title: " + title + ", summary: " + summary + ", extraMap:" + extraMap);
    }
    @Override
    protected void onNotificationClickedWithNoAction(Context context, String title, String summary, String extraMap) {
        Log.e("MyMessageReceiver", "onNotificationClickedWithNoAction, title: " + title + ", summary: " + summary + ", extraMap:" + extraMap);
    }
    @Override
    protected void onNotificationReceivedInApp(Context context, String title, String summary, Map<String, String> extraMap, int openType, String openActivity, String openUrl) {
        Log.e("MyMessageReceiver", "onNotificationReceivedInApp, title: " + title + ", summary: " + summary + ", extraMap:" + extraMap + ", openType:" + openType + ", openActivity:" + openActivity + ", openUrl:" + openUrl);
    }
    @Override
    protected void onNotificationRemoved(Context context, String messageId) {
        Log.e("MyMessageReceiver", "onNotificationRemoved");
    }
}

将该receiver添加到AndroidManifest.xml文件中:

<!-- 消息接收监听器 (用户可自主扩展) -->
<receiver
    android:name=".MyMessageReceiver"
    android:exported="false"> <!-- 为保证receiver安全,建议设置不可导出,如需对其他应用开放可通过android:permission进行限制 -->
    <intent-filter>
        <action android:name="com.alibaba.push2.action.NOTIFICATION_OPENED" />
    </intent-filter>
    <intent-filter>
        <action android:name="com.alibaba.push2.action.NOTIFICATION_REMOVED" />
    </intent-filter>
    <intent-filter>
        <action android:name="com.alibaba.sdk.android.push.RECEIVE" />
    </intent-filter>
</receiver>
重要

旧版本 SDK集成说明:

如果是从V2.3.7及以下版本升级到V3.0.0及以上版本的用户,需将<action android:name="org.agoo.android.intent.action.RECEIVE" />改为<action android:name="com.alibaba.sdk.android.push.RECEIVE" />,否则会接收不到推送。

  1. Android 8+适配

    请参见Android 8.0以上设备接收不到推送通知

  2. Android 13适配

    Android 13新增了POST_NOTIFICATIONS权限,推送3.8.4 SDK已经添加了该权限,如果业务方的APP的targetSdk低于33,只需要升级至3.8.4版本即可,应用启动后系统会自动弹出授权框;如果targetSdk是33,则需要业务方APP在运行时主动申请POST_NOTIFICATIONS权限

混淆配置

如果您的项目中使用Proguard等工具做了代码混淆,请保留以下配置:

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

SDK初始化配置

首先通过PushServiceFactory获取到CloudPushService,然后调用register()初始化并注册推送通道,并确保在Application上下文中进行初始化工作。

请参照以下代码进行初始化:

import android.app.Application;
import android.content.Context;
import android.util.Log;
import com.alibaba.sdk.android.push.CloudPushService;
import com.alibaba.sdk.android.push.CommonCallback;
import com.alibaba.sdk.android.push.noonesdk.PushServiceFactory;
public class MainApplication extends Application {
    private static final String TAG = "Init";
    @Override
    public void onCreate() {
        super.onCreate();
        initCloudChannel(this);
    }
    /**
     * 初始化云推送通道
     * @param applicationContext
     */
    private void initCloudChannel(Context applicationContext) {
        PushServiceFactory.init(applicationContext);
        CloudPushService pushService = PushServiceFactory.getCloudPushService();
      	//仅适用于Debug包,正式包不需要此行
        pushService.setLogLevel(CloudPushService.LOG_DEBUG);           
        pushService.register(applicationContext, new CommonCallback() {
            @Override
            public void onSuccess(String response) {
                Log.d(TAG, "init cloudchannel success");
            }
            @Override
            public void onFailed(String errorCode, String errorMessage) {
                Log.d(TAG, "init cloudchannel failed -- errorcode:" + errorCode + " -- errorMessage:" + errorMessage);
            }
        });
    }
}
重要

PushServiceFactory.init必须在Application主线程中,不能放到Activity中执行,也不能异步初始化。移动推送在初始化过程中将启动后台进程channel,必须保证应用进程和channel进程都执行到PushServiceFactory.init。详情请参见Android SDK中CloudPushService应该怎样初始化?

初始化成功验证

启动正常确认方法:

  • 回调方法callback.onSuccess()被调用。以上文中接入代码为例,logcat将会打印如下日志:

    11-24 12:55:51.096  15235-15535/com.alibaba.xxxx D/YourApp﹕ init cloudchannel success
  • 确认cloud channel初始化正常,在logcat日志中,输入awcn关键字:

    11-24 12:53:51.036  15235-15556/com.alibaba.xxxx E/awcn﹕ |[seq:AWCN1_1] AUTH httpStatusCode: 200
    11-24 12:53:51.036  15235-15556/com.alibaba.xxxx E/awcn﹕ |[seq:AWCN1_1] status:AUTH_SUCC
  • 确认deviceId获取正常:在初始化成功后使用cloudPushService.getDeviceId()可以成功获取deviceId。

  • 如果注册服务器连接失败,则调用callback.onFailed()方法,并且自动进行重新注册,直到onSuccess为止(重试规则会由网络切换等时机自动触发)。在onFailed()方法中,会由相应的错误码返回,可参考错误处理

    说明

    市场上部分手机,对Log显示做了限制,比如华为手机,屏蔽了Debug和Verbose级别的日志;建议开发时使用Info级别日志。日志级别设置请参考基本设置相关接口中的“设置日志等级”。

权限合规说明

移动推送使用的权限用途说明

权限

业务用途

INTERNET

用于连接推送服务,提供推送功能。

ACCESS_NETWORK_STATE

当推送异常时,判断网络状态;获取设备IP,用于网络环境判断,实现推送服务IP调度功能。

GET_TASKS

REORDER_TASKS

推送通知指定打开方式为打开应用时,且当用户点击通知时后台存在运行中的应用时,将后台应用移到前台,避免重复启动应用。

POST_NOTIFICATIONS

Android 13上新增的通知权限

以上是移动推送SDK的权限用途,可以在应用的隐私政策中进行说明,统一告知用户。

如何在用户签署隐私政策之前,避免获取用户敏感信息?

  1. 目前最新版本,SDK内部已经在调用相关API之前,判断了相关权限是否授予,如果未授权,不调用,走默认的逻辑。

  2. 我们对SDK初始化进行了调整,初始化主要分为两个API调用,一个在启动时调用,另一个可以延迟到用户签署隐私政策之后调用。

    • PushServiceFactory.init(applicationContext); :必须在Application的onCreate中执行,不会获取用户信息。

    • CloudPushService的 void register(Context context, CommonCallback callback);:可以在用户签署隐私政策之后调用。

    参考代码:

    public class MyApplication extends Application {
    
        @Override
        public void onCreate() {
            super.onCreate();
            PushServiceFactory.init(this);
    
            // 获取隐私政策签署状态
            boolean sign = false;
    
            if(sign) {
                registerPush();
            } else {
                // 没签,等签署之后再调用registerPush()
            }
        }
    
    
        /**
         * 建立推送通道
         */
        public void registerPush() {
            CloudPushService pushService = PushServiceFactory.getCloudPushService();
            pushService.register(applicationContext, new CommonCallback() {
                @Override
                public void onSuccess(String response) {}
    
                @Override
                public void onFailed(String errorCode, String errorMessage) {}
            });
        }
    }

SDK延迟初始化说明

为了尽量减少对应用的启动速度影响,我们调整了SDK的API,以便于应用可以将部分逻辑延迟执行,减少对应用启动速度的影响。

必须在Application onCreate中执行的逻辑

public class PushServiceFactory {
   /**
    * 初始化推送的变量和基本参数
    * @param appContext
    */
   public static void init(Context appContext) {}
}

此API用于初始化一些推送参数,没有启动推送逻辑,必须在Application onCreate中执行。

可以延迟执行的逻辑

/**
* PushSDK对外API
*/
public interface CloudPushService {
   /**
    * 初始化用户的SDK,将应用关联到云通道
    */
   void register(Context context, CommonCallback callback);
}

此API用于建立推送连接,可以根据业务需要延迟执行。

非手机场景说明

在一些特定设备上,使用场景和手机场景不同,可以进行一些特别的配置,主要分为两类:一类指类似手机应用,当用户使用时应用才会运行,用户不使用时,可能会被系统回收,另一类是系统级别应用,会长时间运行。

类手机应用配置

这种场景,可以开启channel进程心跳,提高通道的稳定性。

    /**
     * 初始化云推送通道
     * @param applicationContext
     */
    private void initCloudChannel(Context applicationContext) {
        PushInitConfig.Builder builder = new PushInitConfig.Builder()
                .application(context);
        // 开启channel进程
        builder.disableChannelProcess(false);
        // 开启channel进程心跳
        builder.disableChannelProcessheartbeat(false);
        PushInitConfig config = builder.build();
        PushServiceFactory.init(config);

        CloudPushService pushService = PushServiceFactory.getCloudPushService();
        pushService.setLogLevel(CloudPushService.LOG_DEBUG);   //仅适用于Debug包,正式包不需要此行        
        pushService.register(applicationContext, new CommonCallback() {
            @Override
            public void onSuccess(String response) {
                Log.d(TAG, "init cloudchannel success");
            }
            @Override
            public void onFailed(String errorCode, String errorMessage) {
                Log.d(TAG, "init cloudchannel failed -- errorcode:" + errorCode + " -- errorMessage:" + errorMessage);
            }
        });
    }

如果系统不支持JobService(Android API版本低于21),还需要添加WAKE_LOCK权限。

<!-- 设备 Android API版本低于21 添加WAKE_LOCK权限 -->
<uses-permission android:name="android.permission.WAKE_LOCK"/>

长时间运行的系统应用

此类应用因为是一直运行的,根据系统性能要求,可以考虑不使用channel进程推送通道,完全使用应用内推送通道。

    /**
     * 初始化云推送通道
     * @param applicationContext
     */
    private void initCloudChannel(Context applicationContext) {
        PushInitConfig.Builder builder = new PushInitConfig.Builder()
                .application(context);
        // 根据情况禁止channel进程
        builder.disableChannelProcess(true);
        // 禁止channel进程心跳
        builder.disableChannelProcessheartbeat(true);
        PushInitConfig config = builder.build();
        PushServiceFactory.init(config);

        CloudPushService pushService = PushServiceFactory.getCloudPushService();
        pushService.setLogLevel(CloudPushService.LOG_DEBUG);   //仅适用于Debug包,正式包不需要此行        
        pushService.register(applicationContext, new CommonCallback() {
            @Override
            public void onSuccess(String response) {
                Log.d(TAG, "init cloudchannel success");
            }
            @Override
            public void onFailed(String errorCode, String errorMessage) {
                Log.d(TAG, "init cloudchannel failed -- errorcode:" + errorCode + " -- errorMessage:" + errorMessage);
            }
        });
    }

长时间运行的应用,需要关注连接是否一直连接,可以注册自己的监听接口,并做一定的检查措施。

  
                // 示意代码,请不要直接使用,请根据具体的业务情况使用api
                final Handler handler = new Handler();
                controlService.setConnectionChangeListener(new PushControlService.ConnectionChangeListener() {
                    @Override
                    public void onConnect() {

                    }

                    @Override
                    public void onDisconnect(final String code, final String msg) {
                        final boolean isNetworkIssue = !isNetworkConnected();
                        // 过一段时间再检查,比如30s
                        handler.postDelayed(new Runnable() {
                            @Override
                            public void run() {
                                if(isNetworkConnected() && !controlService.isConnected()) {
                                    // 如果网络没有问题,而且连接没有恢复
                                    // 此时记录埋点 code 和 msg 信息,一定要记录msg信息
                                    recordDisconnectEvent(code, msg);
                                    if (isNetworkIssue) {
                                        // 刚才没有网络,尝试重连
                                        controlService.reconnect();
                                    } else {
                                        // 网络没有问题,或者重连也不行,进行重置,重新进行初始化
                                        controlService.reset();
                                        initCloudChannel(getContext());
                                    }

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

常见集成问题

  1. UTDID冲突,可参考:阿里云-移动云产品SDK UTDID冲突解决方案

  2. 集成Android SDK后运行App报java.lang.NoClassDefFoundError该如何解决?

  3. Android端SDK集成失败排查

  4. 初推送SDK在初始化时报错

  5. Android SDK初始化时报1105、10207报错

  6. 在Activity中初始化推送SDK,无法接收到推送通知

  • 本页导读 (0)
文档反馈