友盟+搜索

{{errorMsg}}
  • Android 消息推送SDK V3.3.1x  (2017-8-30) SDK下载 
使用方式:
1. 解压缩zip,替换组件化SDK下载的push模块。
2. 参考本文档后方的小米&华为push通道集成说明进行集成。

快速体验

创建应用

集成SDK之前, 请在http://push.umeng.com上使用组件化Demo的包名com.umeng.soexample创建应用,获取应用对应的AppKey和Umeng Message Secret。

替换Appkey和Umeng Message Secret

1、点击“open an existing android studio project”, 打开Demo。

如下图:

2、用添加应用时获得的AppKey和Umeng Message Secret替换掉Demo下的AndroidManifest.xml中的默认的AppKey和Umeng Message Secret。

打包运行

将Demo安装到联网的测试设备上并打开,并在log中查看device token。

说明:

  • device token是【友盟+】消息推送生成的用于标识设备的id,长度为44位,不能定制和修改。同一台设备上不同应用对应的device token不一样。

推送通知

添加测试设备

在【友盟+】消息推送服务后台http://push.umeng.com的“测试模式”中填写该设备的device token,将该设备添加为测试设备:

推送测试通知

在“测试模式”中推送通知。通知发送后会在系统通知栏收到并展示,同时通过响铃、振动或呼吸灯提醒用户。若在测试设备上收到通知,表明SDK集成成功。推送页面如下图所示:

说明:

  • APP收到通知后会展示在通知栏,开发者可以在【友盟+】后台指定用户点击通知后的操作,包括“打开应用”、“打开链接”、“打开指定页面(自身应用内的Activity)”、自定义行为(需自己实现方法,详见:高级功能-通知的展示及提醒-自定义通知打开动作)。
  • 如果没有收到消息,请参考FAQ中的处理方法。
  • 测试模式具体介绍:http://bbs.umeng.com/thread-8910-1-1.html

完整集成

Android Studio集成步骤

创建应用

  1. 请在 http://push.umeng.com上使用你的应用包名创建应用(注:Android Studio请使用applicationId作为包名)。

  2. Appkey作为【友盟+】对应用的唯一标识,在【友盟+】推送和【友盟+】统计,都是可以使用同一个的。已经使用了【友盟+】统计的用户,请从【友盟+】后台已有应用中添加。

  3. 获取应用对应的AppKey和Umeng Message Secret,如下图:

导入PushSDK

  1. 把下载的zip文件解压缩(解压后的文件路径不能有中文)。

  2. 把解压缩后得到的目录下的thirdparties目录里的utdid4all-*.**这个jar文件拷贝到项目工程的libs目录。

  3. 把解压缩后得到的目录下的push目录当做Module导入到自己的工程,如下图所示:

注意:

  • PushSDK 3.0默认只提供armeabi和x86两种so文件夹,若主工程中的so文件夹与PushSDK下的so文件夹不一致,则可以有两种方式处理(选择一种即可):
    (1) 删除主工程下多余的so文件夹,与PushSDK下的so文件夹保持一致。
    (2) 下载全平台so文件,添加缺少的so文件夹至PushSDK下,使PushSDK的so文件夹与主工程的so文件夹保持一致。全平台SO文件下载

配置Appkey和Secret

若已经使用通用接口进行初始化并设置了Appkey和Secret,则可以忽略此步骤

在工程的Application Module的AndroidManifest.xml中的<application></application>标签下添加:

<meta-data
    android:name="UMENG_APPKEY"
    android:value="xxxxxxxxxxxxxxxxxxxxxxxxxxxx" />
<meta-data
    android:name="UMENG_MESSAGE_SECRET"
    android:value="xxxxxxxxxxxxxxxxxxxxxxxxxxxx" />

把上述的UMENG_APPKEYUMENG_MESSAGE_SECRET的值修改为和自己应用对应的值。

说明:

  • 即使用户已经在项目AndroidManifest.xml清单配置中设置了Appkey和Secret,新版组件化SDK还是要求必须在项目工程的自定义Application类的onCreate方法中调用初始化方法UMConfigure.init,已经在AndroidManifest.xml清单配置中设置了Appkey和Secret参数的用户,初始化方法中Appkey和Secret参数可以传入null。
  • Appkey和Secret在代码或manifest中均可设置,若同时在AndroidManifest.xml和代码中设置了Appkey和Secret,则以代码设置的为准。
  • PushSDK组件化版本删除了PushAgent类的setAppkeyAndSecret方法,如要使用代码设置Appkey、Secret,请参考通用接口初始化

添加Channel ID

若已经使用通用接口进行初始化并设置了Channel,则可以忽略此步骤

你可以用Channel ID来标识App的推广渠道,作为推送消息时给用户分组的一个维度。设置方法如下,在Application Module的AndroidManifest.xml中的<application></application>标签下添加:

<meta-data
    android:name="UMENG_CHANNEL"
    android:value="Channel ID" />

请将"android:value"中的"Channel ID"替换为App的推广渠道。

说明:

  • 若在AndroidManifest.xml设置了Channel,则通用初始化方法UMConfigure.init的channel参数可以传null。
  • 若同时在AndroidManifest.xml和代码中设置了Channel,则以代码设置的为准。
  • 若在AndroidManifest.xml和代码里均没有设置,则使用Unknown作为Channel ID。
  • 你可以使用20位以内的英文和数字为渠道定名(不要使用纯数字)。
  • 每台设备仅识别首次安装激活的渠道。
  • PushSDK组件化版本删除了PushAgent类的setMessageChannel方法,如要使用代码设置Channel,请参考通用接口初始化

配置build.gradle

  1. 在Application Module的build.gradle文件的dependencies下添加compile project(':push')
  2. 请确保Application Module的build.gradle文件中的applicationId与资源包名package一致(若不一致,请参考高级功能--自定义资源包名)。

