快速找到所需文档，高效完成接入与排障

适用范围

该文档适用于U-Push SDK 4.0.0及以上版本。

自定义通知

通知图标

状态栏小图标：res/drawable/umeng_push_notification_default_small_icon.png

通知栏大图标：res/drawable/umeng_push_notification_default_large_icon.png

如果项目中没有这两个图标，则会使用应用默认图标。

通知声音

声音资源：res/raw/umeng_push_notification_default_sound.mp3

若无此资源，则默认使用系统的Notification声音。

前台时不显示通知

如果您的应用在前台，您可以设置不显示通知消息。默认情况下，应用在前台是显示通知的。开发者更改前台通知显示设置后，会根据更改生效。若希望前台时不显示通知，调用接口如下：

PushAgent api = PushAgent.getInstance(context);
api.setNotificationOnForeground(false);

通知样式

UmengMessageHandler类负责处理消息，包括通知和自定义消息。其中，getNotification方法返回通知样式。若默认展示样式不符合开发者的需求，可通过重写该方法自定义展示样式。

UmengMessageHandler msgHandler = new UmengMessageHandler() {
    //处理通知栏消息
    @Override
    public void dealWithNotificationMessage(Context context, UMessage msg) {
    }

    //自定义通知样式，此方法可以修改通知样式等
    @Override
    public Notification getNotification(Context context, UMessage msg) {
        return super.getNotification(context, msg);
    }

    //处理透传消息
    @Override
    public void dealWithCustomMessage(Context context, UMessage msg) {
    }
};
PushAgent api = PushAgent.getInstance(context);
api.setMessageHandler(msgHandler);

msg.builder_id是服务器下发的通知栏样式编号字段，用于指定通知消息的样式，默认值为0。

点击通知的打开动作

开发者可自定义点击通知的后续动作，自定义行为在UMessage.custom字段。

在推送通知消息时，在“后续动作”中的“自定义行为”中输入相应的值或代码即可实现。

若开发者需要处理自定义行为，则可以重写方法dealWithCustomAction()，示例代码：

UmengNotificationClickHandler notificationClickHandler = new UmengNotificationClickHandler() {
    @Override
    public void dealWithCustomAction(Context context, UMessage msg) {
    }

    @Override
    public void openActivity(Context context, UMessage msg) {
    }

    @Override
    public void launchApp(Context context, UMessage msg) {
    }

    @Override
    public void dismissNotification(Context context, UMessage msg) {
    }
};
PushAgent api = PushAgent.getInstance(context);
api.setNotificationClickHandler(notificationClickHandler);

通知显示个数

可以设置最多显示通知的个数，当显示数目大于设置值时，若再有新通知到达，会移除一条最早的通知

PushAgent api = PushAgent.getInstance(context);
api.setDisplayNotificationNumber(number);

通知响铃、震动、呼吸灯

响铃、震动及呼吸灯可以分别通过以下三个接口，可单独设置控制方式：

1、服务端控制：通过服务端推送状态来设置通知到达后响铃、震动、呼吸灯的状态；

2、客户端控制：关闭服务端推送控制能力，由客户端控制通知到达后是否响铃、震动以及呼吸灯是否点亮

PushAgent api = PushAgent.getInstance(context);
//声音控制示例
api.setNotificationPlaySound(MsgConstant.NOTIFICATION_PLAY_SERVER);
//呼吸灯控制示例
api.setNotificationPlayLights(MsgConstant.NOTIFICATION_PLAY_SDKE_NABLE);
//振动控制示例
api.setNotificationPlayVibrate(MsgConstant.NOTIFICATION_PLAY_SDK_DISABLE);

通知免打扰

为避免打扰用户，默认在“23:00”到“7:00”之间收到通知消息时不响铃，不振动，不闪灯。

如果需要改变默认的静音时间，可以使用以下接口：

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

例如：

PushAgent api = PushAgent.getInstance(context);
api.setNoDisturbMode(23, 0, 7, 0);

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

PushAgent api = PushAgent.getInstance(context);
api.setNoDisturbMode(0, 0, 0, 0);

默认情况下，同一台设备在1分钟内收到同一个应用的多条通知时，不会重复提醒，可以通过如下方法来修改冷却时间：

PushAgent api = PushAgent.getInstance(context);
api.setMuteDurationSeconds(seconds);

消息处理

自定义参数

开发者在【友盟+】后台推送通知和自定义消息时，可以添加自定义参数，如下图：

这些自定义参数将通过extra字段发送到客户端，您下发的自定义参数可以通过多种方式获得：

方式1：重写UmengMessageHandler类中的getNotification(Context context, UMessage msg)方法：

UmengMessageHandler messageHandler = new UmengMessageHandler() {
    @Override
    public Notification getNotification(Context context, UMessage msg) {
        for (Map.Entry entry : msg.extra.entrySet()) {
            Object key = entry.getKey();
            Object value = entry.getValue();
        }
        return super.getNotification(context, msg);
    }
};
PushAgent api = PushAgent.getInstance(context);
api.setMessageHandler(messageHandler);

