友盟集成

http://dev.umeng.com/push/android/170集成文档

注意集成包名

appkey 以及Umeng Message Secret要填写申请的否则会注册不成功

1.  Android 消息推送(Message) SDK 集成指南

1.1  版本: v1.7.0

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

注意

消息推送SDK 支持Android 2.2 (API 8)及以上系统。建议在编译和混淆时引用最新版本Android SDK (17+)，因为Message SDK 条件使用了一些android-8 以上的API。对于Android 2.2 以下的系统， 消息推送组件不工作，但不影响应用本身功能的正常使用。

集成SDK之前， 请在 http://message.umeng.com 创建应用，获取应用对应的AppKey和Umeng Message Secret。

1.2   导入SDK所需jar包

下载最新版SDK的zip包，将其中的libs 文件夹合并到本地工程libs子目录下，再在Eclipse里面刷新一下工程。

注意

• Eclipse ADT 17 以下版本用户，可以使用老方式添加工程引用。 Eclipse用户鼠标右键工程根目录，选择Properties -> Java Build Path -> Libraries，然后点击Add External JARs... 选择指向jar的路径，点击OK，即导入成功。 如果引用过程中出现问题， 可以参考Dealing with dependencies in Android projects.

• Android Studio 以及Gradle 用户请参考如何引用第三方类库说明， 暂不提供 maven 支持。

• 本SDK需要最新版本的 android-support-v4.jar 支持包。请在工程中添加 android-support-v4.jar 支持包。 关于v4 支持包说明， 请参考 http://developer.android.com/tools/support-library/features.html#v4 .

1.3   使用SDK包中的Demo进行调试（可选）

1. 导入SDK包中Demo的代码到Eclipse。
2. 用添加应用时获得的AppKey和Umeng Message Secret替换掉Demo中默认的AppKey和Umeng Message Secret。
3. 用添加应用时填写的包名(多包名时根据需要填写其中一个)替换Demo的包名（com.umeng.message.example）。包括：
   • AndroidManifest.xml文件中的"package"字段。
   • AndroidManifest.xml文件中的<application>标签下与消息推送相关的组件包名。
   • Eclipse里的包名。
4. 重新打包Demo。将Demo的apk包安装到测试设备上并打开。
5. 参照步骤4.3的说明，给该设备发送测试消息。

1.4   配置AndroidManifest.xml

1.4.1   添加权限

在<manifest>标签下：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="android.permission.WRITE_SETTINGS" />
<!--【可选】如果需要设置前台是否显示通知，需要设置这个权限-->
<uses-permission android:name="android.permission.GET_TASKS" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

说明

• 下面两个权限为消息推送SDK V1.2.3版本中添加的权限，新版中已经不需要这个权限。

    
    <uses-permission android:name="android.permission.REORDER_TASKS" />

1.4.2  添加组件

在<application>标签下：

注意

添加组件时需要将【应用包名】替换为你自己应用的包名。

<receiver
    android:name="com.umeng.message.NotificationProxyBroadcastReceiver"
    android:exported="false" >
</receiver>
<receiver android:name="com.umeng.message.RegistrationReceiver" >
    <intent-filter>
        <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
    </intent-filter>
    <intent-filter>
        <action android:name="android.intent.action.PACKAGE_REMOVED" />

        <data android:scheme="package" />
    </intent-filter>

 
    <intent-filter>
        <action android:name="android.intent.action.BOOT_COMPLETED" />
    </intent-filter>

</receiver>
<receiver android:name="com.umeng.message.UmengBroadcastReceiver" >
    <intent-filter>
        <action android:name="org.agoo.android.intent.action.RECEIVE" />
    </intent-filter>
    <intent-filter>
        <action android:name="【应用包名】.intent.action.COMMAND" />
    </intent-filter>
    <intent-filter>
        <action android:name="org.agoo.android.intent.action.RE_ELECTION_V2" />
    </intent-filter>
</receiver>
<receiver android:name="com.umeng.message.BootBroadcastReceiver" >
    <intent-filter>
       <action android:name="android.intent.action.BOOT_COMPLETED" />
   </intent-filter>
</receiver>

