个推安卓推送——服务端api初级使用手册

前言

自从了解到推送可以提升用户留存率等诸多优势之后，越来越多的开发者开始在他们的服务中加入推送的功能。由于每天有大量新加入的开发者询问在他们的服务端中集成个推服务api的问题，特此写一篇初级使用文档，尽可能帮助大家少走弯路，一次成功。

首先你需要在个推开放着平台上注册你的应用，以及获得以下几个必要的值APPID ｜APPKEY　｜　MASTERSECRET，本文假设你已经完成上述步骤以及完成客户端SDK的集成。

原理

个推服务端api的原理非常简单，组装一个对象，塞进去需要的值，然后编码一下通过http请求发送到个推的推送服务器上，后面的复杂的推送流程就全权交给个推服务器了。
当然尽管原理非常简单，个推服务端api还是做了一些封装，最大限度节省用户工作量，比如组装对象设置特定的数据结构并编码，以及一些额外参数以完成版本的向后兼容等动作。

介绍

个推服务端sdk有多种语言支持，JAVA / Python / C# / PHP / GoLang等等，本文以JAVA版本为例介绍使用方法。
首先需要引入服务端sdk，也就是下面几个jar包，下载地址在个推官网上有

看名字很好理解这些jar包的作用，对于前三个commons开头的，codec是用来编码的，httpclient是用来构造http请求的，logging处理日志的；带sdk的三个jar自然是个推封装的组装请求的逻辑，以及提供对用户开放的使用接口；最后两个是用到的数据结构json和protobuf。

业务场景

单推——推送指定客户端推送
IPushResult pushMessageToSingle(SingleMessage message, Target target)
业务场景：一般适用于指定某个特定用户的推送，比如你要告诉某个用户他租的域名再不续费就要到期啦，或者有个好友@你啦，这种和独立用户紧密相关的个人消息。

群推——批量指定客户端推送
IPushResult pushMessageToList(String contentId, List targetList)
业务场景：一般适用于为某些用户推送消息的场景，比如你提取了一批今天生日的用户列表，给他们发送生日祝福等。

群推——指定应用名称全客户端推送
IPushResult pushMessageToApp(AppMessage message)
业务场景：一般适用为自己应用的所有用户推送同一条消息，比如今年2.14情人节，本店全场5折起之类的消息。

当然以上提到的业务场景只是暂时想到的，你完全可以套用到自己的业务场景里，组合使用各个接口，完成更多元的功能。

使用方式

各个接口使用方式大同小异，如果理解了原理应该很容易融会贯通。我将结合代码，以单推——toSingle接口来讲解使用方法。

1. 首先定义一些常量，我们应用的appId，appkey等值
   private static String appId = "aK6jeksP5C7CsjSSEqLAA3";
   private static String appKey = "tpDVam96sY8pxhwBupJ462";
   private static String masterSecret = "TBokfpttQJ6aHIhBE9y867";
   private static String cid = "ce018bb633066839fd0d6fb448bfcb23";
   private static String url = "http://sdk.open.api.igexin.com/apiex.htm";

2. 新建一个IGtPush实例，传入调用接口网址，appkey和masterSecret
   IGtPush push = new IGtPush(url, appKey, masterSecret);

3. 新建一个消息类型，单推一个用户的话，使用SingleMessage
   除了SingleMessage外还有ListMessage和AppMessage分别对应三个推送接口
   SingleMessage message = new SingleMessage();

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

5. 模板设置好后塞进message里，同时可以配置这条message是否支持离线，以及过期时间等，单位毫秒
   若设置离线，个推推送系统会为当前不在线的用户缓存离线消息，个推现在支持为每个用户缓存多条离线消息，离线时间最多三天，三天后会删除该条离线消息
   message.setData(template);
   message.setOffline(true);
   message.setOfflineExpireTime(1800 * 1000);

6. 新建一个推送目标，填入appid和clientId
   单推情况下只能设置一个推送目标，toList群推时，可以设置多个目标，目前建议一批设置50个左右。
   Target target = new Target();
   target.setAppId(appId);
   target.setClientId(cid);

7. 调用IGtPush实例的toSingle接口，参数就是上面我们配置的message和target
   IPushResult result = push.pushMessageToSingle(message, target);
   String response = result.getResponse().toString();
   System.out.println("返回值：" + response);

小结

至此，一个简单的推送就完成了。无论成功失败，服务端都会有返回结果。根据返回结果可以判断是哪里出错，然后可以有针对的排查问题。常见的错误返回有以下几个：

TokenMD5NoUsers 你填写的cid找不到，看看是不是填错了
AppIdNoUsers 该AppID未绑定用户，去开放平台看看是不是忘记绑定用户了
sign_error 鉴权错误，检查一下你填写的appId和appKey是不是有问题

还有其他类型的错误返回结果，就不一一列举了。下篇文章会写一下群推接口的调用，以及一些高级使用方法。请持续保持关注~