方式2：通过重写UmengNotificationClickHandler类中的launchApp、openUrl、openActivity、dealWithCustomAction方法，均可从msg.extra中获取自定义参数：

方式3：点击通知进入Activity时获取自定义参数：

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

自定义消息

自定义消息不会被展示到通知栏上，SDK仅负责将消息透传给App，其内容处理由开发者自己控制。

最佳实践：自定义消息可以用于应用的内部业务逻辑和特殊展示需求。后台页面如下所示：

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

UmengMessageHandler messageHandler = new UmengMessageHandler() {
    @Override
    public void dealWithCustomMessage(final Context context, final UMessage msg) {
        super.dealWithCustomMessage(context, msg);
        new Handler(Looper.getMainLooper()).post(new Runnable() {
            @Override
            public void run() {
                //对自定义消息的处理方式，点击或者忽略
                boolean isClickOrDismissed = true;
                if (isClickOrDismissed) {
                    //自定义消息的点击统计
                    UTrack.getInstance().trackMsgClick(msg);
                } else {
                    //自定义消息的忽略统计
                    UTrack.getInstance().trackMsgDismissed(msg);
                }
            }
        });
    }
}
PushAgent api = PushAgent.getInstance(context);
api.setMessageHandler(messageHandler);

消息统计接口说明：

/**
 * 统计在线通知消息呈现
 */
UTrack.getInstance().trackMsgShow(UMessage msg);

/**
 * 统计在线通知消息点击
 */
UTrack.getInstance().trackMsgClick(UMessage msg);

/**
 * 统计在线通知消息消失
 */
UTrack.getInstance().trackMsgDismissed(UMessage msg);

/**
 * 统计厂商通知消息点击
 */
UTrack.getInstance().trackMfrPushMsgClick(UMessage msg);

资源包名

当资源包名(AndroidManifest.xml中package或build.gradle中namespace)和应用包名(build.gradle中applicationId)不一致时，需设置资源包名：

PushAgent api = PushAgent.getInstance(context);
api.setResourcePackageName(String packageName);

标签与别名

标签可以给某一类人群推送消息，别名可以给指定用户推送消息。最佳实践：

• 客户端开发者在应用内调用 addTags 或者 addAlias来设置对应关系；

• 【友盟+】消息后台存储相应的关系设置；

• 在服务器端推送消息时，指定向之前设置过的别名或者标签推送。

1、添加、删除、获取标签；

PushAgent api = PushAgent.getInstance(context);
//添加标签 示例：将“标签1”、“标签2”绑定至该设备
api.getTagManager().addTags(new UPushTagCallback<Result>() {
    @Override
    public void onMessage(boolean isSuccess, Result result) {
    }
},"标签1",,"标签2");

//删除标签,将之前添加的标签中的一个或多个删除
api.getTagManager().deleteTags(new UPushTagCallback<Result>() {
    @Override
    public void onMessage(boolean isSuccess, Result result) {
    }
},"标签1",,"标签2");

//获取服务器端的所有标签
api.getTagManager().getTags(new UPushTagCallback<List<String>>() {
    @Override
    public void onMessage(boolean isSuccess, List<String> result){
    }
});

2、增加、绑定、移除别名：

PushAgent api = PushAgent.getInstance(context);
//别名增加，将某一类型的别名ID绑定至某设备，老的绑定设备信息还在，别名ID和device_token是一对多的映射关系
//alias和alias_type两个字段的长度限制分别为128，64个字符
//alias和alias_type的格式仅支持半角大小写字母，数字，下划线
//默认单个alias下同时生效的deviceToken数最多10个，pro可调整，需要绑定大量设备（>1k)的场景用tag更合适
//默认单个Appkey下同时生效的alias_type数最多10个
api.addAlias("别名ID", "自定义类型", new UPushAliasCallback() {
    @Override
    public void onMessage(boolean isSuccess, String message) {
    }
});

//别名绑定，将某一类型的别名ID绑定至某设备，老的绑定设备信息被覆盖，别名ID和deviceToken是一对一的映射关系
api.setAlias("别名ID", "自定义类型", new UPushAliasCallback(){
    @Override
    public void onMessage(boolean isSuccess, String message) {
    }
});

//移除别名ID
api.deleteAlias("别名ID", "自定义类型", new UPushAliasCallback() {
    @Override
    public void onMessage(boolean isSuccess,String message){
    }
});

角标

可通过调用API接口设置角标数字

PushAgent api = PushAgent.getInstance(context);

/**
  * 设置角标数字（支持华为、vivo、荣耀、OPPO(需向OPPO官方申请)）
  * @param number 角标数字
  */
api.setBadgeNum(int number);

/**
  * 角标数字（支持华为、荣耀）递增减
  * @param number 递增减数值
  */
api.changeBadgeNum(int number);

通知权限

可通过调用API接口获取是否具有弹出通知权限、打开通知权限设置界面：

PushAgent api = PushAgent.getInstance(context);

/**
 * 获取弹出通知权限状态
 * @return true:开启; false:关闭
 */