可以根据需要自行设置 android:label 中的服务名 ：
<service
    android:name="com.umeng.message.UmengService"
   android:label="PushService" 
    android:exported="true" 
    android:process=":pushService_v1" >

    <intent-filter>
        <action android:name="【应用包名】.intent.action.START" />
    </intent-filter>
    <intent-filter>
        <action android:name="【应用包名】.intent.action.COCKROACH" />
    </intent-filter>
    <intent-filter>
        <action android:name="org.agoo.android.intent.action.PING" />
    </intent-filter>
</service>
<service
    android:name="org.android.agoo.service.ElectionService"
    android:exported="true"
    android:process=":pushService_v1" >
    <intent-filter>
        <action android:name="org.agoo.android.intent.action.ELECTION_V2" />
    </intent-filter>
</service>
<service android:name="com.umeng.message.UmengIntentService" />
<!-- V1.3.0添加的service，负责下载通知的资源 -->
<service android:name="com.umeng.message.UmengDownloadResourceService" />

1.4.3   添加 AppKey 和 Umeng Message Secret

在<application>标签下：

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

说明

请在http://message.umeng.com创建应用，获取应用对应的AppKey和Umeng Message Secret。

1.4.4   添加Channel ID

你可以用Channel ID来标识APP的推广渠道，作为推送消息时给用户分组的一个维度。设置方法如下：

在<application>标签下：

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

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

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

mPushAgent.setMessageChannel();

说明

• 若同时在AndroidManifest.xml和代码设置了MessageChannel，则以代码设置的为准。
• 若在AndroidManifest.xml和代码里均没有设置，则使用Unknown作为Channel ID。
• 你可以使用20位以内的英文和数字为渠道定名（不要使用纯数字）。
• 友盟消息推送可以和友盟统计分析共用一个"Channel ID"字段。
• 你可以使用友盟渠道打包工具，一次生成多个渠道包。

1.5   添加代码，编译测试

1.5.1   添加代码

1.5.1.1   开启推送服务

在应用的主Activity onCreate() 函数中开启推送服务

PushAgent mPushAgent = PushAgent.getInstance(context);
mPushAgent.enable();

• 可以通过接口 mPushAgent.disable(); 来关闭客户端的通知服务。
• 通过mPushAgent.isEnabled() 来查询状态。 状态表示有没有启用/关闭推送功能， 不表示推送后台服务的运行状态。

注意

如果你的应用继承了Application, 不要在Application onCreate() 中调用 mPushAgent.enable();. 由于SDK 设计的逻辑， 这会造成循环。

1.5.1.2   统计应用启动数据

在所有的Activity 的onCreate 函数添加

PushAgent.getInstance(context).onAppStart();

注意: 如果不调用此方法，将会导致按照"几天不活跃"条件来推送失效。

1.5.1.3   获取设备的Device Token（可选）

如果在测试或其他使用场景中，需要获取设备的Device Token，可以使用下面的方法。

String device_token = UmengRegistrar.getRegistrationId(context)

说明

• Device Token为友盟生成的用于标识设备的id，长度为44位，不能定制和修改。同一台设备上每个应用对应的Device Token不一样。
• 获取Device Token的代码需要放在mPushAgent.enable();后面，注册成功以后调用才能获得Device Token。
• 如果返回值为空， 说明设备还没有注册成功， 需要等待几秒钟，同时请确保测试手机网络畅通。

1.5.2   编译

添加代码完毕后，编译apk包。然后将apk包安装到联网的测试设备上并打开。

说明

如果在编译和调试过程中遇到问题（例如混淆或无法编译），请参考步骤7中常见问题的处理方法。

1.5.3   在测试模式中发送测试消息

1.5.3.1   获取测试设备的Device Token。

可以在Debug模式下输出的logcat中看到Device Token，也可以使用下面的方法来获取Device Token。

String device_token = UmengRegistrar.getRegistrationId(context)

说明

• Device Token为友盟生成的用于标识设备的id，长度为44位，不能定制和修改。同一台设备上每个应用对应的Device Token不一样。
• 获取Device Token的代码需要放在mPushAgent.enable();后面，注册成功以后调用才能获得Device Token。
• 如果返回值为空， 说明设备还没有注册成功， 需要等待几秒钟，同时请确保测试手机网络畅通。

1.5.3.2   添加测试设备

