友盟+搜索

{{errorMsg}}

版本号:v3.1.1

U-Push SDK将不再独立更新。如您有使用聚合其他平台(小米、华为等)推送通道版本的需求,请下载并集成组件化U-Push v3.3.0x SDK

说明:如需参考v2.8.1-x sdk集成文档,请参考U-Push v2.8.1 集成文档

友盟+消息推送组件帮助您实时的推送消息给用户。

版本更新:

  1. 最新适配Android 7.1.1系统;
  2. 优化定制化系统平台稳定性;
  3. 深度优化Demo App。
  4. 适配更多最新型号设备。

开发运行环境:

  1. Android Studio推荐使用v2.0及以上版本。
  2. Eclipse的ADT插件推荐使用v23.0.2及以上版本。
  3. 消息推送SDK 支持Android 3.0 (API 11)及以上系统。

升级指南:

低版本PushSDK升级3.1.1版本攻略

快速体验

创建应用

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

注意: 即使应用名称相同,Android版和iOS版仍是属于不同平台的两个应用,无法共用一个Appkey,需要分开注册。

替换Appkey和Umeng Message Secret

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

如下图:

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

打包运行

将Demo安装到联网的测试设备上并打开。

Demo效果如下图:

推送通知

添加测试设备

在友盟+消息推送服务后台( 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 上使用应用包名创建应用,获取应用对应的AppKey和Umeng Message Secret。

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

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

导入PushSDK

  1. 把下载的zip文件解压缩(解压后的文件路径不能有中文)。
  2. 把解压缩后得到的目录下的PushSDK当做Module导入到自己的工程,如下图所示:

注意:

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

配置Appkey和Secret

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

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

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

添加Channel ID

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

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

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

或者,通过调用以下代码来设置推广渠道。

mPushAgent.setMessageChannel();

说明:

  • 若同时在AndroidManifest.xml和代码设置了Channel,则以代码设置的为准。
  • 若在AndroidManifest.xml和代码里均没有设置,则使用Unknown作为Channel ID。
  • 你可以使用20位以内的英文和数字为渠道定名(不要使用纯数字)。
  • setMessageChannel函数需在调用注册接口前进行设置。
  • 每台设备仅识别首次安装激活的渠道。
  • 友盟+消息推送可以和友盟+统计分析共用AndroidManifest.xml中的"UMENG_CHANNEL"字段。
  • 即使在统计分析SDK代码中设置了Channel,也需要重新设置消息推送SDK的Channel。

配置build.gralde

  1. 在Application Module的build.gradle文件的dependencies下添加compile project(':PushSDK')
  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)推荐使用1.5.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方法才能保证长连接的正确建立)。
  • 若有需要,可以在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.xx或ut.device.xx等冲突异常,请将PushSDK的libs目录中的utdid4all这个jar文件删除,重新编译即可。
  • PushSDK的调试日志默认是输出的,如果app对外正式发布,建议调用mPushAgent.setDebugMode(false)关闭日志输出。

测试推送

添加测试设备

在友盟+消息推送服务后台( 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. 把解压缩后得到的目录下的PushSDK当做Library导入到自己的工程。
  3. 主工程依赖PushSDK。

注意:

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

配置PushSDK

  1. 把PushSDK目录下的AndroidManifest.xml中的${applicationId}替换成为自己项目的包名。
  2. 右键单击PushSDK的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

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

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

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

初始化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.xx或ut.device.xx等冲突异常,请将PushSDK的libs目录中的utdid4all这个jar文件删除,重新编译即可。
  • PushSDK的调试日志默认是输出的,如果app对外正式发布,建议调用mPushAgent.setDebugMode(false)关闭日志输出。

测试推送

添加测试设备

在友盟+消息推送服务后台( 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"> )。 请确保应用设置了默认图标。

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

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

最佳实践:

  • 小图标icon 要求为24dp*24dp 的图标, 或 24*24pxdrawable-mdpi
  • 大图标largeIcon 要求为 64*64 dp 的图标. 对应64*64pxdrawable-mdpi 下, 128*128pxdrawable-xhdpi 中。

通常情况下, 只需要两个图标, 一个24*24px 的小图标(对于超高分辨率的机型的适配,可以适当提高小图标的尺寸,例如48px*48px),一个64*64px 的大图标, 都置于drawable-xhdpi 文件夹下。 制作图标时, 注意图片各边留一个像素的透明。 建议使用黑白图标。 具体参考 Google 官方建议

说明:

  • 通知图标的显示有系统适配问题,有些手机系统,设置了通知的大图标,依然会使用应用图标;还有可能通知的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<String, String> 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) {

    }
});

支持多包名

说明:

  • 该功能仅在Push SDK V1.4.0及以后版本中支持。

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

注意:

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

完全自定义处理

若开发者需要实现对消息的完全自定义处理,则可以继承 UmengMessageService, 实现自己的Service来完全控制达到消息的处理。

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中调用。

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下载链接或第三方应用市场下载链接。此方法可确保开发者避开应用市场、系统厂商、运营商等多方对自动更新服务的限制,进而成功实现用消息推送实现自动更新功能。具体参考下图:

消息推送实现自动更新1

消息推送实现自动更新2

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

实时地理位置推送(Beta)