api.isNotificationEnabled();

/**
 * 打开系统通知权限设置界面
 * @return true:成功; false:失败
 */
api.openNotificationSettings();

厂商Token回调

可通过调用API接口设置厂商Token的回调，通过实现回调接口获取厂商的Token：

PushAgent api = PushAgent.getInstance(context);
api.setThirdTokenCallback(new UPushThirdTokenCallback() {
    @Override
    public void onToken(String type, String token) {
    }
});

通知转应用内浮窗回调

可通过调用API接口设置应用内浮窗事件的回调：

PushAgent api = PushAgent.getInstance(context);
api.setInAppMessageCallback(new UPushInAppMessageCallback() {
    @Override
    public void onShow(Context context, UMessage message) {
    }

    @Override
    public void onClick(Context context, UMessage message) {
    }

    @Override
    public void onDismiss(Context context, UMessage message) {
    }
});

应用内消息

应用内消息可以在【友盟+】Push消息后台的【推送】-【创建任务】中选择【应用内消息】：

全屏消息

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

配置默认图片

1、在主工程的values目录下的styles.xml文件中添加如下代码，并在drawable目录下放置一张名为umeng_push_default_splash_bg的默认图片（推荐1920*1080分辨率，也可以根据适配需要引用xml资源）。

<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 manager = InAppMessageManager.getInstance(this);
        //设置应用内消息为Debug模式
        manager.setInAppMsgDebugMode(true);
        //参数为Activity的完整包路径，下面仅是示例代码，请按实际需求填写
        manager.setMainActivityPath(MainActivity.class.getName());
        return super.onCustomPretreatment();
    }
}

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

<activity 
    android:name="com.umeng.message.demo.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>

插屏消息

插屏消息是在App页面之上弹出的图片或文本消息。插屏消息分为三种类型：插屏、自定义插屏和纯文本。

展示插屏消息

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

void showCardMessage(Activity activity, String label, IUmengInAppMsgCloseCallback callback);

例如：

InAppMessageManager.getInstance(this).showCardMessage(this, "main", new IUmengInAppMsgCloseCallback() {
    @Override
    public void onClose() {
    }
});

展示样式如下所示：

自定义插屏

自定义插屏允许开发者来控制插屏的展示样式。若要使用自定义插屏样式，则需在工程中新建一个命名为umeng_custom_card_message.xml的布局文件，开发者可以修改布局（ImageView和两个Button的id不能改变）。

纯文本

纯文本插屏字体大小可以由开发者控制，单位为sp，默认为18、16、16，可以使用以下方法设置（在showCardMessage之前调用）：

InAppMessageManager.getInstance(context).setPlainTextSize(titleTextSize, contentTextSize, buttonTextSize);

展示样式如下所示：

其他设置

集成自检设置

开启：

PushAgent api = PushAgent.getInstance(context);
api.setPushCheck(true);

关闭：

PushAgent api = PushAgent.getInstance(context);
api.setPushCheck(false);

推送功能开启与关闭

开启：

PushAgent api = PushAgent.getInstance(context);
api.register(...);
api.enable(new UPushSettingCallback() {
    @Override
    public void onSuccess() {
    }

    @Override
    public void onFailure(String errCode, String errDesc) {
    }
});

关闭：

PushAgent api = PushAgent.getInstance(context);
api.register(...);
api.disable(new UPushSettingCallback() {
    @Override
    public void onSuccess() {
    }

    @Override
    public void onFailure(String errCode, String errDesc) {
    }
});

推送降耗设置

开启：

PushAgent api = PushAgent.getInstance(context);
api.setSmartEnable(true);

关闭：

PushAgent api = PushAgent.getInstance(context);
api.setSmartEnable(false);

推送地理围栏设置

如需使用地理围栏功能，需要集成对应SDK（uyumao），并声明以下权限（可选）：

<!-- 允许应用获取粗略位置 -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<!-- 允许应用获取精准位置 -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<!-- 应用后台定位权限 -->
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" /> 

如不需使用地理围栏功能，可调用以下关闭接口：

UYMManager.enableYm1(context, false); // 禁止获取位置信息(发起定位请求)
UYMManager.enableYm2(context, false); // 禁止获取位置信息(读取定位缓存)
UYMManager.enableYm3(context, false); // 禁止获取已连接WiFi路由器信息
UYMManager.enableYm4(context, false); // 禁止获取周边WiFi路由列表信息
UYMManager.enableYm5(context, false); // 禁止获取基站信息

多包名设置

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

采集设备信息开关设置

如希望关闭设备ID采集，请参照以下接口：

// IMSI采集开关接口
// 参数flag: true-允许采集IMSI；false-不允许采集IMSI
UMConfigure.enableImsiCollection(boolean flag);

// ICCID采集开关接口
// 参数flag: true-允许采集ICCID；false-不允许采集ICCID
UMConfigure.enableIccidCollection(boolean flag);

// IMEI采集开关接口
// 参数flag: true-允许采集IMEI；false-不允许采集IMEI
UMConfigure.enableImeiCollection(boolean flag);