注意:

  • (可选)若主工程的targetSdkVersion为23及以上,请在代码中遵循Android 6.0的运行时权限机制**申请存储权限**(WRITE_EXTERNAL_STORAGE),可以更好的在Android 6.0及以上版本的机型中使用推送。
  • Android Plugin Version(com.android.tools.build:gradle)推荐使用2.0.0及以上版本,使用过旧的版本可能由于编译问题导致无法获取device token。

初始化PushSDK

注册推送服务

务必在工程的自定义Application类的 onCreate() 方法中注册推送服务,无论推送是否开启都需要调用此方法:

PushAgent mPushAgent = PushAgent.getInstance(this);
//注册推送服务,每次调用register方法都会回调该接口
mPushAgent.register(new IUmengRegisterCallback() {

    @Override
    public void onSuccess(String deviceToken) {
        //注册成功会返回device token
    }

    @Override
    public void onFailure(String s, String s1) {

    }
});

注意:

  • 请勿在调用register方法时做进程判断处理(主进程和channel进程均需要调用register方法才能保证长连接的正确建立)。若未按文档要求初始化,则会导致App运行时,弹出toast提示。此时,请参考下文解决。
  • 若有需要,可以在Application的onCreate方法中创建一个子线程,并把mPushAgent.register这一行代码放到该子线程中去执行(请勿将PushAgent.getInstance(this)放到子线程中)。
  • device token是【友盟+】消息推送生成的用于标识设备的id,长度为44位,不能定制和修改。同一台设备上不同应用对应的device token不一样。
  • 如需手动获取device token,可以调用mPushAgent.getRegistrationId()方法(需在注册成功后调用)。

统计应用启动数据

在所有的Activity 的onCreate 方法或在应用的BaseActivityonCreate方法中添加:

PushAgent.getInstance(context).onAppStart();

注意:

  • 此方法与统计分析sdk中统计日活的方法无关!请务必调用此方法!

  • 如果不调用此方法,不仅会导致按照"几天不活跃"条件来推送失效,还将导致广播发送不成功以及设备描述红色等问题发生。可以只在应用的主Activity中调用此方法,但是由于SDK的日志发送策略,有可能由于主activity的日志没有发送成功,而导致未统计到日活数据。

设置通知栏图标

默认使用应用图标作为通知栏图标。为了提升展示效果和机型适配,推荐使用自定义通知栏图标

详见高级功能--自定义通知栏图标

混淆配置

如果App需要使用proguard进行混淆打包,请添加以下混淆代码:

-dontwarn com.taobao.**
-dontwarn anet.channel.**
-dontwarn anetwork.channel.**
-dontwarn org.android.**
-dontwarn org.apache.thrift.**
-dontwarn com.xiaomi.**
-dontwarn com.huawei.**

-keepattributes *Annotation*

-keep class com.taobao.** {*;}
-keep class org.android.** {*;}
-keep class anet.channel.** {*;}
-keep class com.umeng.** {*;}
-keep class com.xiaomi.** {*;}
-keep class com.huawei.** {*;}
-keep class org.apache.thrift.** {*;}

-keep class com.alibaba.sdk.android.**{*;}
-keep class com.ut.**{*;}
-keep class com.ta.**{*;}

-keep public class **.R$*{
   public static final int *;
}

#(可选)避免Log打印输出
-assumenosideeffects class android.util.Log {
   public static *** v(...);
   public static *** d(...);
   public static *** i(...);
   public static *** w(...);
 }

打包运行

将打包生成的apk文件安装到联网的测试设备上并打开(推荐使用真机进行调试)。

注意:

  • 若编译时报ta.utdid2.xxut.device.xx等冲突异常,请将项目工程的libs目录中的utdid4all-*.**这个jar文件删除,重新编译即可。

测试推送

添加测试设备

在【友盟+】消息推送服务后台http://push.umeng.com的“测试模式”中填写该设备的device token,将该设备添加为测试设备:

推送测试通知

在“测试模式”中推送通知。通知发送后会在系统通知栏收到并展示,同时通过响铃、振动或呼吸灯提醒用户。若在测试设备上收到通知,表明SDK集成成功。推送页面如下图所示:

说明:

  • APP收到通知后会展示在通知栏,开发者可以在【友盟+】后台或API指定用户点击通知后的操作,包括:打开应用、打开链接、打开指定页面(自身应用内的Activity)、自定义行为(需自己实现方法,详见:高级功能-通知的展示及提醒-自定义通知打开动作)。
  • 如果没有收到消息,请参考FAQ中的处理方法。
  • 测试模式具体介绍: http://bbs.umeng.com/thread-8910-1-1.html

API对接(可选)

  1. 如果要使用API对接【友盟+】服务器来发送消息,需要在【友盟+】消息推送服务后台http://push.umeng.com填写服务器地址,进行白名单登记。
  2. 参考API文档中的格式发送测试消息。**需要填写正确的App Master Secret**。

Eclipse集成步骤

创建应用

请在http://push.umeng.com上使用你的应用包名创建应用,获取应用对应的AppKey和Umeng Message Secret。

导入PushSDK

  1. 把下载的zip文件解压缩(解压后的文件路径不能有中文)。
  2. 把解压缩后得到的目录下的thirdparties目录里的utdid4all-*.**这个jar文件拷贝到项目工程的libs目录。
  3. 把解压缩后得到的目录下的push目录当做Library导入到自己的工程。
  4. 主工程依赖Push Library。

注意:

  • PushSDK 3.0默认只提供armeabi和x86两种so文件夹,若主工程中的so文件夹与PushSDK下的so文件夹不一致,则可以有两种方式处理(选择一种即可):
    (1) 删除主工程下多余的so文件夹,与PushSDK下的so文件夹保持一致。
    (2) 在官网PushSDK下载处,下载全平台so文件,添加缺少的so文件夹至PushSDK下,使PushSDK的so文件夹与主工程的so文件夹保持一致。全平台SO文件下载

