个推服务端api使用手册进阶

前言

上一片初级手册里给大家演示了如何使用个推服务端的sdk调用个推推送服务的api。相信许多朋友已经尝试成功了。但除了能够完成传送消息到手机上的基本功能以外，开发者一定会有很多定制化的需求。本篇给大家提供一些进阶使用的tips。

定制化

推送展示定制化
个推推送服务的客户端展示定制化需求主要通过它的推送模板来实现。上一篇提到，调用推送方法前需要先构造一个template。

『 新建一个推送模版，以透传模板为例，透传顾名思义到达客户端后不做任何操作，由app选择处理
其他原生模板类型种类很多，支持各种客户端展现效果，包括弹框下载、打开链接等等。 』
TransmissionTemplate template = new TransmissionTemplate();
template.setAppId(appId);
template.setAppkey(appKey);
template.setTransmissionContent("测试用的透传文本");
template.setTransmissionType(1);

此处我们在示例里使用了TransmissionTemplate。这是个推的一个基本模板类型。使用这个模板，允许用户设置内容（如果二进制数据可以以base64方式转码），由个推推送系统将内容推送至APP，开发者自行对内容进行处理和展示。
除了这个模板类型以外，个推还提供了以下模板共开发者直接使用：

 NotificationTemplate # 通知栏模板
在通知栏显示一条含图标、标题等的通知，用户点击后激活您的应用
NotificationTemplate template = new NotificationTemplate();
template.setAppId(appId);
template.setAppkey(appKey);
template.setTitle("测试标题"); // 展示标题
template.setText("测试文本"); // 展示文本
template.setLogo("logo.png"); // 本地logo
template.setLogoUrl("http://imgurl.com/xxx.png"); // 外链logo
template.setIsRing(true); // 是否响铃
template.setIsVibrate(true); //是否震动
template.setIsClearable(true); //通知栏里是否可被清除
template.setTransmissionType(1); //理解启动应用

 LinkTemplate # 通知栏—链接模板
在通知栏显示一条含图标、标题等的通知，用户点击可打开您指定的网页
除了上面的设置以外LinkTemplate需要额外设置一个跳转的URL
LinkTemplate template = new LinkTemplate();
template.setUrl("http://www.baidu.com");

 NotyPopLoadTemplate # 通知栏—弹框下载模板
在通知栏显示一条含图标、标题等的通知，用户点击后弹出框，用户可以选择直接下载应用或者取消下载应用。除了appId，appKey以外还需要设置下面几个值：
NotyPopLoadTemplate template = new NotyPopLoadTemplate();
template.setPopTitle("弹框标题");
template.setPopContent("弹框内容");
template.setPopImage("POP.png");
template.setPopButton1("按钮1");
template.setPopButton2("按钮2");
template.setLoadIcon("下载图标");
template.setLoadTitle("下载标题");
template.setLoadUrl("下载地址");

其他接口

除了常用的pushMessageToSingle/ pushMessageToList/ pushMessageToApp/ 这三个推送接口以外，个推还提供了一些额外的方便用户使用和排查问题的接口。
 getClientIdStatus # 获取客户端在线与否状态
IGtPush push = new IGtPush(url, appKey, masterSecret);
push.getClientIdStatus(appId, cid);

这个接口会返回客户端在个推系统里的在线状态，个推里的在线状态决定了个推系统会给这个用户推送这条消息还是帮它缓存到离线库里。

 stop # 根据taskId停止推送任务
IGtPush push = new IGtPush(url, appKey, masterSecret);
push.stop(contentId);

当你发起了一个数量巨大的群推任务，会花费个推一定的时间去帮助你推送完所有的客户端。期间，你可以调用这个接口停止此次推送任务，还没有收到的客户端将不会再收到这次推送的消息。

回调接口

当你调用了服务端的api发送完一条消息，并收到服务端的返回success_online。如何确定这条推送是否真的到达了自己的客户端呢？个推提供了一个回调接口服务，开发者可以在个推开放者平台上注册一个回调URL，这样个推在确认客户端收到消息后，会向开发者填写的回调URL post一个http请求。
 填写回调URL

 回调协议
 协议使用HTTP POST方式，通过调用第三方预先提供的URL来传递信息。
 POST数据的内容采用Json格式。
 第三方返回Json格式的返回信息，表示是否成功接收到回执

 举例
 回执例子：
{"sign":"xxxxxxxxxxxxx","msgid":"test-msgid","desc":"test-descmsg","taskid":"test-taskid","appid":"xxxxxxxxxxxxx","code":"400", "cid":"test-cid"}
 响应例子：
{"code":"0","result":"ok"}
开发者在自己的服务端处理这个json串即可确定对应的消息推送是否真的到达了客户端。

小结

今天介绍的这些tips都是比较实用的，尽管很多开发者偏爱使用TransmissionTemplate来进行推送，然后最大自由的处理推送内容，可以完成很多功能，但是其他模板在特定的应用情形下，也能发挥其便捷的优势。比如更新应用，完全可以使用NotyPopLoadTemplate，只需要少许几个设置，就能在客户端完成弹框下载的功能；比如消息提示，可以直接使用NotificationTemplate，完成最基础也最常用的客户端收到推送，然后在通知栏提醒用户的功能。
回调接口也是默默无闻但是非常实用的功能，能使你在需要在确保消息送达的情景下做到百分百的安心。还没有使用的开发者们赶快尝试一下吧~