Android SDK 开发文档

概述

Android SDK是为Android平台开发者接入“云推送”服务而提供开发者工具包,开发者需要在应用中正确集成Android SDK才能使安装该应用的Android设备接收到云推送服务端发送的各类消息。

关于如何开通云推送服务,请参考 接入指南,在开通推送服务后,可以通过快速开始一节内容了解如何快速构建一个Android应用并接收消息。

快速开始

下载最新的Android SDK压缩包并解压,使用Eclipse或者Android Studio,导入Android工程示例(Demo)。此时会看到Demo工程中有错误,把工程编码改为UTF-8,再打开左侧目录树,错误存在于PushDemo工程下src文件夹中,com.baidu.push.example包路径下的PushDemoActivity.java文件中。

报错的这一行特别提醒开发者,在特定位置上一定要填上您获得的API Key,否则会绑定失效,无法接收到推送的消息。

首先需要把错误注释掉。

然后将AndroidManifest.xml 122行 “api_key”修改为您的API Key并保存,如下图所示。

右键点击PushDemo工程,选择Run As --> Android Application,运行程序。

选中您已连接的手机设备或Android虚拟机,开始运行Demo。

开发指南

集成SDK

下载最新的Android SDK压缩包并解压,在新建工程或已有工程中增加百度云推送功能,如果您使用的是Demo示例,请直接跳到 推送注意:如果您的Android工程使用的是Android API level 21及以上的版本,您的通知图标背景必须是透明的,否则在Android5.0及以上的机器上通知图标可能会变成白色的方块。

导入云推送jar包和so文件:

将解压后的libs文件夹中所有文件拷贝到您的工程的libs文件夹中。如果您的工程中没有其他的.so文件,建议只拷贝armeabi文件夹。如果您的工程中还使用了其他的.so文件,只需要拷贝对应目录下的.so文件即可。如果你使用的Android开发环境是Android Stutio,在工程中“src/main”目录中新建名为jniLibs的目录,将libs文件夹中文件拷贝到“jniLibs”目录内。 如下图所示

配置AndroidManifest文件:

在当前工程的AndroidManifest.xml文件中,添加权限和声明信息(请勿修改):


<!-- Push service 运行需要的权限 -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<uses-permission android:name="android.permission.WRITE_SETTINGS" />
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.DISABLE_KEYGUARD" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<!-- 富媒体需要声明的权限 -->
<uses-permission android:name="android.permission.ACCESS_DOWNLOAD_MANAGER"/>
<uses-permission android:name="android.permission.DOWNLOAD_WITHOUT_NOTIFICATION" />
<uses-permission android:name="android.permission.EXPAND_STATUS_BAR" />

<!-- 适配Android N系统必需的ContentProvider写权限声明,写权限包含应用包名-->
<uses-permission android:name="baidu.push.permission.WRITE_PUSHINFOPROVIDER.YourPackageName" />
<permission
        android:name="baidu.push.permission.WRITE_PUSHINFOPROVIDER.YourPackageName"
        android:protectionLevel="signature">
</permission>

<!-- push service start -->
<!-- 用于接收系统消息以保证PushService正常运行 -->
<receiver android:name="com.baidu.android.pushservice.PushServiceReceiver"
    android:process=":bdservice_v1" >
    <intent-filter>
        <action android:name="android.intent.action.BOOT_COMPLETED" />
        <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
        <action android:name="com.baidu.android.pushservice.action.notification.SHOW" />
        <action android:name="com.baidu.android.pushservice.action.media.CLICK" />
        <!-- 以下四项为可选的action声明,可大大提高service存活率和消息到达速度 -->
        <action android:name="android.intent.action.MEDIA_MOUNTED" />
        <action android:name="android.intent.action.USER_PRESENT" />
        <action android:name="android.intent.action.ACTION_POWER_CONNECTED" />
        <action android:name="android.intent.action.ACTION_POWER_DISCONNECTED" />
    </intent-filter>