在友盟消息推送服务后台（ http://message.umeng.com ）的“测试模式”中填写该设备的Device Token，将该设备添加为测试设备，

1.5.3.3   发送测试消息

在“测试模式”中发送测试消息。在测试设备上收到消息，表明SDK集成成功。

说明

SDK 默认使用通知栏展示通知消息，开发者可以在友盟后台指定用户点击通知栏时的操作，包括“打开应用”、“打开指定页面（Activity）”、或“打开指定网页”。 如果没有收到消息，请参考FAQ中的处理方法。

1.5.4  API对接（可选）

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

1.6  自定义消息的打开动作和处理方式

1.6.1  消息的分类

在友盟后台，消息分为两类：

 通知消息

该消息包含Notification所需的参数，如Notification的标题、内容、是否振动、点击后的相应动作等信息。如下图所示：

其中， 通知消息根据打开动作，又可以分为以下四种：

• 打开应用
• 使用系统默认浏览器打开指定网页
• 打开指定页面（Activity）
• 自定义行为
• 更新应用

前3种打开动作默认由消息推送SDK负责处理，自定义行为则由开发者处理。 更新应用可以从后台发送应用的自动更新通知消息。

 自定义消息

友盟消息推送SDK不对该消息进行展示和提醒，消息内容全部都传递给应用处理。其包含的内容如下图所示：

1.6.2  自定义通知打开动作

在友盟后台可以指定用户点击通知消息之后的动作：

• 打开应用
• 使用系统默认浏览器打开指定网页
• 打开指定页面（Activity）
• 自定义行为

其中，自定义行为的数据放在"custom" 字段。 在友盟后台或通过API发送消息时，在“后续动作”中的“自定义行为”中输入相应的值或代码即可实现。

在消息推送SDK里，有一个类UmengNotificationClickHandler，负责处理消息的点击事件。 该类主要有四个成员方法：

public void launchApp(Context context, UMessage msg);
public void openUrl(Context context, UMessage msg);
public void openActivity(Context context, UMessage msg);
public void dealWithCustomAction(Context context, UMessage msg);

这四个方法，分别对应于四种打开方式。其中，launchApp、openUrl、openActivity这三个方法已经由消息推送SDK完成，而dealWithCustomAction则只是一个空的方法。 若开发者需要处理自定义行为，则可以重写方法dealWithCustomAction();其中自定义行为的内容，存放在UMessage.custom中。下面是处理自定义行为的代码：

/**
 * 该Handler是在BroadcastReceiver中被调用，故
 * 如果需启动Activity，需添加Intent.FLAG_ACTIVITY_NEW_TASK
 * */
UmengNotificationClickHandler notificationClickHandler = new UmengNotificationClickHandler(){
    @Override
    public void dealWithCustomAction(Context context, UMessage msg) {
        Toast.makeText(context, msg.custom, Toast.LENGTH_LONG).show();
    }
};
mPushAgent.setNotificationClickHandler(notificationClickHandler);

注意

• 以上代码需在Application的onCreate()中调用使用以下接口，而不是在Activity 中调用。如果在Activity中调用此接口，若应用进程关闭，则设置的接口会无效。请参考demo 应用代码。
• 该Handler是在BroadcastReceiver中被调用。因此若需启动Activity，需为Intent添加Flag：Intent.FLAG_ACTIVITY_NEW_TASK，否则无法启动Activity。
• 若开发者想自己处理打开网页、打开APP、打开Activity，可重写相应的函数来实现。

1.6.3   自定义通知栏样式

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

@Override
public Notification getNotification(Context context, UMessage msg) {
    switch (msg.builder_id) {
    case 1:
        NotificationCompat.Builder builder = new NotificationCompat.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);
        Notification mNotification = builder.build();
        //由于Android v4包的bug，在2.3及以下系统，Builder创建出来的Notification，并没有设置RemoteView，故需要添加此代码
        mNotification.contentView = myNotificationView;
        return mNotification;
    default:
        //默认为0，若填写的builder_id并不存在，也使用默认。
        return super.getNotification(context, msg);
    }

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

注意

• 若要使用自定义通知栏样式，请勿重写方法dealWithNotificationMessage()；否则，自定义通知栏样式将失效。

1.6.4   自定义消息处理

