全部产品
移动推送

SDK API介绍

更新时间:2017-08-09 10:13:48   分享:   

Android API

Android SDK最新版本v3.0.11。

Android参考Demo

API索引:


1. CloudPushService接口

以下接口调用时,如有回调,均为异步执行,且回调不能为空。

1.1基本设置


SDK注册

  • 初始化推送SDK,关联到云通道。

参数

  • context 应用上下文(需要ApplicationContext
  • callback 回调
  1. void register(Context context, CommonCallback callback);

SDK动态注册接口

  • 支持动态设置appKey,appSecret的注册接口

参数

  • context 应用上下文(需要ApplicationContext
  • appKey
  • appSecret
  • callback 回调
  1. void register(Context context, String appKey, String appSecret, CommonCallback callback);

启动信息统计

  • 统计App启动信息。
  1. void onAppStart();

获取设备标识

  • 获取设备唯一标识。

返回

  • 设备唯一标识。
  1. String getDeviceId();

设置日志等级

  • 需要在通道初始化之前设置;
  • 默认日志等级为CloudPushService.ERROR

参数

  • logLevel 支持设置:CloudPushService.ERROR | CloudPushService.INFO | CloudPushService.DEBUG | CloudPushService.OFF(关闭Log)
  1. void setLogLevel(int logLevel);

动态设置appKey(V2.3.6及以上版本支持)

  • 动态设置appKey无需在manifest配置appKey
  • 务必在调用register注册接口之前调用该接口,否则动态设置失效

参数

  • appKey 需要设置的appKey
  1. void setAppKey(String appKey);

动态设置appSecret(V2.3.6及以上版本支持)

  • 动态设置appSecret无需在manifest配置appSecret
  • 务必在调用register注册接口之前调用该接口,否则动态设置失效

参数

  • appSecret 需要设置的appSecret
  1. void setAppSecret(String appSecret);

打开推送通道(V3.0.3及以上版本支持)

  • 用于在程序运行时动态打开推送通道
  • 全量推送场景下,打开推送通道存在2-3小时延迟。其他场景实时生效

参数

  • callback 回调
  1. void turnOnPushChannel(CommonCallback callback);

关闭推送通道(V3.0.3及以上版本支持)

  • 用于在程序运行时动态关闭推送通道
  • 全量推送场景下,关闭推送通道存在2-3小时延迟。其他场景实时生效

参数

  • callback 回调
  1. void turnOffPushChannel(CommonCallback callback);

查询推送通道状态(V3.0.3及以上版本支持)

  • app运行时查询当前推送通道状态
  • 如果当前为打开状态,则通过callback.success(String response)回调传入’on’;反之则传入’off’

参数

  • callback 回调
  1. void checkPushChannelStatus(CommonCallback callback);

设置消息接收IntentService(V3.0.10及以上版本支持)

  • 通过IntentService组件接收消息回调
  • 设置后消息将通过该组件透出,不再通过MessageReceiver
  • 设置的IntentService需继承com.alibaba.sdk.android.push.AliyunMessageIntentService,并覆写相关回调方法

参数

  • messageIntentService 自定义接收消息IntentService的class
  1. void setPushIntentService(Class messageIntentService);

1.2 账号API


绑定账号

  • 将应用内账号和推送通道相关联,可以实现按账号的定点消息推送;
  • 设备只能绑定一个账号,同一账号可以绑定到多个设备;
  • 同一设备更换绑定账号时无需进行解绑,重新调用绑定账号接口即可生效;
  • 若业务场景需要先解绑后绑定,在解绑账号成功回调中进行绑定绑定操作,以此保证执行的顺序性;
  • 账户名设置支持64字节。

参数

  • account 绑定账号名
  • callback 回调
  1. void bindAccount(String account, CommonCallback callback);

解绑账号

  • 将应用内账号和推送通道取消关联。

参数

  • callback 回调
  1. void unbindAccount(CommonCallback callback);

1.3 标签API


绑定标签

  • 绑定标签到指定目标;
  • 支持向设备、账号和别名绑定标签,绑定类型由参数target指定;
  • 绑定标签在10分钟内生效;
  • App最多支持绑定1万个标签,单个标签最大支持128字符。

参数

  • target 目标类型,1:本设备; 2:本设备绑定账号; 3:别名
  • target(V2.3.5及以上版本) 目标类型,CloudPushService.DEVICE_TARGET:本设备; CloudPushService.ACCOUNT_TARGET:本账号; CloudPushService.ALIAS_TARGET:别名
  • tags 标签(数组输入)
  • alias 别名(仅当target = 3时生效)
  • callback 回调
  1. void bindTag(int target, String[] tags, String alias, CommonCallback callback);

解绑标签

  • 解绑指定目标标签;
  • 支持解绑设备、账号和别名标签,解绑类型由参数target指定;
  • 解绑标签在10分钟内生效;
  • 解绑标签只是解除设备和标签的绑定关系,不等同于删除标签,即该APP下标签仍然存在,系统目前不支持标签的删除。

参数

  • target 目标类型,1:本设备; 2:本设备绑定账号; 3:别名。
  • target(V2.3.5及以上版本) 目标类型,CloudPushService.DEVICE_TARGET:本设备; CloudPushService.ACCOUNT_TARGET:本账号; CloudPushService.ALIAS_TARGET:别名
  • tags 标签(数组输入)
  • alias 别名(仅当target = 3时生效)
  • callback 回调
  1. void unbindTag(int target, String[] tags, String alias, CommonCallback callback);

查询标签

  • 查询目标绑定标签,当前仅支持查询设备标签;
  • 查询结果可从回调onSuccess(response)的response获取;
  • 标签绑定成功且生效(10分钟内)后即可查询。

参数

  • target 目标类型,1: 本设备
  • target(V2.3.5及以上版本) 目标类型,CloudPushService.DEVICE_TARGET:本设备;
  • callback 回调
  1. void listTags(int target, CommonCallback callback);

1.4 别名API


添加别名

  • 设备添加别名;
  • 单个设备最多添加128个别名,且同一别名最多添加到128个设备;
  • 别名支持128字节。

参数

  • alias 别名
  • callback 回调
  1. void addAlias(String alias, CommonCallback callback);

删除别名

  • 删除设备别名;
  • 支持删除指定别名和删除全部别名(alias = null || alias.length = 0)。

参数

  • alias 别名(alias = null or alias.length = 0时,删除设备全部别名)
  • callback 回调
  1. void removeAlias(String alias, CommonCallback callback);

查询别名

  • 查询设备别名;
  • 查询结果可从回调onSuccess(response)的response中获取;
  • 从V3.0.9及以上版本开始,接口内部有5s短缓存,5s内多次调用只会请求服务端一次。

参数

  • callback 回调
  1. void listAliases(CommonCallback callback);

1.5 通知设置API


设置通知声音

  • 设置推送通知声音文件路径;
  • 若不调用本接口,默认获取资源id为R.raw.alicloud_notification_sound的资源文件;
  • 若没有获取到指定声音文件,取设备设置的消息声音。

参数

  • filePath 通知声音文件路径
  1. void setNotificationSoundFilePath(String filePath);

设置通知栏图标

  • 设置推送通知栏图标资源Bitmap。
  • 若不调用本接口,默认获取id为R.drawable.alicloud_notification_largeIcon的资源文件;
  • 若没有获取到指定图标文件,取App启动图标。

参数

  • icon 图标资源Bitmap
  1. void setNotificationLargeIcon(Bitmap icon);

设置状态栏图标

  • 设置推送状态栏图标资源Id;
  • 若不调用本接口,默认获取id为R.drawable.alicloud_notification_smallIcon的资源文件;
  • 若没有获取到指定资源文件Id,取App启动图标。

参数

  • iconId 图标资源Id
  1. void setNotificationSmallIcon(int iconId);

设置免打扰时段

  • 设置免打扰时间段,过滤所有通知与消息;
  • 免打扰时段仅支持设置一次,多次调用以最后一次调用设置时段为准;
  • 设置免打扰时段为00:00 - 00:00,可取消免打扰功能;(以下功能支持该用法,V2.3.5及以上版本使用关闭免打扰功能接口)
  • 全天免打扰可以设置为”0:0-23:59”
  • 免打扰时段设置对小米辅助弹窗通知无效。

参数

  • startHour 免打扰的起始时间(小时),24小时制,取值范围:0-23
  • startMinute 免打扰起始时间(分钟),取值范围:0-59
  • endHour 免打扰的结束时间(小时),24小时制,取值范围:0-23
  • endMinute 免打扰结束时间(分钟),取值范围:0-59
  1. void setDoNotDisturb(int startHour, int startMinute, int endHour, int endMinute, CommonCallback callback);

关闭免打扰功能(V2.3.5及以上版本支持)

  • 关闭后,先前设置的免打扰时段失效
  • 免打扰功能默认是关闭的
  • 没有对应的开发免打扰功能接口,调用设置免打扰功能时段功能后自动打开免打扰功能
  1. void closeDoNotDisturbMode();

删除所有通知接口(V2.3.7及以上版本支持)

  • 删除推送SDK创建的所有通知
  • 若需要实现精准删除特定通知可以在onNotification回调中获取通知id,自行删除
  1. void clearNotifications();

1.6 自建通知统计上报API(V3.0.6及以上版本支持)


本接口主要针对统计用户自建通知(通过阿里云推送发送透传消息,并在onMessage回调中自行创建通知)的删除/点击事件上报,其相关实现可以参考移动推送Android SDK:透传消息+用户自建通知最佳实践,如果您直接通过阿里云推送通知,无需使用相关接口。

自建通知点击上报接口

  • 上报自建通知的点击事件
  • 请确保同一消息仅上报一次

参数

  • message 要上报点击事件的消息实例
  1. void clickMessage(CPushMessage message);

自建通知删除上报接口

  • 上报自建通知的删除事件
  • 请确保同一消息仅上报一次

参数

  • message 要上报删除事件的消息实例
  1. void dismissMessage(CPushMessage message);

1.7 电话API(V3.0.11及以上版本支持)


为提高信息的到达率和实效性,扩展推送的使用场景,我们推出了推送与短信的融合通知模式。开发者可以设置在一定时间内,如果用户未收到或未点击推送,通过短信补发通知用户。具体方案可参考:推送短信融合

为实现推送短信融合方案,需要在终端接入绑定/解绑电话号接口,接口详情如下。

绑定电话号

将设备与电话号绑定

参数

  • phoneNumber 要绑定的手机号
  • callback 回调
  1. void bindPhoneNumber(String phoneNumber, CommonCallback callback);

解绑电话号

解除当前设备与电话号的绑定关系

参数

  • callback 回调
  1. void unbindPhoneNumber(CommonCallback callback);

2. MessageReceiver/AliyunMessageIntentService

  • 通过继承MessageReciever,可以拦截通知,接收消息,获取推送中的扩展字段。或者在通知打开或删除的时候,切入进行后续处理。
  • 如果调用了setPushIntentService,则需继承com.alibaba.sdk.android.push.AliyunMessageIntentService,并覆写相关方法,AliyunMessageIntentService所有消息回调同MessageReceiver一致。

使用方法:

  • MessageReceiver

    • 继承com.alibaba.sdk.android.push.MessageReceiver
    • 在Manifest中找到原来MessageReceiver的配置,将上边的class替换成你自己的receiver[不要配置多个]。

      1. <!--消息接收监听器-->
      2. <receiver android:name="com.alibaba.sdk.android.push.MessageReceiver <-- 把这里替换成你自己的receiver">
      3. <intent-filter>
      4. <action android:name="com.alibaba.push2.action.NOTIFICATION_OPENED"/>
      5. </intent-filter>
      6. ... ...
      7. </receiver>
  • AliyunMessageIntentService
    • 继承com.alibaba.sdk.android.push.AliyunMessageIntentService并覆写相关方法
    • 在Manifest中注册该service
      1. <service android:name="MyPushIntentService" >
      2. <intent-filter>
      3. <action android:name="com.alibaba.push2.action.NOTIFICATION_OPENED" />
      4. </intent-filter>
      5. <intent-filter>
      6. <action android:name="com.alibaba.push2.action.NOTIFICATION_REMOVED" />
      7. </intent-filter>
      8. <intent-filter>
      9. <action android:name="com.alibaba.sdk.android.push.RECEIVE" />
      10. </intent-filter>
      11. </service>

消息接收回调

  • 用于接收服务端推送的消息。
  • 消息不会弹窗,而是回调该方法。

参数

  • context 上下文环境
  • message CPushMessage类型,可以获取消息Id、消息标题和内容。
  1. void onMessage(Context context, CPushMessage message);

通知接收回调

  • 客户端接收到通知后,回调该方法。
  • 可获取到并处理通知相关的参数。

参数

  • context 上下文环境
  • title 通知标题
  • summary 通知内容
  • extraMap 通知额外参数,包括部分系统自带参数:
    • _ALIYUN_NOTIFICATION_ID_(V2.3.5及以上):创建通知对应id
    • _ALIYUN_NOTIFICATION_PRIORITY_(V2.3.5及以上):创建通知对应id。默认不带,需要通过OpenApi设置
  1. void onNotification(Context context, String title, String summary, Map<String, String> extraMap)

通知打开回调

  • 打开通知时会回调该方法,通知打开上报由SDK自动完成。

参数

  • context 上下文环境
  • title 通知标题
  • summary 通知内容
  • extraMap 通知额外参数,包括部分系统自带参数:
    • _ALIYUN_NOTIFICATION_ID_(V2.3.5及以上):创建通知对应id
    • _ALIYUN_NOTIFICATION_PRIORITY_(V2.3.5及以上):创建通知对应id。默认不带,需要通过OpenApi设置
  1. void onNotificationOpened(Context context, String title, String summary, String extraMap);

无跳转逻辑通知打开回调

  • 打开无跳转逻辑(open=4)通知时回调该方法(v2.3.2及以上版本支持),通知打开上报由SDK自动完成。

参数

  • context 上下文环境
  • title 通知标题
  • summary 通知内容
  • extraMap 通知额外参数,包括部分系统自带参数:
    • _ALIYUN_NOTIFICATION_ID_(V2.3.5及以上):创建通知对应id
    • _ALIYUN_NOTIFICATION_PRIORITY_(V2.3.5及以上):创建通知对应id。默认不带,需要通过OpenApi设置
  1. void onNotificationClickedWithNoAction(Context context, String title, String summary, String extraMap);

通知删除回调

  • 删除通知时回调该方法,通知删除上报由SDK自动完成。

参数

  • context 上下文环境
  • messageId 删除通知的Id
  1. void onNotificationRemoved(Context context, String messageId);

通知在应用内到达回调

  • 当用户创建自定义通知样式,并且设置推送应用内到达不创建通知弹窗时调用该回调,且此时不调用onNotification回调(v2.3.3及以上版本支持)

参数

  • context 上下文环境
  • title 通知标题
  • summary 通知内容
  • extraMap 通知额外参数
  • openType 原本通知打开方式,1:打开APP;2:打开activity;3:打开URL;4:无跳转逻辑
  • openActivity 所要打开的activity的名称,仅当openType=2时有效,其余情况为null
  • openUrl 所要打开的URL,仅当openType=3时有效,其余情况为null
  1. void onNotificationReceivedInApp(Context context, String title, String summary, Map<String, String> extraMap, int openType, String openActivity, String openUrl);

3. 自定义样式通知(V2.3.3及以上版本开始支持

Android Push SDK支持用户自定义通知样式,用户可以设定自己的通知样式,涉及的内容包括通知的提醒方式(声音、震动、静默),通知在状态栏的显示图标,推送消息应用内到达时是否创建通知以及自定义通知布局文件等。自定义样式通知的设置包括两部分:

3.1 客户端设置通知样式

  • 用户利用SDK提供的自定义通知样式接口创建自定义样式通知。SDK中有两个自定义样式通知类:1)BasicCustomPushNotification;2)AdvancedCustomPushNotification。其中BasicCustomPushNotification用户设置基础样式,包括提醒方式、状态栏图标以及当推送消息到达时应用正处于前台情况下是否创建该通知等。AdvancedCustomPushNotificationBasicCustomPushNotification的子类,继承了BasicCustomPushNotification的所有方法,同时还可以设置通知样式布局文件
  • 每个样式都需要对应一个特定的整数类型id,如果多个样式设置为同一个id,则最后设置的样式有效。如果SDK没有找到对应id的样式则会创建默认样式的通知
  • 样式只需设置一次,SDK会记住这个设置,在需要使用时加载对应样式
  • 具体使用例子请参考Demo

3.2 后端推送消息时添加自定义样式id

  • 用户利用OpenApi推送消息时设定特定样式的id
  • 服务端不能设置样式,只能指定需要展现的样式id
  • 指定id的样式必须在客户端已经进行设置,否则SDK会创建默认样式的通知

3.3 Example


Example-BasicCustomPushNotification

  1. BasicCustomPushNotification notification = new BasicCustomPushNotification();
  2. notification.setRemindType(BasicCustomPushNotification.REMIND_TYPE_SOUND);
  3. notification.setStatusBarDrawable(R.drawable.logo_yuanjiao_120);
  4. boolean res = CustomNotificationBuilder.getInstance().setCustomNotification(1, notification);

Example-AdvancedCustomPushNotification

  1. AdvancedCustomPushNotification notification = new AdvancedCustomPushNotification(R.layout.notitfication_layout, R.id.m_icon, R.id.m_title, R.id.m_text);
  2. notification.setServerOptionFirst(true);
  3. notification.setBuildWhenAppInForeground(false);
  4. boolean res = CustomNotificationBuilder.getInstance().setCustomNotification(2, notification);

Example-OpenApi

客户端设置完成后,服务端在推送通知时需要利用OpenApi指明对应的自定义样式ID

  1. final SimpleDateFormat dateFormat = new SimpleDateFormat("MM-dd HH:mm:ss");
  2. final String date = dateFormat.format(new Date());
  3. PushRequest pushRequest = new PushRequest();
  4. // 推送目标
  5. pushRequest.setAppKey(appKey);
  6. pushRequest.setTarget("device"); //推送目标: device:推送给设备; account:推送给指定帐号,tag:推送给自定义标签; all: 推送给全部
  7. pushRequest.setTargetValue("deviceId");
  8. // 推送配置
  9. pushRequest.setType(1); // 0:表示消息(默认为0), 1:表示通知
  10. pushRequest.setTitle(date); // 消息的标题
  11. pushRequest.setBody("PushRequest body"); // 消息的内容
  12. pushRequest.setSummary("PushRequest summary"); // 通知的摘要
  13. pushRequest.setAndroidNotificationBarType(2);//设置的通知样式ID,通知栏自定义样式范围0-100
  14. // 推送配置: Android
  15. pushRequest.setAndroidOpenType("1"); // 点击通知后动作,1:打开应用 2: 打开应用Activity 3:打开 url
  16. pushRequest.setAndroidExtParameters("{\"_NOTIFICATION_BAR_STYLE_\":\"2\"}");

3.4 BasicCustomPushNotification API


默认构造函数

  • BasicCustomPushNotification的默认构造函数,所有配置采用默认设置:通知方式采用震动+通知;NotificationFlag采用Notification.FLAG_AUTO_CANCEL,状态栏图标用的是android.R.drawable.stat_notify_chat。
  1. public BasicCustomPushNotification();

构造函数

参数

  • drawable 状态栏图标
  • flags NotificationFlags,支持系统Notification下的Flag参数
  • remindType 提醒类型,有BasicCustomPushNotification.REMIND_TYPE_SILENT:静默;BasicCustomPushNotification.REMIND_TYPE_VIBRATE:震动;BasicCustomPushNotification.REMIND_TYPE_SOUND:声音;BasicCustomPushNotification.REMIND_TYPE_VIBRATE_AND_SOUND:声音+震动
  1. public BasicCustomPushNotification(int drawable, int flags, int remindType);

获取状态栏图标

  • 获取已设置的状态栏图标
  1. public int getStatusBarDrawable()

设置状态栏图标

  • 更改状态栏图标设置

参数

  • statusBarDrawable 状态栏图标资源id
  1. public void setStatusBarDrawable(int statusBarDrawable);

获取提醒方式

  • 获取已经设置的提醒方式
  1. public int getRemindType();

设置提醒方式

  • 更改自定义通知的提醒方式

参数

  • remindType 提醒方式,提供的参数有:BasicCustomPushNotification.REMIND_TYPE_SILENT:静默;BasicCustomPushNotification.REMIND_TYPE_VIBRATE:震动;BasicCustomPushNotification.REMIND_TYPE_SOUND:声音;BasicCustomPushNotification.REMIND_TYPE_VIBRATE_AND_SOUND:声音+震动
  1. public void setRemindType(int remindType);

获取Notification Flags参数

  • 获取已经设置的notification flag参数
  1. public int getNotificationFlags();

设置Notification Flags参数

  • 更改自定义通知的flags参数

参数

  • notificationFlags 支持系统自带的Notification Flag参数
  1. public void setNotificationFlags(int notificationFlags);

获取是否服务端设置优先

  • 利用OpenApi或者阿里云推送控制台推送消息都可以设置提醒方式,当后端设置的提醒方式和自定义样式提醒方式冲突时,SDK根据serverOptionFirst参数来判断提醒方式策略。如果该参数为true,则采用后端设定的提醒方式;如果该参数为false,则采用自定义样式指定的提醒方式。默认为false
  1. public boolean isServerOptionFirst();

设置是否服务端优先

  • 更改自定义通知的serverOptionFirst参数

参数

  • serverOptionFirst 是否服务器配置优先
  1. public void setServerOptionFirst(boolean serverOptionFirst);

获取推送前台到达否创建通知参数

  • 当推送到达时,如果应用处在前台,用户可以通过自定义样式决定是否创建通知。默认是创建通知
  1. public boolean isBuildWhenAppInForeground();

设置推送前台到达否创建通知参数

  • 更改当推送到达时应用处在前台情况下是否创建通知的设置

参数

  • buildWhenAppInForeground 是否创建通知
  1. public void setBuildWhenAppInForeground(boolean buildWhenAppInForeground);

3.5 AdvancedCustomPushNotification API

  • AdvancedCustomPushNotificationBasicCustomPushNotification的子类,继承了上文中BasicCustomPushNotification的所有方法。

AdvancedCustomPushNotification构造函数

  • AdvancedCustomPushNotification类的构造函数,AdvancedCustomPushNotification没有默认构造函数

参数

  • view 自定义通知布局文件id。注:Notification的自定义布局是RemoteViews,和其他RemoteViews一样,在自定义视图布局文件中,仅支持FrameLayout、LinearLayout、RelativeLayout三种布局。
  • iconViewId 自定义布局文件中icon的viewId
  • titleViewId 自定义布局文件中title的viewId
  • contentViewId 自定义布局文件中显示通知正文的viewId
  1. public AdvancedCustomPushNotification( int view, int iconViewId, int titleViewId, int contentViewId);

设置通知图标

  • 设置通知栏中显示的图标,该图标显示在iconViewId所指定的控件中。

参数

  • icon icon图标资源id
  1. public void setIcon(int icon);

获取通知图标

  • 获取设置的通知图标
  1. public int getIcon();

3.6 CustomNotificationBuilder API

  • CustomNotificationBuilder用于注册用户设定好的自定义样式通知

获取CustomNotificationBuilder实例

  • CustomNotificationBuilder是单例类,必须通过指定接口来获取实例
  1. public static CustomNotificationBuilder getInstance();

注册自定义样式通知

  • 用户创建好自定义样式通知后需要将其注册,并赋予其一个特定的id

参数

  • customNotificationId 所注册的自定义样式通知的id,id必须大于0。如果将多个不同的自定义样式通知赋予同一个id,则最后注册的通知有效,其他的通知将会被覆盖
  • notification 创建的通知,该通知可以是BasicCustomPushNotification对象也可以是AdvancedCustomPushNotification对象,但是不能为null

返回

  • 该方法会返回一个boolean类型的结果,如果返回true,则注册成功;反之则失败。
  1. public boolean setCustomNotification(int customNotificationId, BasicCustomPushNotification notification);

本文导读目录
本文导读目录
以上内容是否对您有帮助?