</receiver>
<!-- Push服务接收客户端发送的各种请求-->
<receiver android:name="com.baidu.android.pushservice.RegistrationReceiver"
    android:process=":bdservice_v1" >
    <intent-filter>
        <action android:name="com.baidu.android.pushservice.action.METHOD" />
        <action android:name="com.baidu.android.pushservice.action.BIND_SYNC" />
    </intent-filter>
    <intent-filter>
        <action android:name="android.intent.action.PACKAGE_REMOVED" />
        <data android:scheme="package" />
    </intent-filter>
</receiver>
<service android:name="com.baidu.android.pushservice.PushService" android:exported="true"
    android:process=":bdservice_v1" >
    <intent-filter >
            <action android:name="com.baidu.android.pushservice.action.PUSH_SERVICE" />
    </intent-filter>
</service>

<!-- 4.4版本新增的CommandService声明,提升小米和魅族手机上的实际推送到达率 -->
<service android:name="com.baidu.android.pushservice.CommandService"
    android:exported="true" />

<!-- 适配Android N系统必需的ContentProvider声明,写权限包含应用包名-->
<provider
    android:name="com.baidu.android.pushservice.PushInfoProvider"
    android:authorities="YourPackageName.bdpush"
    android:writePermission="baidu.push.permission.WRITE_PUSHINFOPROVIDER.YourPackageName"
    android:protectionLevel = "signature"
    android:exported="true" />

<!-- push结束 -->

配置Manifest文件之后,请将YourPackageName替换成用户自己的包名。

启动云推送

在当前工程的主Activity的onCreate函数中,添加以下代码:

PushManager.startWork(getApplicationContext(),PushConstants.LOGIN_TYPE_API_KEY,"api_key")

其中的“API Key“需要手动修改为指定应用的API Key。

自定义回调类

在当前工程中新建一个类,右键点击选择new --> Class,填写接收云推送回调信息和推送到达信息的类的类名,并点击Finish创建该类文件(本例中使用PushTestReceiver)。

打开新创建的类,继承PushMessageReceiver,此时类名飘红,移动到类名上,点击 Add unimplemented methods,重载所有的回调函数,并打印对应信息,如图所示:

在当前工程的AndroidManifest.xml文件中,添加自定义Receiver信息如下:


<!-- 此处Receiver名字修改为当前包名路径 -->
<receiver android:name="YourPackageName.PushTestReceiver">
    <intent-filter>
        <!-- 接收push消息 -->
        <action android:name="com.baidu.android.pushservice.action.MESSAGE" />
        <!-- 接收bind、setTags等method的返回结果-->
        <action android:name="com.baidu.android.pushservice.action.RECEIVE" />
        <!-- 接收通知点击事件,和通知自定义内容 -->
        <action android:name="com.baidu.android.pushservice.action.notification.CLICK" />
    </intent-filter>
</receiver>

运行App

右键点击当前工程,选择Run As --> Android Application,选中已连接的设备或Android虚拟机,运行该程序。如果在logcat中的回调函数中的errorCode为0,说明已经绑定成功,并返回userid和channelid,我们就可以在云控制台推送通知和透传消息到该app了。

处理推送消息

推送

在集成SDK后,可以通过以下两种方式推送消息。

  1. 通过控制台推送消息。参见:管理控制台

  2. 通过服务端SDK推送消息,目前服务端提供 JavaPHPPython三种语言的SDK,其它语言可以通过包装RestAPI使用云推送服务,具体可参见 SDK开发指南

接收通知消息

当设备接收到通知消息后,查看手机的通知栏,可以看到通知栏内的新通知展示。如图:

通知到达时,当通知被用户点击时,会回调onNotificationClicked函数。

推送透传消息

当设备接收到透传消息时,消息不会在通知栏展示,只是静默回调开发者自定义Receiver中的onMessage函数。手机收到消息后不会有任何现象,因为透传消息对用户完全透明,用户无法感知,便于开发者在不影响用户的情况下对app进行操作。开发者可以通过log内容和自定义的回调函数onMessage中打印该内容,确认消息到达,并执行开发者指定操作。