消息推送SDK里，有一个类UmengMessageHandler，是负责消息的处理的。该类拥有两个成员函数，分别为：

public void dealWithNotificationMessage(Context context, UMessage msg);
public void dealWithCustomMessage(Context context, UMessage msg);

其中，dealWithNotificationMessage()方法负责处理通知消息，该方法已经由消息推送SDK 完成；dealWithCustomMessage()方法负责处理自定义消息，需由用户处理。 若开发者需要处理自定义消息，则需要将方法dealWithCustomMessage()重写，自定义消息的内容则存放在UMessage.custom里。 代码如下所示：

/**
 * 该Handler是在IntentService中被调用，故
 * 1. 如果需启动Activity，需添加Intent.FLAG_ACTIVITY_NEW_TASK
 * 2. IntentService里的onHandleIntent方法是并不处于主线程中，因此，如果需调用到主线程，需如下所示;
 *        或者可以直接启动Service
 * */
UmengMessageHandler messageHandler = new UmengMessageHandler(){
    @Override
    public void dealWithCustomMessage(final Context context, final UMessage msg) {
        new Handler(getMainLooper()).post(new Runnable() {

            @Override
            public void run() {
                // TODO Auto-generated method stub
                Toast.makeText(context, msg.custom, Toast.LENGTH_LONG).show();
            }
        });
    }
};
mPushAgent.setMessageHandler(messageHandler);

注意

• 以上代码需在 Application 的onCreate() 中调用，而不是在Activity 中调用。如果在Activity中调用此接口，若应用进程关闭， 则设置的接口会无效。 请参考demo 应用代码。
• 该UmengMessageHandler是在IntentService中被调用。由于IntentService里的onHandleIntent方法是并不处于主线程中，因此，如果需调用到主线程，请参考demo；若需启动Activity，需为Intent添加Flag：Intent.FLAG_ACTIVITY_NEW_TASK，否则无法启动Activity。
• 若开发者想自己处理通知消息，可以重写方法dealWithNotificationMessage()。

1.6.5   完全自定义处理

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

1. 实现一个类，继承 UmengBaseIntentService， 重写onMessage(Context context, Intent intent) 方法，并请调用super.onMessage(context, intent)。参考 demo 应用中MyPushIntentService。请参考下面代码：

   public class MyPushIntentService extends UmengBaseIntentService{
   private static final String TAG = MyPushIntentService.class.getName();
   
   // 如果需要打开Activity，请调用Intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)；否则无法打开Activity。
   
   @Override
   protected void onMessage(Context context, Intent intent) {
       super.onMessage(context, intent);
       try {
           String message = intent.getStringExtra(BaseConstants.MESSAGE_BODY);
           UMessage msg = new UMessage(new JSONObject(message));
           UTrack.getInstance(context).trackMsgClick(msg);
           // code  to handle message here
           // ...
       } catch (Exception e) {
           Log.e(TAG, e.getMessage());
       }
   }
   }
   
   

2. 在AndroidManifest.xml 中声明。

   <!-- 请填写实际的类名，下面仅是示例代码-->
   <service android:name="com.umeng.message.example.MyPushIntentService" />
   
   

3. 在主Activity中调用。

   mPushAgent.setPushIntentServiceClass(MyPushIntentService.class);
   
   

说明

• 在onMessage()中，请务必调用super.onMessage(context, intent)；否则，后台无法统计消息的到达。
• 打开消息行为的数据统计：默认情况下，SDK将用户点击通知栏的行为定义为“打开消息”。使用PushIntentService自定义处理后，SDK只能记录消息送达的数据，无法记录消息打开的数据。要记录消息打开的数据，你可以在应用中定义打开消息的语义，并使用以下接口向服务器发送消息打开的数据以便统计：java UTrack.getInstance(context).trackMsgClick(msg);
• 如果需要打开Activity，需为Intent添加Flag：Intent.FLAG_ACTIVITY_NEW_TASK，否则无法启动Activity。

1.6.6  自动更新消息推送

1.当开发者发布了新的版本后，可以通过推送自动更新通知消息来通知用户。可以在网站上发送通知消息时，通过点击更新应用的后续行为选项或者通过API发送时，指定通知的“display_type”为“autoupdate”来实现。