配置PushSDK

  1. 把push目录下的AndroidManifest.xml中的${applicationId}替换成为自己项目的包名。
  2. 右键单击push的libs目录下的jar文件,选择add to build path(若使用最新版本的ADT工具,则会自动将libs目录下的jar包添加到build path,无需执行此步骤)。
  3. 在自己工程目录下找到project.properties,在里面加入manifestmerger.enabled=true,同时使主工程的minSdkVersion、targetSdkVersion与PushSDK的minSdkVersion、targetSdkVersion保持一致。

注意:

  • (可选)若主工程的**targetSdkVersion为23及以上**,请在代码中遵循Android 6.0的运行时权限机制**申请存储权限**(WRITE_EXTERNAL_STORAGE),可以更好的在Android 6.0及以上版本的机型中使用推送。
  • ADT工具推荐使用23.0.2及以上版本,使用过旧的ADT工具可能导致合并清单(manifestmerger.enabled=true)出错。

配置Appkey和Secret

若已经使用通用接口进行初始化并设置了Appkey和Secret,则可以忽略此步骤

在工程的Application Module的AndroidManifest.xml中的<application></application>标签下添加:

<meta-data
    android:name="UMENG_APPKEY"
    android:value="xxxxxxxxxxxxxxxxxxxxxxxxxxxx" />
<meta-data
    android:name="UMENG_MESSAGE_SECRET"
    android:value="xxxxxxxxxxxxxxxxxxxxxxxxxxxx" />

把上述的UMENG_APPKEYUMENG_MESSAGE_SECRET的值修改为和自己应用对应的值。

说明:

  • 即使用户已经在项目AndroidManifest.xml清单配置中设置了Appkey和Secret,新版组件化SDK还是要求必须在项目工程的自定义Application类的onCreate方法中调用初始化方法UMConfigure.init,已经在AndroidManifest.xml清单配置中设置了Appkey和Secret参数的用户,初始化方法中appkey和secret参数可以传入null。
  • Appkey和Secret在代码或manifest中均可设置,若同时在AndroidManifest.xml和代码中设置了Appkey和Secret,则以代码设置的为准。
  • PushSDK组件化版本删除了PushAgent类的setAppkeyAndSecret方法,如要使用代码设置Appkey、Secret,请参考通用接口初始化

添加Channel ID

若已经使用通用接口进行初始化并设置了Channel,则可以忽略此步骤

你可以用Channel ID来标识App的推广渠道,作为推送消息时给用户分组的一个维度。设置方法如下,在Application Module的AndroidManifest.xml中的<application></application>标签下添加:

<meta-data
    android:name="UMENG_CHANNEL"
    android:value="Channel ID" />

请将"android:value"中的"Channel ID"替换为App的推广渠道。

说明:

  • 若在AndroidManifest.xml设置了Channel,则通用初始化方法UMConfigure.init的channel参数可以传null。
  • 若同时在AndroidManifest.xml和代码中设置了Channel,则以代码设置的为准。
  • 若在AndroidManifest.xml和代码里均没有设置,则使用Unknown作为Channel ID。
  • 你可以使用20位以内的英文和数字为渠道定名(不要使用纯数字)。
  • 每台设备仅识别首次安装激活的渠道。
  • PushSDK组件化版本删除了PushAgent类的setMessageChannel方法,如要使用代码设置Channel,请参考通用接口初始化

初始化PushSDK

注册推送服务

务必在工程的自定义Application类的 onCreate() 方法中开启推送服务,无论推送是否开启都需要调用此方法:

PushAgent mPushAgent = PushAgent.getInstance(this);

//注册推送服务,每次调用register方法都会回调该接口
mPushAgent.register(new IUmengRegisterCallback() {

    @Override
    public void onSuccess(String deviceToken) {
        //注册成功会返回device token
    }

    @Override
    public void onFailure(String s, String s1) {

    }
});

注意:

  • 请勿在调用register方法时做进程判断处理(主进程和channel进程均需要调用register方法才能保证长连接的正确建立)。
  • 若有需要,可以在Application的onCreate方法中创建一个子线程,并把mPushAgent.register这一行代码放到该子线程中去执行(请勿将PushAgent.getInstance(this)放到子线程中)。
  • device token是【友盟+】生成的用于标识设备的id,长度为44位,不能定制和修改。同一台设备上不同应用对应的device token不一样。
  • 如需手动获取device token,可以调用mPushAgent.getRegistrationId()方法(需在注册成功后调用)。

统计应用启动数据

在所有的Activity 的onCreate 方法或在应用的BaseActivityonCreate方法中添加:

PushAgent.getInstance(context).onAppStart();

注意:

  • 此方法与统计分析sdk中统计日活的方法无关!请务必调用此方法!

  • 如果不调用此方法,不仅会导致按照“几天不活跃条件”来推送失效,还将导致广播发送不成功以及设备描述红色等问题发生。可以只在应用的主Activity中调用此方法,但是由于SDK的日志发送策略,有可能由于主activity的日志没有发送成功,而导致未统计到日活数据。

设置通知栏图标

默认使用应用图标作为通知栏图标。为了提升展示效果和机型适配,推荐使用自定义通知栏图标

详见高级功能--自定义通知栏图标

混淆配置

如果App需要使用proguard进行混淆打包,请添加以下混淆代码:

-dontwarn com.taobao.**
-dontwarn anet.channel.**
-dontwarn anetwork.channel.**
-dontwarn org.android.**
-dontwarn org.apache.thrift.**
-dontwarn com.xiaomi.**
-dontwarn com.huawei.**

-keepattributes *Annotation*

-keep class com.taobao.** {*;}
-keep class org.android.** {*;}
-keep class anet.channel.** {*;}
-keep class com.umeng.** {*;}
-keep class com.xiaomi.** {*;}
-keep class com.huawei.** {*;}
-keep class org.apache.thrift.** {*;}