错误码说明

error_code 描述
0 绑定成功
10001 当前网络不可用,请检查网络
10002 服务不可用,连接server失败
10003 服务不可用,503错误
10101 应用集成方式错误,请检查各项声明和权限
20001 未知错误
30600 服务内部错误
30601 非法函数请求,请检查您的请求内容
30602 请求参数错误,请检查您的参数
30603 非法构造请求,服务端验证失败
30605 请求的数据在服务端不存在
30608 绑定关系不存在或未找到
30609 一个百度账户绑定设备超出个数限制(多台设备登录同一个百度账户)
30612 百度账户绑定应用时被禁止,需要白名单授权

混淆说明

如果需要混淆app,请在混淆文件(一般默认为Android工程下proguard-project.txt或者proguard.cfg)中添加以下说明(pushservice-VERSION.jar为集成的jar包名字,VERSION为版本名称),防止SDK内容被二次混淆,无法收到消息。

     -libraryjars libs/pushservice-VERSION.jar
     -dontwarn com.baidu.**
     -keep class com.baidu.**{*; }

API

本SDK中有四个重要的开放类,分别为:PushManager、PushSettings、BasicPushNotificationBuilder和CustomPushNotificationBuilder,另外还有常量类PushConstants和回调接收类PushMessageReceiver。
描述
PushManager 提供了所有使用Push服务的静态方法
PushSettings 提供了端上Push服务的配置静态方法
BasicPushNotificationBuilder 用于定制 Android Notification 里的基础样式和行为
CustomPushNotificationBuilder 用于定制 Android Notification 里的 sound / flags / icon,以及通知栏的layout、图标
和状态栏图标
PushConsants SDK对外的常量定义
PushMessageReceiver 自定义接收push消息和通知实现的直接父类

接口与方法

Push Android SDK目前支持以下接口:

分类 功能 API函数原型
Push服务接口 提供Push服务 startWork, stopWork, resumeWork
Tag管理接口 Tag的创建与删除 setTags, delTags, onListTags
通知管理接口 自定义通知样式 CustomPushNotificationBuilder, BasicPushNotificationBuilder,
setNotificationFlags, setNotificationDefaults, setStatusbarIcon,
setLayoutDrawable, setNotificationSound, setNotificationBuilder
设置接口 Push服务设置 enableDebugMode
LBS推送接口 打开或关闭精确LBS推送 enableLbs, disableLbs
异步消息处理接口 Push消息处理receiver onBind, onMessage, onNotificationClicked, onNotificationArrived, onSetTags, onDelTags,
onListTags, onUnbind

Push服务初始化及绑定-- startWork

函数原型
public static void startWork(Context context, int loginType, String loginValue);
功能

PushManager类定义的静态方法,完成Push服务的初始化,并且自动完成bind工作。