实时地理位置推送:实现对用户划定区域内实时人群推送消息。

注意:

此功能仅适用于Android 2.8.1L_Beta版本sdk。只有在集成Android 2.8.1L_Beta版本sdk后,U-push后台才会展示实时地理位置推送功能。

实时地理位置推送

  • 进入区域:消息有效期内,对进入热点区域的用户推送消息;
  • 离开区域:消息有效期内,对离开热点区域的用户推送消息;
  • 附近区域:消息有效期内,对 进入 热点区域周边(不含热点区域)xx米内用户推送消息。

设置实时地理位置推送发送频率,可选范围为2秒/次 ~ 30分钟/次。若不调用该方法,则默认10分钟发送一次地理位置信息:

mPushAgent.setLocationInterval(int seconds);

开启实时地理位置推送,覆盖在指定地理区域内的用户:

mPushAgent.startLBS();

停止实时地理位置推送,调用该方法后,SDK不再发送地理位置信息:

mPushAgent.stopLBS();

应用内消息

注意:该功能目前需集成v3.1.0a版本SDK方可使用。

全屏消息

全屏消息是App首次启动打开进入的页面,以全屏图片的形式展示。如下图所示:

配置默认图片

1、在主工程的values目录下的styles.xml文件中添加如下代码,并在drawable目录下放置一张名为umeng_push_default_splash_bg的默认图片(推荐1920*1080分辨率)。

<style name="Theme_Umeng_Push_Splash" parent="android:Theme.NoTitleBar.Fullscreen">
<item name="android:windowBackground">@drawable/umeng_push_default_splash_bg</item>
</style>

2、新建一个Activity,继承自UmengSplashMessageActivity,重写onCustomPretreatment方法,并设置全屏消息默认跳转Activity的路径,例如:

public class SplashTestActivity extends UmengSplashMessageActivity {
  @Override
  public boolean onCustomPretreatment() {
     InAppMessageManager mInAppMessageManager = InAppMessageManager.getInstance(this);
     //设置应用内消息为Debug模式
     mInAppMessageManager.setInAppMsgDebugMode(true);
     //参数为Activity的完整包路径,下面仅是示例代码,请按实际需求填写
     mInAppMessageManager.setMainActivityPath("com.umeng.message.example.MainActivity");
     return super.onCustomPretreatment(); 
  }
}

说明:

onCustomPretreatment方法默认的返回值为false,返回false则会走全屏消息的默认逻辑。若开发者在全屏消息的Activity里有动态申请权限的需求,则可以在onCustomPretreatment内进行处理,并return true,则全屏消息逻辑不会继续执行。

3、在主工程的AndroidManifest.xml中的<application>标签下注册Activity,并将其配置为App首次启动打开的Activity,theme设置为步骤1所写的Theme_Umeng_Push_Splash,例如:

<activity
      android:name="com.umeng.message.example.SplashTestActivity"
      android:screenOrientation="portrait"
      android:theme="@style/Theme_Umeng_Push_Splash">
      <intent-filter>
           <action android:name="android.intent.action.MAIN" />

           <category android:name="android.intent.category.LAUNCHER" />
      </intent-filter>
</activity>

说明:

  • 生产模式请求服务器的最小间隔是30分钟,测试模式的最小间隔是1秒。
  • 全屏消息默认的逻辑为显示2s默认图片,若在2s内请求到全屏消息,则展示全屏消息,否则就跳转到开发者设置的页面。
  • 全屏消息的图片会自动缓存,并在有新消息到来时,删除旧消息的缓存。

使用方法

  • 在【消息列表】中选择【应用内消息】,并新建消息。

  • 按要求填写【通知描述】【样式选择】【后续动作】【目标人群】【展示条件】后,点击创建通知,唤出二次确认对话框。

  • 确认本次消息详情及预览样式后,即可点击【发送】。

  • 插屏消息

    插屏消息是在App页面之上弹出的图片消息。如下图所示:

    展示插屏消息

    在要展示的页面中调用如下方法:

    InAppMessageManager.getInstance(Context context).showCardMessage(Activity activity, 
           String label, IUmengInAppMsgCloseCallback callback);
    
    

    例如:

    InAppMessageManager.getInstance(this).showCardMessage(this, "main", 
           new IUmengInAppMsgCloseCallback() {
                 //插屏消息关闭时,会回调该方法
                 @Override
                 public void onColse() {
                      UmLog.i(TAG, "card message close");
            }
    });
    
    

    说明:

    • label是插屏消息的标签,用来标识该消息。
    • 客户端需先调用showCardMessage,把label发送到服务器,之后U-Push后台【展示位置】才会出现可选lable。
    • 以label为单位,生产模式请求服务器的最小间隔是30分钟,测试模式的最小间隔是1秒。
    • 插屏消息的图片会自动缓存,并在有新消息到来时,删除旧消息的缓存。
    • 注意:安装到设备上后,每个版本(versionCode)的App最多打10个标签

    使用方法

  • 在【消息列表】中选择【应用内消息】,并新建消息。

  • 按要求填写【通知描述】【样式选择】【展示位置】【后续动作】【目标人群】【展示条件】后,点击创建通知,唤出二次确认对话框。

  • 确认本次消息详情及预览样式后,即可点击【发送】。