-keep class com.alibaba.sdk.android.**{*;}
-keep class com.ut.**{*;}
-keep class com.ta.**{*;}

-keep public class **.R$*{
   public static final int *;
}

#(可选)避免Log打印输出
-assumenosideeffects class android.util.Log {
   public static *** v(...);
   public static *** d(...);
   public static *** i(...);
   public static *** w(...);
 }

打包运行

将打包生成的apk文件安装到联网的测试设备上并打开(推荐使用真机进行调试)。

注意:

  • 若编译时报ta.utdid2.xxut.device.xx等冲突异常,请将项目工程的libs目录中的utdid4all-*.**这个jar文件删除,重新编译即可。

测试推送

添加测试设备

在【友盟+】消息推送服务后台http://push.umeng.com的“测试模式”中填写该设备的device token,将该设备添加为测试设备:

推送测试通知

在“测试模式”中推送通知。通知发送后会在系统通知栏收到并展示,同时通过响铃、振动或呼吸灯提醒用户。若在测试设备上收到通知,表明SDK集成成功。推送页面如下图所示:

说明:

  • APP收到通知后会展示在通知栏,开发者可以在【友盟+】后台指定用户点击通知后的操作,包括“打开应用”、“打开链接”、“打开指定页面(自身应用内的Activity)”、自定义行为(需自己实现方法,详见:高级功能-通知的展示及提醒-自定义通知打开动作)。
  • 如果没有收到通知,请参考FAQ中的处理方法。
  • 测试模式具体介绍: http://bbs.umeng.com/thread-8910-1-1.html

API对接(可选)

  1. 如果要使用API对接【友盟+】服务器来发送消息,需要在【友盟+】消息推送服务后台http://push.umeng.com填写服务器地址,进行白名单登记。
  2. 参考API文档中的格式发送测试消息。**需要填写正确的App Master Secret**。

高级功能

通知的展示及提醒

自定义通知打开动作

开发者可自定义用户点击通知栏时的后续动作。**自定义行为**的数据放在UMessage.custom字段。 在【友盟+】后台或通过API发送消息时,在“后续动作”中的“自定义行为”中输入相应的值或代码即可实现。

若开发者需要处理自定义行为,则可以重写方法dealWithCustomAction()。其中自定义行为的内容,存放在UMessage.custom中。请在自定义Application类中添加以下代码:

UmengNotificationClickHandler notificationClickHandler = new UmengNotificationClickHandler() {

    @Override
    public void dealWithCustomAction(Context context, UMessage msg) {
        Toast.makeText(context, msg.custom, Toast.LENGTH_LONG).show();
    }
};
mPushAgent.setNotificationClickHandler(notificationClickHandler);

注意:

  • 如果在Activity中调用此接口,若应用进程关闭,则设置的接口会无效。请参考: demo 应用代码
  • UmengNotificationClickHandler是在BroadcastReceiver中被调用,因此若需启动Activity,需为Intent添加Flag:Intent.FLAG_ACTIVITY_NEW_TASK,否则无法启动Activity。

自定义通知栏样式

在PushSDK里,UmengMessageHandler类负责处理消息,包括通知和自定义消息。其中,成员函数getNotification负责定义通知栏样式。若SDK默认的消息展示样式不符合开发者的需求,可通过覆盖该方法来自定义通知栏展示样式。**以下是demo里的示例代码:**

UmengMessageHandler messageHandler = new UmengMessageHandler() {

    @Override
    public Notification getNotification(Context context, UMessage msg) {
        switch (msg.builder_id) {
            case 1:
                Notification.Builder builder = new Notification.Builder(context);
                RemoteViews myNotificationView = new RemoteViews(context.getPackageName(), 
                    R.layout.notification_view);
                myNotificationView.setTextViewText(R.id.notification_title, msg.title);
                myNotificationView.setTextViewText(R.id.notification_text, msg.text);
                myNotificationView.setImageViewBitmap(R.id.notification_large_icon, 
                    getLargeIcon(context, msg));
                myNotificationView.setImageViewResource(R.id.notification_small_icon, 
                    getSmallIconId(context, msg));
                builder.setContent(myNotificationView)
                       .setSmallIcon(getSmallIconId(context, msg))
                       .setTicker(msg.ticker)
                       .setAutoCancel(true);

                return builder.getNotification();
            default:
                //默认为0,若填写的builder_id并不存在,也使用默认。
                return super.getNotification(context, msg);
        }
    }
};

mPushAgent.setMessageHandler(messageHandler);

具体介绍请参考文档 http://bbs.umeng.com/thread-9598-1-2.html

其中,msg.builder_id是服务器下发的消息字段,用来指定通知消息的样式。开发者可在【友盟+】Push网站上指定,默认值为0。

说明:

  • 每当有通知送达时,均会回调getNotification方法,因此可以通过监听此方法来判断通知是否送达。

通知免打扰模式

为免过度打扰用户,SDK默认在“23:00”到“7:00”之间收到通知消息时不响铃,不振动,不闪灯。如果需要改变默认的静音时间,可以使用以下接口:

public void setNoDisturbMode(int startHour, int startMinute, int endHour, int endMinute) 

例如:

mPushAgent.setNoDisturbMode(23, 0, 7, 0);

可以通过下面的设置,来关闭免打扰模式:

mPushAgent.setNoDisturbMode(0, 0, 0, 0);

默认情况下,同一台设备在1分钟内收到同一个应用的多条通知时,不会重复提醒,同时在通知栏里新的通知会替换掉旧的通知。可以通过如下方法来设置冷却时间:

mPushAgent.setMuteDurationSeconds(int seconds);

通知栏按数量显示

通知栏可以设置最多显示通知的条数,当有新通知到达时,会把旧的通知隐藏。

public void setDisplayNotificationNumber(int number);

例如设置通知栏最多显示两条通知(当通知栏已经有两条通知,此时若第三条通知到达,则会把第一条通知隐藏):

