推送模板说明

此SDK已停止维护,请开发者对接 RestApi V2

推送模板说明

代码示例

推送模板,GitHub示例点此查看

简述

开发者可设置推送展示效果,分为通知样式和后续操作。

推送效果:

  • 通知消息:

通知展示时效果:响铃、震动、通知是否可清除,下拉大图、长文本。

通知点击后效果:打开应用首页、打开应用内指定页面、打开浏览器指定网页。

  • 透传消息:

即自定义消息,效果由开发者自行管理,个推只负责消息传递,不做任何处理,默认不会在通知栏中展示,开发者需自行处理展示方式或后续动作。

设置步骤

STEP1:选择合适的推送模板,决定后续操作。

STEP2:(仅通知模板)调用模板中的setStyle接口,设置通知样式。(如需同时进行iOS推送,相关样式设置请参考【通知样式】iOS通知样式设置

STEP3:设置推送其他参数

STEP4:执行推送

示例说明

    // STEP1:选择模板
    NotificationTemplate template = new NotificationTemplate();
    // 设置APPID与APPKEY
    template.setAppId(appId);
    template.setAppkey(appKey)


    // STEP2:设置通知样式
    Style0 style = new Style0();
    // 设置通知栏标题与内容
    style.setTitle("请输入通知栏标题");
    style.setText("请输入通知栏内容");
    // 配置通知栏图标
    style.setLogo("icon.png");
    // 配置通知栏网络图标
    style.setLogoUrl("");
    // 配置自定义铃声,需要在客户端开发时嵌入
    style.setRingName("sound");
    // 角标, 必须大于0, 个推通道下发有效; 此属性目前仅针对华为 EMUI 4.1 及以上设备有效
    style.setBadgeAddNum(1);
    // 设置通知是否响铃,震动,或者可清除
    style.setRing(true);
    style.setVibrate(true);
    style.setClearable(true);
    style.setChannel("通知渠道id");
    style.setChannelName("通知渠道名称");
    style.setChannelLevel(3); //设置通知渠道重要性
    template.setStyle(style);

    template.setAPNInfo(getAPNPayload()); //详见本页iOS通知样式设置

    // STEP3:设置推送其他参数
    SingleMessage message = new SingleMessage();
    message.setData(template);
    // 厂商通道下发策略(可选项),参数含义见【推送API】页面
    message.setStrategyJson("{\"default\":4,\"ios\":4,\"st\":4}");

    // STEP4:执行推送
    push.pushMessageToSingle(message, target);

【透传模板】自定义消息

描述

透传消息是指消息传递到客户端只有消息内容,展现形式由客户端自行定义。客户端可自定义通知的展现形式,也可自定义通知到达之后的动作,或者不做任何展现。

对应模板(TransmissionTemplate)

参数说明

成员和方法名 类型 必填 默认值 说明
setAppID String 设定接收的应用
setAppkey String 用于鉴定身份是否合法
setTransmissionContent String 透传内容,不支持转义字符
setTransmissionType int 搭配transmissionContent使用,可选值为1、2;
1:立即启动APP(不推荐使用,影响客户体验)
2:客户端收到消息后需要自行处理
setSmsInfo SmsInfo 设置短信相关参数,详见短信补量
setAPNInfo Payload 【iOS】用于设置标题、内容、语音、多媒体、VoIP(基于IP的语音传输)等。【厂商下发策略】可以选择厂商优先,具体样式见iOS通知样式

代码示例

    public static TransmissionTemplate transmissionTemplateDemo() {
        TransmissionTemplate template = new TransmissionTemplate();
        template.setAppId(appId);
        template.setAppkey(appkey);
        template.setTransmissionType(2);
        template.setTransmissionContent("请输入需要透传的内容");
        //template.setAPNInfo(getAPNPayload()); //详见本页iOS通知样式设置
        return template;
    }

【通知模板】打开应用首页

描述

在通知栏显示一条通知,用户点击后打开应用的首页。

应用场景

针对沉默用户,发送推送消息,点击消息栏的通知可直接激活启动应用,提升应用的转化率。

对应模板(NotificationTemplate)

参数说明

成员和方法名 类型 必填 默认值 说明
setAppId String 设定目标应用
setAppkey String 用于鉴定身份是否合法
setDuration String, String 【Android】格式yyyy-MM-dd HH:mm:ss, 收到消息后,在此时间区间展示,如果此区间APP不在前台,就会错过展示,例如2019年8月14日8点-2019年8月14日9点,展示早间新闻
transmissionContent String 透传内容,不在通知栏中展示,开发者自行处理,不支持转义字符
setTransmissionType int 搭配transmissionContent使用,可选值为1、2;
1:立即启动APP
2:客户端收到消息后需要自行处理
setStyle AbstractNotifyStyle - 【Android】用于设置标题、内容、提示音、震动、背景图等。具体样式见Android通知样式
setNotifyid Integer 【Android】在消息推送的时候设置notifyid。如果需要覆盖此条消息,则下次使用相同的notifyid发一条新的消息。客户端sdk会根据notifyid进行覆盖。详见消息覆盖
setSmsInfo SmsInfo 设置短信相关参数,详见短信补量
setAPNInfo Payload 【iOS】用于设置标题、内容、语音、多媒体、VoIP(基于IP的语音传输)等。【厂商下发策略】可以选择厂商优先,具体样式见iOS通知样式

代码示例

    public static NotificationTemplate notificationTemplateDemo(String appId, String appkey) {
        NotificationTemplate template = new NotificationTemplate();
        template.setAppId(appId);
        template.setAppkey(appkey);
        template.setTransmissionType(1);
        template.setTransmissionContent("请输入您要透传的内容");

        Style0 style = new Style0();
        // 设置通知栏标题与内容
        style.setTitle("请输入通知栏标题");
        style.setText("请输入通知栏内容");
        // 配置通知栏图标
        style.setLogo("icon.png");
        // 配置通知栏网络图标
        style.setLogoUrl("");
        // 设置通知是否响铃,震动,或者可清除
        style.setRing(true);
        style.setVibrate(true);
        style.setClearable(true);
        style.setChannel("自定义channel");
        style.setChannelName("自定义channelName");
        style.setChannelLevel(3);
        template.setStyle(style);
        //template.setAPNInfo(getAPNPayload()); //详见本页iOS通知样式设置

        // 设置定时展示时间,安卓机型可用
        // template.setDuration("2019-08-16 11:40:00", "2019-08-16 12:24:00");

        // 消息覆盖
        // template.setNotifyid(123); // 在消息推送的时候设置自定义的notifyid。如果需要覆盖此条消息,则下次使用相同的notifyid发一条新的消息。客户端sdk会根据notifyid进行覆盖。
        return template;
    }

【通知模板】打开应用内页面

描述

在通知栏显示一条通知,用户点击后打开应用内指定的页面。

应用场景

推广促销活动,用户点击通知栏信息,直接打开到应用内指定的促销活动页面。

对应模板(StartActivityTemplate)

参数说明

成员和方法名 类型 必填 默认值 说明
setAppId String 设定目标应用
setAppkey String 用于鉴定身份是否合法
setDuration String, String 【Android】格式yyyy-MM-dd HH:mm:ss, 收到消息后,在此时间区间展示,如果此区间APP不在前台,就会错过展示,例如2019年8月14日8点-2019年8月14日9点,展示早间新闻
setIntent String 【Android】长度小于1000字节,通知带intent传递参数(以intent:开头,;end结尾)
示例:intent:#Intent;component=你的包名/你要打开的 activity 全路径;S.parm1=value1;S.parm2=value2;end
intent生成请参考
setStyle AbstractNotifyStyle - 【Android】用于设置标题、内容、提示音、震动、背景图等。具体样式见Android通知样式
setNotifyid Integer 【Android】在消息推送的时候设置notifyid。如果需要覆盖此条消息,则下次使用相同的notifyid发一条新的消息。客户端sdk会根据notifyid进行覆盖。详见消息覆盖
setSmsInfo SmsInfo 设置短信相关参数,详见短信补量
setAPNInfo Payload 【iOS】用于设置标题、内容、语音、多媒体、VoIP(基于IP的语音传输)等。【厂商下发策略】可以选择厂商优先,具体样式见iOS通知样式

代码示例

    public static StartActivityTemplate startActivityTemplateDemo(String appId, String appKey) {
        StartActivityTemplate template = new StartActivityTemplate();
        template.setAppId(appId);
        template.setAppkey(appKey);

        Style0 style = new Style0();
        // 设置通知栏标题与内容
        style.setTitle("请输入通知栏标题");
        style.setText("请输入通知栏内容");
        // 配置通知栏图标
        style.setLogo("icon.png");
        // 配置通知栏网络图标
        style.setLogoUrl("");
        // 设置通知是否响铃,震动,或者可清除
        style.setRing(true);
        style.setVibrate(true);
        style.setClearable(true);
        style.setChannel("自定义channel");
        style.setChannelName("自定义channelName");
        style.setChannelLevel(3);
        template.setStyle(style);

        String intent = "intent:#Intent;component=com.yourpackage/.NewsActivity;end";
        template.setIntent(intent); //最大长度限制为1000
        template.setNotifyid(123); // 在消息推送的时候设置notifyid。如果需要覆盖此条消息,则下次使用                                                
        // 设置定时展示时间,安卓机型可用
        // template.setDuration("2019-08-16 11:40:00", "2019-08-16 12:24:00");

        // 消息覆盖
        // template.setNotifyid(123); // 在消息推送的时候设置自定义的notifyid。如果需要覆盖此条消息,则下次使用相同的notifyid发一条新的消息。客户端sdk会根据notifyid进行覆盖。

        //template.setAPNInfo(getAPNPayload()); //详见本页iOS通知样式设置
        return template;
    }

【通知模板】打开浏览器网页

描述

在通知栏显示一条通知,用户点击可打开浏览器的指定网页。

应用场景

推广促销活动,用户点击通知栏信息,直接打开到指定的促销活动页面,推送直接到达指定页面,免去了中间过程的用户流失。

对应模板(LinkTemplate)

参数说明

成员和方法名 类型 必填 默认值 说明
setAppId String 设定目标应用
setAppkey String 用于鉴定身份是否合法
setUrl String 点击通知后打开的网页地址
setDuration String, String 【Android】格式yyyy-MM-dd HH:mm:ss, 收到消息后,在此时间区间展示,如果此区间APP不在前台,就会错过展示,例如2019年8月14日8点-2019年8月14日9点,展示早间新闻
setStyle AbstractNotifyStyle - 【Android】用于设置标题、内容、提示音、震动、背景图等。具体样式见Android通知样式
setNotifyid Integer 【Android】在消息推送的时候设置notifyid。如果需要覆盖此条消息,则下次使用相同的notifyid发一条新的消息。客户端sdk会根据notifyid进行覆盖。详见消息覆盖
setSmsInfo SmsInfo 设置短信相关参数,详见短信补量
setAPNInfo Payload 【iOS】用于设置标题、内容、语音、多媒体、VoIP(基于IP的语音传输)等。【厂商下发策略】可以选择厂商优先,具体样式见iOS通知样式

代码示例

    public static LinkTemplate linkTemplateDemo(String appId, String appKey) {
        LinkTemplate template = new LinkTemplate();
        template.setAppId(appId);
        template.setAppkey(appKey);

        Style0 style = new Style0();
        // 设置通知栏标题与内容
        style.setTitle("请输入通知栏标题");
        style.setText("请输入通知栏内容");
        // 配置通知栏图标
        style.setLogo("icon.png");
        // 配置通知栏网络图标
        style.setLogoUrl("");
        // 设置通知是否响铃,震动,或者可清除
        style.setRing(true);
        style.setVibrate(true);
        style.setClearable(true);
        style.setChannel("自定义channel");
        style.setChannelName("自定义channelName");
        style.setChannelLevel(3);
        template.setStyle(style);

        // 设置打开的网址地址
        template.setUrl("http://www.getui.com");
        // 设置定时展示时间,安卓机型可用
        // template.setDuration("2019-08-16 11:40:00", "2019-08-16 12:24:00");

        // 消息覆盖
        // template.setNotifyid(123); // 在消息推送的时候设置自定义的notifyid。如果需要覆盖此条消息,则下次使用相同的notifyid发一条新的消息。客户端sdk会根据notifyid进行覆盖。

        //template.setAPNInfo(getAPNPayload()); //详见本页iOS通知样式设置
        return template;
    }

【通知模板】通知消息撤回

描述

消息撤回是指对已经发送的个推通道消息进行撤回。客户端接收到消息撤回的指令,会将通知栏中展示的消息进行删除,不再展示。

sdk版本要求

客户端sdk:2.12.5.0以上

服务端os-sdk:java 4.1.0.1以上

撤回使用限制

  1. 支持任务类型:os-sdk撤回模板支持撤回单推、群推、toApp任务。
  2. 支持模板:只支持撤回通知、不支持透传
  3. Android只支持撤回个推通道下发的通知,通过手机厂商通道下发的通知不支持撤回

对应模板 (RevokeTemplate)

参数说明

成员和方法名 类型 必填 默认值 说明
setAppId String 设定目标应用
setAppkey String 用于鉴定身份是否合法
setOldTaskId String 指定需要撤回消息对应的taskId
setForce Boolean false 【Android】客户端没有找到对应的taskid,是否把对应appid下所有的通知都撤回

代码示例

    public static RevokeTemplate revokeTemplateDemo(String appId, String appKey) {      
        RevokeTemplate template = new RevokeTemplate();
        template.setAppId(appId);
        template.setAppkey(appKey);
        template.setOldTaskId(oldTaskId);
        template.setForce(force);
        returen template;
    }

【通知样式】iOS通知样式设置

iOS推送需要在代码中通过通知或透传模板的setAPNInfo接口设置相应的APNs通知参数。
APNs传输数据最大支持3KB。

对应方法

setAPNInfo(Payload payload)

参数描述

setAPNInfo具体参数含义详见苹果APNs文档

注:setAutoBadge、setAlertMsg、setSound(不设置无声)必须至少设置一项

参数说明

  • 普通消息推送
类名 方法名 说明
APNPayload setAutoBadge 设置角标,还可以实现显示数字的自动增减,如"+1"、"-1"、"1"等
setContentAvailable 推送直接带有透传数据
setAlertMsg 通知消息体
setSound(String) 通知铃声文件名
setSound(Sound) sound支持Dictionary类型,可以控制“警告性质的推送”,仅支持iOS 12.0以上版本
setCategory 在客户端通知栏触发特定的action和button显示
addCustomMsg 增加自定义的数据,Key-Value形式
addMultiMedia(MultiMedia media) 添加一个多媒体资源,当前最多传入3个资源
setMultiMedias(List<MultiMedia> medias) 设置多媒体资源列表,单个列表最多支持3个资源
setVoicePlayType(int voicePlayType) 设置语音播报类型,int类型,0.不可用 1.播放body 2.播放自定义文本
setVoicePlayMessage(String voicePlayMessage) 设置语音播报内容,String类型,非必须参数,用户自定义播放内容,仅在voicePlayMessage=2时生效
setThreadId(String threadId) ios的远程通知通过该属性对通知进行分组,仅支持iOS 12.0以上版本
setApnsCollapseId(String apnsCollapseId) 使用相同的apnsCollapseId可以覆盖之前的消息
类名 方法名 说明
Sound setCritical(int) 临界警报标志。设置为1以启用临界警报
setName(String) 声音文件名
setVolume(double) 临界警报声音的音量。将此设置为0(无声)和1(全音量)之间的值
类名 方法名 说明
APNPayload.SimpleAlertMsg - 通知文本消息字符串
APNPayload.DictionaryAlertMsg setBody 通知文本消息字符串
setActionLocKey (用于多语言支持)指定执行按钮所使用的Localizable.strings
setLocKey (用于多语言支持)指定Localizable.strings文件中相应的key
addLocArg 如果loc-key中使用的是占位符,则在loc-args中指定各参数
setLaunchImage 指定启动界面图片名
setTitle 通知标题
setTitleLocKey (用于多语言支持)对于标题指定执行按钮所使用的Localizable.strings,仅支持iOS8.2以上版本
addTitleLocArg 对于标题,如果loc-key中使用的是占位符,则在loc-args中指定各参数,仅支持iOS8.2以上版本
setSubtitle 设置子标题,仅支持iOS8.2以上版本
setSubtitleLocKey 设置当前本地化文件中的子标题字符串的关键字,仅支持iOS8.2以上版本
addSubtitleLocArgs 设置当前本地化子标题内容中需要置换的变量参数 ,仅支持iOS8.2以上版本
setSummaryArg 合并分组时简介信息,仅支持iOS12.0以上版本
setSummaryArgCount 合并分组时单条消息中包含数字,仅支持iOS12.0以上版本
类名 方法名 说明
MultiMedia setResId(String resId) 设置资源id
setResUrl(String resUrl) 设置资源url
setResType(MediaType resType) 设置资源类别
MediaType.pic 图片
MediaType.audio 音频
MediaType.video 视频
setOnlyWifi(boolean onlyWifi) 设置是否在WIFI下才展示多媒体消息,如果设置true但未使用WIFI时会展示成普通通知
  • VoIP推送
类名 方法名 说明
VoIPPayload setVoIPPayload 设置VoIP内容,建议使用JSON格式

代码示例

    public static TransmissionTemplate getTemplate() {
        TransmissionTemplate template = new TransmissionTemplate();
        template.setAppId(appId);
        template.setAppkey(appkey);       
        template.setTransmissionType(2);
        template.setTransmissionContent("透传内容"); //透传内容
        template.setAPNInfo(getAPNPayload()); //ios消息推送
        //template.setAPNInfo(getVoIPPayload());
    }

    private static APNPayload getAPNPayload() {
        APNPayload payload = new APNPayload();
        //在已有数字基础上加1显示,设置为-1时,在已有数字上减1显示,设置为数字时,显示指定数字
        payload.setAutoBadge("+1");
        payload.setContentAvailable(0);
        //ios 12.0 以上可以使用 Dictionary 类型的 sound
        payload.setSound("default");
        payload.setCategory("$由客户端定义");
        payload.addCustomMsg("由客户自定义消息key", "由客户自定义消息value");

        //简单模式APNPayload.SimpleMsg
        payload.setAlertMsg(new APNPayload.SimpleAlertMsg("hello"));
        //payload.setAlertMsg(getDictionaryAlertMsg());  //字典模式使用APNPayload.DictionaryAlertMsg

        //设置语音播报类型,int类型,0.不可用 1.播放body 2.播放自定义文本
        payload.setVoicePlayType(2);
        //设置语音播报内容,String类型,非必须参数,用户自定义播放内容,仅在voicePlayMessage=2时生效
        //注:当"定义类型"=2, "定义内容"为空时则忽略不播放
        payload.setVoicePlayMessage("定义内容");

        // 添加多媒体资源
        payload.addMultiMedia(new MultiMedia().setResType(MultiMedia.MediaType.pic)
                .setResUrl("资源文件地址")
                .setOnlyWifi(true));

        return payload;
    }

    private static APNPayload.DictionaryAlertMsg getDictionaryAlertMsg() {
        APNPayload.DictionaryAlertMsg alertMsg = new APNPayload.DictionaryAlertMsg();
        alertMsg.setBody("body1");
        alertMsg.setActionLocKey("显示关闭和查看两个按钮的消息");
        alertMsg.setLocKey("loc-key1");
        alertMsg.addLocArg("loc-ary1");
        alertMsg.setLaunchImage("调用已经在应用程序中绑定的图形文件名");
        // iOS8.2以上版本支持
        alertMsg.setTitle("通知标题");
        alertMsg.setTitleLocKey("自定义通知标题");
        alertMsg.addTitleLocArg("自定义通知标题组");
        return alertMsg;
    }

    /**
     * 需要使用iOS语音传输,请使用VoIPPayload代替APNPayload
     * @return
     */
    private static VoIPPayload getVoIPPayload() {
        VoIPPayload payload = new VoIPPayload();
        JSONObject jo = new JSONObject();
        jo.put("key1", "value1");
        payload.setVoIPPayload(jo.toString());
        return payload;
    }

【通知样式】Android通知样式设置

对应接口

setStyle(AbstractNotifyStyle style)

接口说明

AbstractNotifyStyle是父类,Style0、Style6是其子类

  • Style0:系统样式
  • Style6-1:大图+文本样式
  • Style6-2:长文本样式

style4

参数说明

公共成员和方法名 类型 必填 默认值 说明
setRing boolean TRUE 收到通知是否响铃:true响铃,false不响铃。默认响铃。
setVibrate boolean TRUE 收到通知是否振动:true振动,false不振动。默认振动。
setClearable boolean TRUE 通知是否可清除: true可清除,false不可清除。默认可清除。
setRingName string 自定义铃声,请填写文件名,不包含后缀名(需要在客户端开发时嵌入),个推通道下发有效
客户端SDK最低要求 2.14.0.0
服务端SDK最低要求 4.1.1.3
setBadgeAddNum number 角标, 必须大于0, 个推通道下发有效
此属性目前仅针对华为 EMUI 4.1 及以上设备有效
角标数字数据会和之前角标数字进行叠加;
举例:角标数字配置1,应用之前角标数为2,发送此角标消息后,应用角标数显示为3。
客户端SDK最低要求 2.14.0.0
服务端SDK最低要求 4.1.1.3

Style0 系统样式

成员和方法名 类型 必填 默认值 说明
setTitle String 通知标题
setText String 通知内容
setLogo String push.png 通知的图标名称,包含后缀名(需要在客户端开发时嵌入),如“icon.png”
小LOGO,默认push_small.png,需要提前内置到客户端
setLogoUrl String 通知图标URL地址,小米、华为有些机型不支持此参数
setChannel String Default 通知渠道id,唯一标识
setChannelName String Default 通知渠道名称
setChannelLevel int 3 该字段代表通知渠道重要性,具体值有0、1、2、3、4;
设置之后不能修改;具体展示形式如下:
0:无声音,无震动,不显示。(不推荐)
1:无声音,无震动,锁屏不显示,通知栏中被折叠显示,导航栏无logo。
2:无声音,无震动,锁屏和通知栏中都显示,通知不唤醒屏幕。
3:有声音,有震动,锁屏和通知栏中都显示,通知唤醒屏幕。(推荐)
4:有声音,有震动,亮屏下通知悬浮展示,锁屏通知以默认形式展示且唤醒屏幕。(推荐)

Style6 展开式通知样式,setBigStyle1/setBigStyle2 两种方式选一种

成员和方法名 类型 必填 默认值 说明
setTitle String 通知标题
setText String 通知内容
setLogo String push.png 通知的图标名称,包含后缀名(需要在客户端开发时嵌入),如“icon.png”
小LOGO,默认push_small.png,需要提前内置到客户端
setLogoUrl String 通知图标URL地址,小米、华为有些机型不支持此参数
setBigStyle1(bigImageUrl) String 通知展示大图样式,参数是大图的URL地址
setBigStyle2(bigText) String 通知展示文本+长文本样式,参数是长文本
setChannel String Default 通知渠道id,唯一标识
setChannelName String Default 通知渠道名称
setChannelLevel int 3 该字段代表通知渠道重要性,具体值有0、1、2、3、4;
设置之后不能修改;具体展示形式如下:
0:无声音,无震动,不显示。(不推荐)
1:无声音,无震动,锁屏不显示,通知栏中被折叠显示,导航栏无logo。
2:无声音,无震动,锁屏和通知栏中都显示,通知不唤醒屏幕。
3:有声音,有震动,锁屏和通知栏中都显示,通知唤醒屏幕。(推荐)
4:有声音,有震动,亮屏下通知悬浮展示,锁屏通知以默认形式展示且唤醒屏幕。(推荐)
开发者中心 SDK 下载

文档中心搜索

技术
咨询

微信扫一扫

随时联系技术支持

在线
咨询