2.通过消息推送来发送自动更新消息时，需要集成友盟的自动更新SDK，集成的方法就是友盟自动更新SDK的集成方法。 可以参考Android自动更新SDK快速开始 

3.当收到推送的自动更新通知消息后，如果当前应用的版本号小，会显示自动更新的通知消息，用户点击通知后，会弹出更新的提示框， 供用户下载应用，更新的流程保持与自动更新SDK一致

说明

自动更新需要集成2.6.0以上的版本。

1.7   高级功能

1.7.1  自定义参数的使用

说明

• 该功能仅在Push SDK V1.2.3及以后版本中支持。
• Push SDK 默认处理方式里，自定义参数均以字符串的形式进行传递。

开发者在发送通知和自定义消息时，可以添加自定义参数，友盟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"
    }
}

另外，开发者也可以通过Umessage.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中通过以下代码获得传递的参数：

Bundle bun = getIntent().getExtras();
if (bun != null)
{
    Set<String> keySet = bun.keySet();
    for (String key : keySet) {
        String value = bun.getString(key);
        ...
    }
}

1.7.2  通知免打扰模式

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

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

例如：

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

说明

同一台设备在1分钟内收到同一个应用的多条通知时，不会重复提醒，同时在通知栏里新的通知会替换掉旧的通知。

1.7.3   用户标签

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

mPushAgent.getTagManager().add("movie", "sport");

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

注意

下面的操作都是同步操作， 注意不要在主线程中调用。

• 添加标签

public Result add(String... tags) 

• 删除标签

public Result delete(String... tags) 

• 清除所有标签

public void reset() 

• 获取服务器端的所有标签

public List<String> list() 

1.7.4  设置用户id

如果你的应用有自有的用户id体系，可以在SDK中通过Alias字段上传自有用户id，按用户id向用户推送消息。

用户id可以是你的应用为每个用户自动生成的唯一id，也可以是用户采用第三方平台登录时从第三方平台获取到的用户id。要设置用户ID，可以使用以下接口：

mPushAgent.addAlias("zhangsan@sina.com", ALIAS_TYPE.SINA_WEIBO);

若是要移除用户id，可调用以下接口：

mPushAgent.removeAlias("zhangsan@sina.com", ALIAS_TYPE.SINA_WEIBO);

说明

• addAlias、removeAlias操作是同步操作，请勿在主线程中调用。

• 若要使用新的alias，请先调用removeAlias接口移除掉旧的alias，在调用addAlias添加新的alias，代码如下所示：

  mPushAgent.removeAlias("old@sina.com", ALIAS_TYPE.SINA_WEIBO);
  mPushAgent.addAlias("new@sina.com", ALIAS_TYPE.SINA_WEIBO);
  
  

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

• 一台设备上最大支持20个类型的alias。而每个类型的alias同时只能存在一个，同一个类型的新alias会覆盖旧alias。

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

1.7.5   自定义通知栏图标

如果在发送后台没有指定通知栏图标，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暂时无法支持自定义通知栏图标，若开发者有需求，也可通过自定义通知栏样式来解决。

最佳实践:

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

通常情况下， 只需要两个图标， 一个24*24px 的小图标，一个64*64px 的大图标， 都置于drawable-xhdpi 文件夹下。 制作图标时， 注意图片各边留一个像素的空白。 建议使用黑白图标。 具体参考Google 官方建议。

1.7.6   自定义通知栏声音

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

注意

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