mPushAgent.setDisplayNotificationNumber(2);

说明:

  • 参数number可以设置为0~10之间任意整数。**当参数为0时,表示不合并通知。**
  • 该方法可以多次调用,以最后一次调用时的设置为准。

客户端控制通知到达响铃、震动、呼吸灯

有三种状态:

  • MsgConstant.NOTIFICATIONPLAYSERVER(服务端控制)
  • MsgConstant.NOTIFICATIONPLAYSDKENABLE(客户端允许)
  • MsgConstant.NOTIFICATIONPLAYSDKDISABLE(客户端禁止) > 服务端控制:通过服务端推送状态来设置客户端响铃、震动、呼吸灯的状态 > 客户端允许:不关心服务端推送状态,客户端都会响铃、震动、呼吸灯亮 > 客户端禁止:不关心服务端推送状态,客户端不会响铃、震动、呼吸灯亮

通过以下方法可以设置:

mPushAgent.setNotificationPlaySound(MsgConstant.NOTIFICATION_PLAY_SERVER); //声音
mPushAgent.setNotificationPlayLights(MsgConstant.NOTIFICATION_PLAY_SERVER);//呼吸灯
mPushAgent.setNotificationPlayVibrate(MsgConstant.NOTIFICATION_PLAY_SERVER);//振动 

自定义通知栏图标

如果在发送后台没有指定通知栏图标,SDK将使用本地的默认图标,其中,大图标默认使用:drawable下的umeng_push_notification_default_large_icon,小图标默认使用drawable下的umeng_push_notification_default_small_icon。若开发者没有设置这两个图标,则默认使用应用的图标(<application android:icon="@drawable/ic_launcher"></application>),请确保应用设置了默认图标。

若开发者在发送后台指定了图片的链接,则该链接将通过Message的img字段进行传输。当SDK接受到消息后,会先下载图片,下载成功后显示通知;若下载失败,会自动重试两次(总共下载3次);若仍失败,则采用默认图片进行显示。

如果使用API方式( API文档)来发送消息, 可以指定icon 和largeIcon 字段,分别对应状态栏图标和通知栏下拉之后左侧大图标id ([R.drawable].icon), (请填写对应图片文件名,不包含扩展名) 请参考**API文档**。另外,MIUI暂时无法支持自定义通知栏图标,若开发者有需求,也可通过自定义通知栏样式来解决。具体介绍请参考文档:http://bbs.umeng.com/thread-9686-1-1.html

最佳实践:

drawable目录下,放置两张图片,分别命名为umeng_push_notification_default_large_iconumeng_push_notification_default_small_icon

  • 小图标smallIcon要求为48*48像素,图片各边至少留一个像素的透明,图标主体使用颜色,背景均使用透明。
  • 大图标largeIcon 要求为64*64像素。

说明:

  • 对于超高分辨率的机型的适配,可以适当提高图标的尺寸
  • 通知图标的显示有系统适配问题,有些手机系统,设置了通知的大图标,依然会使用应用图标;还有可能通知的Ticker图标显示不完全,只是部分显示。 关于通知的系统适配问题,需要开发者根据不同手机系统做相应的适配工作。

自定义通知栏声音

如果在发送后台没有指定通知栏的声音,SDK将采用本地默认的声音,即在res/raw/下的umeng_push_notification_default_sound。若无此文件,则默认使用系统的Notification声音。

注意:

  • 若需要在线配置声音,则需先将与配置的声音文件放置在res/raw下,然后自发送后台指定声音的id,即R.raw.[sound]里的sound。

应用在前台时否显示通知

如果应用在前台的时候,开发者可以自定义配置是否显示通知,默认情况下,应用在前台是显示通知的。 开发者更改前台通知显示设置后,会根据更改生效。

若要不显示前台通知,调用接口如下:

mPushAgent.setNotificaitonOnForeground(false);

注意:

  • 此方法请在mPushAgent.register方法之前调用。

自定义消息

自定义消息,是指发送后不会在系统通知栏展现,SDK将消息体传给第三方应用后需要开发者写展现代码才能看到的推送形式。 【友盟+】消息推送SDK不对该消息进行展示和提醒,消息内容全部都传递给应用处理。

后台页面如下图所示:

若开发者要使用自定义消息,则需重在自定义Application类的onCreate() 中重写dealWithCustomMessage()方法,自定义消息的内容存放在UMessage.custom字段里。代码如下所示:

UmengMessageHandler messageHandler = new UmengMessageHandler(){

    @Override
    public void dealWithCustomMessage(final Context context, final UMessage msg) {
        new Handler(getMainLooper()).post(new Runnable() {

            @Override
            public void run() { 
                // 对于自定义消息,PushSDK默认只统计送达。若开发者需要统计点击和忽略,则需手动调用统计方法。
                boolean isClickOrDismissed = true;
                if(isClickOrDismissed) {
                    //自定义消息的点击统计
                    UTrack.getInstance(getApplicationContext()).trackMsgClick(msg);
                } else {
                    //自定义消息的忽略统计
                    UTrack.getInstance(getApplicationContext()).trackMsgDismissed(msg);
                }
                Toast.makeText(context, msg.custom, Toast.LENGTH_LONG).show();
            }
        });
    }

};

mPushAgent.setMessageHandler(messageHandler);

注意:

  • 如果在Activity中调用此接口,若应用进程关闭, 则设置的接口将会无效。 请参考: demo 应用代码

设置用户标签(tag)

您可以为用户加上标签,方便推送时按照标签来筛选。例如:

mPushAgent.getTagManager().add(new TagManager.TCallBack() {

    @Override
    public void onMessage(final boolean isSuccess, final ITagManager.Result result) {
        //isSuccess表示操作是否成功         
    }

}, "movie", "sport");

目前每个用户tag限制在1024个, 每个tag 最大256个字符。

注意:

tag名称请不要加入URL Encode等变换处理,请使用原生字符串。

  • 添加标签