参数
  • context:当前执行Context
  • loginType:绑定认证方式(无账号认证方式PushConstants.LOGIN_TYPE_API_KEY
  • loginValue:应用的API Key
返回结果

通过自定义的Receiver类里onBind方法返回结果,详见 onBind

注意:不要在Application的onCreate里去做startWork的操作。

停止和恢复Push服务-- stopWork、resumeWork

函数原型
public static void stopWork(Context context);
功能

PushManager类定义的静态方法,停止本应用Push服务进程,并且完成unbind工作。startWork和resumeWork都会重新开启本应用Push功能。

参数
  • context:当前执行Context
返回结果

通过自定义的Receiver类里onUnbind方法返回结果,详见 onUnbind

函数原型
public static void resumeWork(Context context);
功能

PushManager类定义的静态方法,恢复本应用Push服务,并且再次完成bind工作。

参数
  • context:当前执行Context
返回结果

通过自定义的Receiver类里onBind方法返回结果,详见 onBind

查询push是否被停止的接口-- isPushEnabled

函数原型
public static boolean isPushEnabled(Context context);
功能

PushManager类定义的静态方法,查询push是否已经被停止。

参数
  • context:当前执行Context
返回结果
  • true:已开启push服务
  • false:未开启push服务

设置免打扰时段-- setNoDisturbMode

函数原型
PushManager.setNoDisturbMode(Context context, int startHour, int startMinute, int endHour, int endMinute);
功能

PushManager类定义的静态方法,设置免打扰模式的具体时段,该时间内处于免打扰模式,通知到达时去除通知的提示音、振动以及提示灯闪烁。

注意:如果开始时间小于结束时间,免打扰时段为当天的起始时间到结束时间;如果开始时间大于结束时间,免打扰时段为第一天起始时间到第二天结束时间;如果开始时间和结束时间的设置均为00:00时,取消免打扰时段功能。

参数
  • context:当前执行Context
  • startHour,startMinute:起始时间,24小时制,取值范围0~23,0~59
  • endHour,endMinute:结束时间,24小时制,取值范围0~23,0~59
返回结果

设置Tag-- setTags

函数原型
public static void setTags(Context context, List tags);
功能

PushManager类定义的静态方法,用于设置标签;成功设置后,可以从管理控制台或您的服务后台,向指定的设置了该tag的一群用户进行推送。

注意:tag设置的前提是已绑定的端,也就是应用有运行过startWork或bind,且在onBind回调中返回成功。

返回结果

通过自定义的Receiver类里onSetTags方法返回结果,详见 onSetTags

删除Tag-- delTags

函数原型
public static void delTags(Context context, List tags);
功能

PushManager类定义的静态方法,用于删除标签。

返回结果

通过自定义的Receiver类里onDelTags方法返回结果,详见 onDelTags

列举Tag-- listTags

函数原型
public static void listTags(Context  context);
功能

PushManager类定义的静态方法,用于列出本机绑定的标签。

返回结果

通过自定义的Receiver类里onListTags方法返回结果,详见 onListTags

设置通知的Builder -- setNotificationBuilder

函数原型
public static void setNotificationBuilder(Context context, int id, PushNotificationBuilder notificationBuilder);
功能

PushManager类定义的静态方法,设置通知栏样式,并为样式指定编号。在管理控制台或您的服务后台中,您可以指定相应的编号,让客户端显示预先设定好的样式。

参数
  • context :android app运行上下文
  • id :notificationBuilder编号,开发者自己维护
  • notificationBuilder :通知栏构建类

设置默认的通知Builder-- setDefaultNotificationBuilder

函数原型
public static void setDefaultNotificationBuilder(Context context, PushNotificationBuilder notificationBuilder);
功能

PushManager类定义的静态方法,设置默认的通知栏样式;如果推送通知时不指定id的样式,都将显示该默认样式。

参数
  • Context :android app运行上下文
  • notificationBuilder :通知栏构建类

设置富媒体通知的Builder-- setMediaNotificationBuilder

函数原型
public static void setMediaNotificationBuilder(Context context, PushNotificationBuilder notificationBuilder);
功能

PushManager类定义的静态方法,为富媒体通知设置样式;用法和自定义通知样式相似。

自定义通知Builder-- BasicPushNotificationBuilder

函数原型
BasicPushNotificationBuilder();
功能

自定义通知状态栏构建类构造函数(定制通知栏基础样式) 。

自定义通知Builder-- CustomPushNotificationBuilder

函数原型
CustomPushNotificationBuilder(layoutId, layoutIconId, layoutTitleId, layoutTextId);
功能

自定义通知状态栏构建类构造函数(定制通知栏基础样式及layout)。

参数
  • layoutId :自定义layout资源id
  • layoutIconId :自定义layout中显示icon 的id
  • layoutTitleId :自定义layout中显示标题的id
  • layoutTextId :自定义layout中显示内容的id

设置通知flags-- setNotificationFlags

函数原型
public void setNotificationFlags (int flags);
功能

基类PushNotificationBuilder定义的方法,定制 Android Notification 里的flags。

参数
  • flags :Android Notification flags

设置通知defaults-- setNotificationDefaults

函数原型
public void setNotificationDefaults (int defaults);
功能

基类PushNotificationBuilder定义的方法,定制 Android Notification 里的defaults。

参数
  • defaults :Android Notification defaults

设置通知状态栏icon-- setStatusbarIcon

函数原型
public void setStatusbarIcon (int icon);
功能

基类PushNotificationBuilder类定义的方法,定制 Android Notification通知状态栏的icon图标。

参数
  • icon :图标资源id

设置通知样式图片-- setLayoutDrawable

函数原型
public void setLayoutDrawable(int drawableId);
功能

CustomPushNotificationBuilder类定义的方法,定制自定义layout中显示的图片。

参数

drawableId :图标资源id

设置通知样式声音-- setNotificationSound

函数原型
public void setNotificationSound(String soundId);
功能

CustomPushNotificationBuilder类定义的方法,自定义推送的声音。

参数

soundId :声音资源路径

开启调试模式-- enableDebugMode

函数原型
public static void enableDebugMode(boolean debugEnabled);
功能

PushSettings类定义的方法,开启调试模式,会输出调试Log。

注意:发布应用时,请不要开启调试模式,否则会降低Push性能。

参数
  • debugEnabled :true打开调试模式,false关闭调试模式。

开启精确LBS推送模式-- enableLbs

函数原型
public static void enableLbs(Context context);
功能

PushManager类定义的方法,开启精确LBS推送模式,覆盖最近半小时内在指定区域出现过的终端。

参数
  • Context :android app运行上下文

关闭精确LBS推送模式-- disableLbs

函数原型
public static void disableLbs(Context context);
功能

PushManager类定义的方法,关闭精确LBS推送模式,关闭后,服务端将无法有效发送基于地理位置的定向推送。

参数
  • Context :android app运行上下文

获取绑定请求的结果-- onBind

函数原型
public void onBind(Context context, int errorCode, String appid, String userId, String channelId, String requestId);
功能

PushMessageReceiver的抽象方法,把receiver类继承PushMessageReceiver可以使用。调用PushManager.startWork后,sdk将对push server发起绑定请求,这个过程是异步的。绑定请求的结果通过onBind返回。 如果您需要用单播推送,需要把这里获取的channel id上传到应用server中,再调用server接口用channel id给单个手机或者用户推送。

参数
  • context BroadcastReceiver的执行Context
  • errorCode 绑定接口返回值,0 - 成功
  • appid 应用id,errorCode非0时为null
  • userId 应用user id,errorCode非0时为null
  • channelId 应用channel id,errorCode非0时为null
  • requestId 向服务端发起的请求id,在追查问题时有用

接收透传消息的函数-- onMessage

函数原型
public void onMessage(Context context, String message, String customContentString);
功能

PushMessageReceiver的抽象方法,把receiver类继承PushMessageReceiver可以使用。接收透传消息。

参数
  • context 上下文
  • message 推送的消息
  • customContentString 自定义内容,为空或者json字符串

接收通知点击的函数-- onNotificationClicked

函数原型
public void onNotificationClicked(Context context, String title, String description, String customContentString)
功能

PushMessageReceiver的抽象方法,把receiver类继承PushMessageReceiver可以使用。接收通知点击的函数。

参数
  • context 上下文
  • title 推送的通知的标题
  • description 推送的通知的描述
  • customContentString 自定义内容,为空或者json字符串

接收通知到达的函数-- onNotificationArrived

函数原型
public void onNotificationArrived(Context context, String title, String description, String customContentString)
功能

PushMessageReceiver的抽象方法,把receiver类继承PushMessageReceiver可以使用。接收通知到达的函数。

参数
  • context 上下文
  • title 推送的通知的标题
  • description 推送的通知的描述
  • customContentString 自定义内容,为空或者json字符串

setTags的回调函数-- onSetTags

函数原型
public void onSetTags(Context context, int errorCode, List sucessTags, List failTags, String requestId);
功能

PushMessageReceiver的抽象方法,把receiver类继承PushMessageReceiver可以使用。setTags() 的回调函数。

参数
  • context 上下文
  • errorCode 错误码,0表示某些tag已经设置成功,非0表示所有tag的设置均失败
  • successTags 设置成功的tag
  • failTags 设置失败的tag
  • requestId 分配给对云推送的请求的id

delTags的回调函数-- onDelTags

函数原型
public void onDelTags(Context context, int errorCode, List sucessTags, List failTags, String requestId)
功能

PushMessageReceiver的抽象方法,把receiver类继承PushMessageReceiver可以使用。delTags() 的回调函数。

参数
  • context 上下文
  • errorCode 错误码。0表示某些tag已经删除成功;非0表示所有tag均删除失败
  • successTags 成功删除的tag
  • failTags 删除失败的tag
  • requestId 分配给对云推送的请求的id

listTags的回调函数-- onListTags

函数原型
public void onListTags(Context context, int errorCode, List tags, String requestId);
功能

PushMessageReceiver的抽象方法,把receiver类继承PushMessageReceiver可以使用。listTags() 的回调函数。

参数
  • context 上下文
  • errorCode 错误码。0表示列举tag成功;非0表示失败
  • tags 当前应用设置的所有tag
  • requestId 分配给对云推送的请求的id

stopWork的回调函数-- onUnbind

函数原型
public void onUnbind(Context context, int errorCode, String requestId);
功能

PushMessageReceiver的抽象方法,把receiver类继承PushMessageReceiver可以使用。PushManager.stopWork() 的回调函数。

参数
  • context 上下文
  • errorCode 错误码,0表示从云推送解绑定成功,非0表示失败
  • requestId 分配给对云推送的请求的id

常量说明

Android SDK的常量定义都在PushConstants类中。

如:Push发送给应用的Action的常量,都是String类型

ACTION_MESSAGE

接收消息时使用。

ACTION_RECEIVE

获取方法调用的返回值,包括绑定、设置Tag、删除Tag等方法。

ACTION_RECEIVER_NOTIFICATION_CLICK

通知点击事件的截获。

注意:通知发出时,应用从Intent中获取Extra的常量,均为String类型

EXTRA_PUSH_MESSAGE_STRING

消息内容,在ACTION_MESSAGE中使用。Extra获取方法

intent.getStringExtra(PushConstants.EXTRA_PUSH_MESSAGE_STRING)

EXTRA_METHOD

方法名,在ACTION_RECEIVE中使用。Extra获取方法

intent.getStringExtra(PushConstants.EXTRA_METHOD)

EXTRA_ERROR_CODE

方法错误码,在ACTION_RECEIVE中使用。Extra获取方法

intent.getIntExtra(PushConstants.EXTRA_ERROR_CODE)

EXTRA_CONTENT

方法返回内容,在ACTION_RECEIVE中使用。Extra获取方法

intent.getByteArrayExtra(PushConstants.EXTRA_CONTENT)

EXTRA_NOTIFICATION_TITLE

通知标题,在ACTION_RECEIVER_NOTIFICATION_CLICK中使用。Extra获取方法

intent.getStringExtra(PushConstants.EXTRA_NOTIFICATION_TITLE)

EXTRA_NOTIFICATION_CONTENT

通知内容,在ACTION_RECEIVER_NOTIFICATION_CLICK中使用。Extra获取方法

intent.getStringExtra(PushConstants.ACTION_RECEIVER_NOTIFICATION_CLICK)

方法名常量,都是String类型

METHOD_BIND, METHOD_SET_TAGS, METHOD_DEL_TAGS

绑定方法名,在EXTRA_METHOD中取得的值是这三者之一。