1.7.7   自定义前台通知显示

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

  若要不显示前台通知，调用接口如下：

  mPushAgent.setNotificaitonOnForeground(false);

  1.7.8   Push注册回调和注销回调

  在V1.3.0上增加了两个回调： 注册回调：IUmengRegisterCallback；当开启友盟推送时，可传入注册回调，即PushAgent.enable(IUmengRegisterCallback)。 注销回调：IUmengUnregisterCallback；当关闭友盟推送时，可传入注销回调，即PushAgent.disable(IUmengUnregisterCallback)。

  注意

  • 回调的代码并不是在主线程中进行调用，故若需要调用到主线程，需在handler进行操作。代码如下：

  public IUmengRegisterCallback mRegisterCallback = new IUmengRegisterCallback() {
      @Override
      public void onRegistered(String registrationId) {
          handler.post(new Runnable() {
              @Override
              public void run() {
                  updateStatus();
              }
          });
      }
  };
  
  

  1.7.9  避免点击通知栏之后重复打开已经打开过的Activity

  在通过通知栏打开的Activity加上singleTask 属性。

  1.7.10   支持多包名

  说明

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

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

  

  

  注意

  • 如果同一设备安装同一应用的不同包名的多个安装包，只有最后安装的应用可以正常收到推送消息。
  • 主包名指的是默认的包名或者大部分渠道用到的包名，开发者自行决定哪个是主包名即可。另外，如果之前已经填写过包名，那么申请开通多包名之后，之前已经填写过的包名就会默认成为主包名。
  • 修改包名后，注意AndroidManifest.xml文件中相应的地方也需要进行包名替换，详见3.2

  1.8   常见问题

  1.8.1   集成问题

  • 如何统计Message的到达、点击和忽略？

    开发者仅需要自己统计自定义消息的点击和忽略；其他的统计，均已由消息推送SDK完成。开发者可以通过调用以下两个方法来完成统计：

    UTrack.getInstance(context).trackMsgClick(msg);//统计消息被点击或者处理
    UTrack.getInstance(context).trackMsgDismissed(msg);//统计消息被忽略
    
    

  • 如何将UMessage放入Intent中传递？

    通过调用UMessage.getRaw().toString()，可获取到UMessage的原始JSON字符串，再将其放入到Intent中。代码如下所示：

    intent.putExtra("EXTRA_KEY_MSG", msg.getRaw().toString());
    
    

  1.8.2   编译问题

  • 在测试时可以设置调试模式

    注意 正式发布应用时，请务必将本开关关闭，避免影响用户正常使用APP。

    mPushAgent.setDebugMode(boolean debug)
    
    

    打开调试模式后，可以在logcat里面看到比较详细的log信息，以方便调试和定位问题。

  • 如果APP进行了混淆，请添加:

    -keep,allowshrinking class org.android.agoo.service.* {
        public <fields>;
        public <methods>;
    }
    
    -keep,allowshrinking class com.umeng.message.* {
        public <fields>;
        public <methods>;
    }
    
    -keep public class [应用包名].R$*{
       public static final int *;
    }
    
    
    

    将【应用包名】替换为你自己应用的包名

  • 如果在编译或者混淆的过程中遇到类似下面的错误，

    Proguard returned with error code 1. See console
    Note: there were 371 duplicate class definitions.
    Warning: org.android.agoo.client.ElectionHelper: can't find referenced field 'long firstInstallTime' in library class android.content.pm.PackageInfo
    Warning: org.android.agoo.client.MessageService: can't find referenced field 'java.util.concurrent.TimeUnit MINUTES' in library class java.util.concurrent.TimeUnit
    Warning: there were 2 unresolved references to library class members.
    You probably need to update the library versions.
    (http://proguard.sourceforge.net/manual/troubleshooting.html#unresolvedlibraryclassmember)
    java.io.IOException: Please correct the above warnings first.
    at proguard.Initializer.execute(Initializer.java:369)
    at proguard.ProGuard.initialize(ProGuard.java:212)
    at proguard.ProGuard.execute(ProGuard.java:87)
    at proguard.ProGuard.main(ProGuard.java:484)
    Warning: 
    
    

    请将Android 工程对Android SDK的引用 设为最新版本(Eclipse-> 工程右键-> 属性-> Android-> Android4.3 或最新版SDK)。 minSdkVersion可以设为8.

  1.8.3  调试问题

  • 消息推送SDK 不支持在QEMU模拟器上调试，调试时请尽量使用真机。
  • 调试时 mPushAgent.isEnabled() 状态表示有没有启用推送功能，不表示推送后台服务在不在运行。

  • 调试时确认推送服务运行状态的方法

    打开调试模式后， 启动应用，在DDMS 中可以看到:umengService_v1 结尾的进程，这是友盟推送服务使用的后台进程。由于友盟推送SDK 使用了共享通道的技术，此进程可能在其他应用的包名下运行。 同时在Logcat 中可以看到类似 connect[7170]--->[onHeart()] 的log， 表明应用和友盟的推送通道成功建立。

    11-21 14:32:15.767: D/AgooService(24977): receiver--->[android.intent.action.SCREEN_ON]--->[try connect]
    11-21 14:32:16.838: D/MessagePush(24977): tryConnect---->[force:false][started:true]
    11-21 14:32:20.202: D/MessagePush(24977): connect[7170]--->[onHeart()]
    
    

  • 查看设备的Device Token的方法

    可以在Debug模式下输出的logcat中看到Device Token，也可以使用下面的方法来获取Device Token。

    String device_token = UmengRegistrar.getRegistrationId(context)
    
    

    说明

    • Device Token为友盟生成的用于标识设备的id，长度为44位，不能定制和修改。同一台设备上每个应用对应的Device Token不一样。
    • 获取Device Token的代码需要放在mPushAgent.enable();后面，注册成功以后调用才能获得Device Token。
    • 如果返回值为空， 说明设备还没有注册成功， 需要等待几秒钟，同时请确保测试手机网络畅通。

  • 如果在Logcat 中发现服务器的消息到达客户端， 但是SDK 无法展示通知栏， 请检查应用是否在 AndroidManifest.xml 中为 <Application> 设置了android:icon 属性。

  1.8.4   测试问题

  1. 消息送达时间

     在测试阶段，广播或者发送给部分人的消息会在发送后的10分钟之内送达。发送给单个Device Token的消息会在1分钟内送达。

     如果发现消息很长时间才到，有可能是因为网络状况不好，导致设备离线，到设备再次上线时才收到消息。

  2. 消息提醒的冷却时间

     同一台设备在某段时间内（默认是60秒）收到多条消息时，不会重复提醒，可以通过下面的方法来设置冷却时间。

     PushAgent.getInstance(context).setMuteDurationSeconds(int seconds)
     
     

  3. 通知栏如何展示多条通知

     默认情况下，使用SDK提供的通知类型，当设备收到多条通知时，通知栏只展示最新的一条通知，可以使用下面的方法来展示多条通知。

     PushAgent.getInstance(context).setMergeNotificaiton(false)
     
     

     注意：请慎用此开关，以免用户看到多条通知时，会带来不好的用户体验。

  4. 消息过期时间

     发送一条消息后，有些设备当时没有联网，无法收到该条消息。待设备联网时，如果消息没有过期，则设备可以收到该条消息；如果消息已经过期，则设备不会收到该条消息。

     发送消息时，过期时间应设定为晚于发送时间1小时以上。如果过期时间与发送时间间隔太短，可能任务处理时就已经过期，导致消息发送失败。

  5. 统计数据

     用户打开消息的统计数据不是立即回传的，会有5-10分钟的延时，因此测试时在后台看到的统计数据也会有相应的延时。如果数据还未回传时，应用被Android系统停止，可能造成统计数据不回传，待下次启动时才会回传。

  6. 选择发送给部分人时，筛选条件中没有显示我要的数据

     筛选条件的数据是在应用注册以后发送回来的。收到数据到数据在页面上显示出来大约需要10分钟，稍等几分钟就能在前端看到和选择了。

  7. 消息发送时的新增设备

     一条消息被服务器开始处理以后，要发送的设备就已经确定了，在这期间的新增设备不会收到这条消息。

  8. 如何添加测试设备

     在广播、组播等大规模发送消息的情况下，为了防止开发者误将测试消息大面积发给线上用户，特增加了测试模式。 测试模式下，只会将消息发送给测试设备。测试设备需要到网站上手工添加。 请参照截图:

  

  1.8.5  其他问题

  1. 集成友盟推送获取不到device_token 查看帮助

  2. 后台显示消息发送成功，设备并没有收到消息 查看帮助

  3. Logcat有消息 通知栏收不到 查看帮助

     更多常见问题请点击访问：友盟消息推送常见问题索引

  1.9   技术支持

  如果还有问题，请把您的问题发邮件至msg-support@umeng.com或者联系企业QQ:800083942，以及消息推送官方QQ群：196756762（需提供友盟账号以及app名称），我们会尽快回复您。

  如果可以附上相关日志，我们可以更好的帮助您解决问题，通过mPushAgent.setDebugMode(boolean debug)打开Debug模式，在logcat里查看log，发布应用时请去掉。