**在原有标签基础上增加新标签。**

mPushAgent.getTagManager().add(new TagManager.TCallBack() {

    @Override
    public void onMessage(final boolean isSuccess, final ITagManager.Result result) {

    }

}, String... tags);

  • 删除标签

**将之前添加的标签中的一个或多个删除。**

mPushAgent.getTagManager().delete(new TagManager.TCallBack() {

    @Override
    public void onMessage(final boolean isSuccess, final ITagManager.Result result) {

    }

}, String... tags);

  • 更新标签

**删除之前添加的所有标签,重置为新标签。**

mPushAgent.getTagManager().update(new TagManager.TCallBack() {

    @Override
    public void onMessage(final boolean isSuccess, final ITagManager.Result result) {

    }

}, String... tags);

  • 清除所有标签

**删除之前添加的所有标签。**

mPushAgent.getTagManager().reset(new TagManager.TCallBack() {

    @Override
    public void onMessage(boolean isSuccess, ITagManager.Result result) {

    }

});

  • 获取服务器端的所有标签
mPushAgent.getTagManager().list(new TagManager.TagListCallBack() {

    @Override
    public void onMessage(boolean isSuccess, List<String> result) {

    }

});

设置用户别名(alias)

如果你的应用有自有的用户id体系,可以在SDK中通过Alias字段上传自有用户id,按用户id向用户推送消息。用户id可以是你的应用为每个用户自动生成的唯一id,也可以是用户采用第三方平台登录时从第三方平台获取到的用户id。要设置用户ID,可以使用以下接口。

设置用户id和device_token的一对多的映射关系:

mPushAgent.addAlias("zhangsan@sina.com", ALIAS_TYPE.SINA_WEIBO, new UTrack.ICallBack() {

    @Override
    public void onMessage(boolean isSuccess, String message) {

    }

});

设置用户id和device_token的一一映射关系,确保同一个alias只对应一台设备:

mPushAgent.addExclusiveAlias("zhangsan@sina.com", ALIAS_TYPE.SINA_WEIBO, 

new UTrack.ICallBack() {

    @Override
    public void onMessage(boolean isSuccess, String message) {

    }

});

若是要移除用户id,可调用以下接口:

mPushAgent.removeAlias("zhangsan@sina.com", ALIAS_TYPE.SINA_WEIBO, new UTrack.ICallBack(){

    @Override
    public void onMessage(boolean isSuccess, String message) {

    }

});

说明:

  • 若要使用新的alias,请先调用deleteAlias接口移除掉旧的alias,再调用addAlias添加新的alias,代码如下所示:
mPushAgent.removeAlias("old@sina.com", ALIAS_TYPE.SINA_WEIBO, new UTrack.ICallBack() {

   @Override

   public void onMessage(boolean isSuccess, String message) {

   }

});

mPushAgent.addAlias("new@sina.com", ALIAS_TYPE.SINA_WEIBO, new UTrack.ICallBack() {

   @Override

   public void onMessage(boolean isSuccess, String message) {

   }

});

  • 回传alias时需要指定该alias对应的类型(alias type),例如:自有id、新浪微博、腾讯微博、豆瓣等。

  • 每个类型的alias同时只能存在一个,同一个类型的新alias会覆盖旧alias。

  • alias名称请不要使用URLEncode等变换处理,请使用原生字符串。

  • alias的绑定是需要获取到device_token为前提的,最好是在注册即enable的回调接口中进行alias的绑定,此时可以保证获取到device_token。

  • 请参考alias的具体说明 http://bbs.umeng.com/thread-9564-1-1.html

自定义参数

说明:

  • Push SDK 默认处理方式里,自定义参数均以字符串的形式进行传递。

开发者在推送通知和自定义消息时,可以添加自定义参数,【友盟+】Push SDK会将自定义参数的内容传递给APP进行处理。

这些自定义参数将通过extra字段发送到客户端,下面是发送至客户端的JSON字符串。

{
    "msg_id": "uu481201399440513912",
    "display_type": "notification",
    "alias": "",
    "random_min": 0,
    "body": {
        "title": "测试自定义参数",
        "ticker": "测试自定义参数",
        "text": "无",
        "after_open": "go_app",
        "url": "",
        "activity": "",
        "custom": "",
        "play_vibrate": "true",
        "play_sound": "true",
        "play_lights": "true"
    },
    "extra": {
        "key1": "value1",
        "key2": "value2"
    }
}

方法一:

开发者可以通过SDK提供的回调方法来获取自定义参数。例如,重写UmengMessageHandler类中的getNotification(Context context, UMessage msg)方法,此方法会在通知展示到通知栏时回调。另外,也可重写UmengNotificationClickHandler类中的dealWithCustomAction(Context context, UMessage msg)方法,此方法会在通知被点击时回调。参数中的UMessage对象即为消息体,可在msg.extra获取到自定义参数.

for (Entry entry : msg.extra.entrySet()) {

    String key = entry.getKey();
    String value = entry.getValue();
    ...

}

方法二:

若开发使用Push SDK默认处理通知消息,则自定义参数将会通过Intent传递给相应的Activity。以下是SDK将参数放入Intent的代码:

private Intent addMessageToIntent(Intent intent, UMessage msg) {

    if (intent == null || msg == null || msg.extra == null)
        return intent;

    for (Entry<String, String> entry : msg.extra.entrySet())
    {
        String key = entry.getKey();
        String value = entry.getValue();
        if (key!=null)
            intent.putExtra(key, value);
    }
    return intent;

}

开发者可以在相应的Activity中的onResume()方法内通过以下代码获得传递的参数:

Bundle bun = getIntent().getExtras();

if (bun != null) {

    Set<String> keySet = bun.keySet();
    for (String key : keySet) {
        String value = bun.getString(key);
        ...
    }

}

同时需要将该ActivitylaunchMode设置为android:launchMode="singleTask",并重写onNewIntent方法:

@Override

protected void onNewIntent(Intent intent) {

    super.onNewIntent(intent);
    setIntent(intent);

}

自定义资源包名

Android Studio开发工具是基于gradle的配置方式,资源文件的包和应用程序的包是可以分开的,为了正确的找到资源包名,为开发者提供了自定义的设置资源包的接口。

当资源包名和应用程序包名不一致时,调用设置资源包名的接口:

mPushAgent.setResourcePackageName(String packageName);

是否检查集成配置文件

为了便于开发者更好的集成配置文件,我们提供了对于AndroidManifest配置文件的检查工具,可以自行检查开发者的配置问题。SDK默认是不检查集成配置文件的,在线上版本请关掉该配置检查,或者去掉这行检查代码(sdk默认是不做该项检查的)。

自定义检查集成配置文件的接口如下:

mPushAgent.setPushCheck(boolean pushCheck);

关闭推送

注销回调:IUmengCallback;当关闭【友盟+】推送时,可调用以下代码(请在Activity内调用):

mPushAgent.disable(new IUmengCallback() {

    @Override
    public void onSuccess() {

    }

    @Override
    public void onFailure(String s, String s1) {

    }

});

若调用关闭推送后,想要再次开启推送,则需要调用以下代码(请在Activity内调用):

mPushAgent.enable(new IUmengCallback() {

    @Override
    public void onSuccess() {

    }

    @Override
    public void onFailure(String s, String s1) {

    }

});

支持多包名

若一个APP针对不同渠道有不同的包名,则可通过开通多包名支持一个AppKey对应多个包名发送消息。如下图所示:

注意:

  • 该功能仅在PushSDK V1.4.0及以后版本中支持。
  • 如果同一设备安装同一应用的不同包名的多个安装包,只有最后安装的应用可以正常收到推送消息。
  • 主包名指的是默认的包名或者大部分渠道用到的包名,开发者自行决定哪个是主包名即可。另外,如果之前已经填写过包名,那么申请开通多包名之后,之前已经填写过的包名就会默认成为主包名。
  • 修改包名后,Eclipse用户需注意,AndroidManifest.xml文件中相应的地方也需要进行包名替换。
  • 多包名的具体用法,请参考 http://bbs.umeng.com/thread-9613-1-1.html

完全自定义处理

若开发者需要实现对消息的完全自定义处理,则可以继承 UmengMessageService, 实现自己的Service来完全控制达到消息的处理。使用完全自定义处理后,PushSDK只负责下发消息体且只统计送达数,展示逻辑需由开发者自己写代码实现,点击数和忽略数需由开发者调用UTrack类的trackMsgClick和trackMsgDismissed方法进行统计。

1、实现一个类,继承 UmengMessageService, 重写onMessage(Context context, Intent intent) 方法参考 demo 应用中MyPushIntentService。代码如下:

public class MyPushIntentService extends UmengMessageService {

    private static final String TAG = MyPushIntentService.class.getName();

    @Override
    public void onMessage(Context context, Intent intent) {
        try {
            //可以通过MESSAGE_BODY取得消息体
            String message = intent.getStringExtra(AgooConstants.MESSAGE_BODY);
            UMessage msg = new UMessage(new JSONObject(message));
            UmLog.d(TAG, "message=" + message);      //消息体
            UmLog.d(TAG, "custom=" + msg.custom);    //自定义消息的内容
            UmLog.d(TAG, "title=" + msg.title);      //通知标题
            UmLog.d(TAG, "text=" + msg.text);        //通知内容
            // code  to handle message here
            // ...

            // 对完全自定义消息的处理方式,点击或者忽略
            boolean isClickOrDismissed = true;
            if (isClickOrDismissed) {
                //完全自定义消息的点击统计
                UTrack.getInstance(getApplicationContext()).trackMsgClick(msg);
            } else {
                //完全自定义消息的忽略统计
                UTrack.getInstance(getApplicationContext()).trackMsgDismissed(msg);
            }

            // 使用完全自定义消息来开启应用服务进程的示例代码
            // 首先需要设置完全自定义消息处理方式
            // mPushAgent.setPushIntentServiceClass(MyPushIntentService.class);
            // code to handle to start/stop service for app process
            JSONObject json = new JSONObject(msg.custom);
            String topic = json.getString("topic");
            UmLog.d(TAG, "topic=" + topic);
            if (topic != null && topic.equals("appName:startService")) {
                // 在【友盟+】portal上新建自定义消息,自定义消息文本如下
                //{"topic":"appName:startService"}
                if (Helper.isServiceRunning(context, NotificationService.class.getName()))
                    return;
                Intent intent1 = new Intent();
                intent1.setClass(context, NotificationService.class);
                context.startService(intent1);
            } else if (topic != null && topic.equals("appName:stopService")) {
                // 在【友盟+】portal上新建自定义消息,自定义消息文本如下
                //{"topic":"appName:stopService"}
                if (!Helper.isServiceRunning(context,NotificationService.class.getName()))
                    return;
                Intent intent1 = new Intent();
                intent1.setClass(context, NotificationService.class);
                context.stopService(intent1);
            }
        } catch (Exception e) {
            UmLog.e(TAG, e.getMessage());
        }
    }

}

2、在AndroidManifest.xml 中声明:

<!-- 请填写实际的类名,下面仅是示例代码-->
<service android:name="【应用包名】.MyPushIntentService" />

3、在自定义Application类的onCreate方法中调用:

mPushAgent.setPushIntentServiceClass(MyPushIntentService.class);

说明:

  • 打开消息行为的数据统计:默认情况下,SDK将用户点击通知栏的行为定义为“打开消息”。使用PushIntentService自定义处理后,SDK只能记录消息送达的数据,无法记录消息打开的数据。要记录消息打开的数据,你可以在应用中定义打开消息的语义,并使用以下接口向服务器发送消息打开的数据以便统计:UTrack.getInstance(context).trackMsgClick(msg);

  • 也可以根据需要对自定义处理的消息进行忽略统计:UTrack.getInstance(context).trackMsgDismissed(msg);

  • 如果需要打开Activity,需为Intent添加Flag:Intent.FLAG_ACTIVITY_NEW_TASK,否则无法启动Activity。

  • 如果使用了完全自定义处理后,又想恢复成【友盟+】的默认的处理,可以通过如下设置来恢复mPushAgent.setPushIntentServiceClass(null);;

消息推送实现自动更新

注意:

  • 由于自动更新组件作出策略调整,若开发者想通过消息推送SDK实现自动更新功能,建议采用推送应用下载链接的形式来实现。可将链接设置为官网的APK下载链接或第三方应用市场下载链接。此方法可确保开发者避开应用市场、系统厂商、运营商等多方对自动更新服务的限制,进而成功实现用消息推送实现自动更新功能。具体参考下图:

除已提供示例外,开发者可通过自定义更新通知的展示方式来实现不同的展示效果。

小米Push通道使用教程

创建应用

打开dev.xiaomi.com,点击右上角进入登录页面。进入登陆界面后,输入帐号、密码并点击登陆后进入小米开放平台。

点击移动开发服务中的消息推送按钮进入推送后台。

点击“创建手机/平板应用”按钮进入创建新应用界面。

正确创建应用后,获取小米push的Appkey和AppSecret。

配置小米Push的AppSecret

在【友盟+】新版推送后台http://message.umeng.com的【应用管理】【应用信息】里的x-secret处填上小米Push的AppSecret,并保存。

小米Push初始化

在Application类的onCreate方法中添加:

MiPushRegistar.register(final Context context, final String XIAOMI_ID, final String XIAOMI_KEY);

注册成功后会在tag:MiPushBroadcastReceiver下面打印log: onCommandResult is called. regid= xxxxxxxxxxxxxxxxxxxxxxx

接收到小米消息则会打印log: onReceiveMessage,msg= xxxxxxxxxxxxxxxxxxxxxxx

注意:

  • 仅在小米MIUI设备上生效。
  • 集成小米push的版本暂不支持多包名。

使用小米弹窗功能

小米对后台进程做了诸多限制。若小米后台清理进程,channel进程被清除,将接收不到推送。为了增加推送的送达率,可选择接入小米托管弹窗功能。通知将由小米系统托管弹出,点击通知栏将跳转到指定的Activity。该Activity需继承自UmengNotifyClickActivity,同时实现父类的onMessage方法,对该方法的intent参数进一步解析即可,该方法异步调用,不阻塞主线程。示例如下:

public class MipushTestActivity extends UmengNotifyClickActivity {

    private static String TAG = MipushTestActivity.class.getName();

    @Override
    protected void onCreate(Bundle bundle) {
        super.onCreate(bundle);
        setContentView(R.layout.activity_mipush);
    }

    @Override
    public void onMessage(Intent intent) {
        super.onMessage(intent);  //此方法必须调用,否则无法统计打开数
        String body = intent.getStringExtra(AgooConstants.MESSAGE_BODY);
        UmLog.i(TAG, body);
        Message message = Message.obtain();
        message.obj = body;
        handler.sendMessage(message);
    }
}

在【友盟+】推送后台发送通知时,勾选**若设备离线转为系统通道下发**,并填写Activity的完整包路径(该Activity需继承自UmengNotifyClickActivity)。

**注意:**

  • 使用小米系统通道下发的消息,将只能被统计到消息的【打开数】,而该条消息的【收到数】、【忽略数】将无法被统计到。
  • 若要使用小米系统通道下发通知,则**通知的标题(title)不允许全是空白字符且长度小于50,通知的内容(text)不允许全是空白字符且长度小于128(通知的标题和内容必填,一个中英文字符均计算为1)**。
  • 在调用API接口实现推送消息时,如果需要使用小米弹窗,需添加:
"mipush":true
"mi_activity":"com.umeng.message.example.MipushTestActivity"        //此处请填写Activity完整包路径

API接口添加位置参考:

{
"appkey": "", 
"mi_activity": "com.umeng.message.example.MipushTestActivity"
"mipush": true,
"timestamp": 1473225266373,
"production_mode": "true",
"type": "unicast", 
"device_tokens": "", 
"payload":
    {"body": 
       {"text": "from pa36a", 
        "after_open": "go_app", 
        "ticker": "Hello World2", 
        "title": "listcastpa43"
       }, 
     "display_type": "notification", 
    }
}

华为Push通道使用教程

创建应用

登录华为开发者联,http://developer.huawei.com/cn/consumer/devunion/ui/server/PUSH.html

创建应用。

填写应用基本信息。

点击“+”号图标添加推送(Push)权益。

填写推送权限配置信息。

在应用管理中,点击应用名称,查看应用的app id和app secret。

配置华为Push的AppID和Secret

在【友盟+】新版推送后台http://message.umeng.com的【应用管理】【应用信息】里的华为AppID和华为Secret处填上华为Push的app id和app secret。

华为Push初始化

在Application类的onCreate方法中添加:

HuaWeiRegister.register(final Context context);


注册成功后会在tag:HuaWeiReceiver下面打印log: 获取token成功,token= xxxxxxxxxxxxxxxxxxxxxxx

接收到华为消息则会打印log: HuaWeiReceiver,content= xxxxxxxxxxxxxxxxxxxxxxx

注意:

  • 仅在华为设备上生效。
  • 集成华为push的版本暂不支持多包名。
  • 若需要使用华为系统级通道,则需在华为设备上的【手机管家】App中,开启应用的“自启动权限”。

服务端API文档

  1. 如果要使用API对接【友盟+】服务器来发送消息,需要在【友盟+】消息推送服务后台(http://push.umeng.com )填写服务器地址,进行白名单登记。

  2. 参考API文档中的格式发送测试消息。需要填写正确的App Master Secret。