推送Java API文档

    最后更新于2014-12-11 10:21:01

    一、概述

    本文档主要讲解 WeCloud消息推送API 的 Java 版本封装开发包的使用,该版本目前按发送方式支持实时消息与定时消息,按接收类型支持所有人接收、按维度接收以及按token接收。


    二、接入说明

    Jar包方式,将该jar包以及第三方jar包commons-beanutils1.8.3和

    commons-logging1.1.3放在项目相应的libs目录下即可。


    三、使用介绍

    MessageClient


    该类对消息发送过程进行了封装,并且会在消息发送前进行参数有效性校验。在使用时主要关注1个构造方法和3个方法。

    方法名
    用法
    备注
    MessageClient(String appkey, String masterSecret)
    需要填入appkey和masterSecret
    appkey和masterSecret在创建应用时获得。
    MessageResult sendToAll(Message message)
    发送至所有人,你需要做的就是传入符合你需求的Message对象

    public MessageResult sendByDimension(Message message, List<Country> countrys, List<Tag> tags, List<NetType> netTypes,List<String> channels,List<String> versions) 

    按维度发送,需要在传入Message的基础上,再传入5个维度列表
    目前暂支持5个维度,可以填入一个或多个。有关维度信息参见附录。
    MessageResult sendByTokenList(Message message, List tokenList)
    按token发送,需要在传入Message的基础上,再传入tokenList
    token的个数不得超过100。


    Message

    该类是对待发送消息实体的封装,包含了消息的基本参数信息。以下是Message所包含字段的具体含义。

    字段名
    含义
    messageType
    代表消息类型,枚举型,具有COMMAND(命令)和NOTIFICATION(通知)。
    title
    代表消息标题,长度不得超过100。
    content
    代表消息内容,长度不得超过1000。

    messageStyle

    富媒体消息样式,默认值为0。

    message_url

    富媒体消息地址。

    sendType
    代表消息的发送类型,枚举型,具有REALTIME(及时消息)和DELAYED(定时消息)。
    messageAction
    代表消息点击后触发的动作,枚举型,具有OPEN_APP(打开应用),OPEN_ACTIVITY(打开指定界面),OPEN_WEB_SITE(打开指定网页)和CUSTOM(自定义)。
    actionParam
    代表动作参数,例如当messageAction为打开网页时,actionParam则为具体网站地址。
    sendTime
    代表消息的发送时间,定时消息需要设置。
    remandTime
    代表消息的有效期,默认为24小时,最大不得超过5天。
    platforms 代表app平台,目前支持android,ios(ios分为ios开发以及ios生产)。


    以上字段通过相应的set方法进行设置。


    四、使用样例

    以下各代码片段均来自jar包中的io.wecloud.message.api.example包

    代码是在使用jar包发送消息给所有人时的主要步骤,其中关键在于对Message的初始化,通过setXX()对Message包含的各个参数进行设置,如上面代码,将消息类型设置为通知消息,将消息点击后触发动作设为打开指定网页,进而设置了需要打开的网页地址。然后调用sendXX按指定要求发送消息。MessageResult对返回结果进行了封装。

    MessageClient messageClient = new MessageClient(appkey,masterKey);
     
     try {
         //initialize and set the message
         Message message=new Message();
         message.setMessageType(MessageType.NOTIFICATION);//set the message'type as notification
         message.setTitle(TITLE);//set the message's title
         message.setContent(CONTENT);//set the message' content
         message.setSendType(SendType.REALTIME);//set the send type of the message as delayed
         message.setMessageAction(MessageAction.OPEN_ACTIVITY);
         message.setActionParam("HomeActivity");
         List<Platform> platforms=new ArrayList<Platform>();
         platforms.add(Platform.IOS_PRO);
         message.setPlatforms(platforms);
         MessageResult messageResult = messageClient.sendToAll(message);//invocate sendMessageToAll method,send the message to all people
         System.err.println(JsonUtil.beanToJson(messageResult));
     } catch (APIConnectionException e) {
         e.printStackTrace();
     } catch (APIRequestException e) {
         e.printStackTrace();
     }



    以下代码完成按维度发送消息的功能,与发送给所有人不同的只是增加了5个用户维度而已,NetType,Tag,Country,channels以及versions分别代表用户的网络类型、所属标签,国家属性,渠道以及版本,你可以传入其中某一个维度,也可以传入多个维度,在某一个维度中你仍然可以传入一个或多个维度元素。

    MessageClient messageClient = new MessageClient(appkey,masterKey);
     try {
     //initialize and set the message
         Message message=new Message();
         message.setTitle(TITLE);//set the message's title
         message.setContent(CONTENT);//set the message' content
         message.setSendType(SendType.REALTIME);//set the send type of the message as delayed
         //initialize the dimension by net type and set it,you can add more than one type
         List<Platform> platforms=new ArrayList<Platform>();
         platforms.add(Platform.IOS_PRO);
         message.setPlatforms(platforms);
         List<NetType> netTypes=new LinkedList<NetType>();
         netTypes.add(NetType._3G);
         netTypes.add(NetType._4G);
         //initialize the dimension by tag and set it,you can add more than one tag
         List<Tag> tags=new LinkedList<Tag>();
         tags.add(Tag.CARTOON);
         tags.add(Tag._90S);
     
         //initialize the dimension by country and set it,you can add more than one country
         List<Country> countrys = new LinkedList<Country>();
         countrys.add(Country.AU);
         countrys.add(Country.BE);
         countrys.add(Country.OT);
         List<String> versions=new ArrayList<String>();
         versions.add("1.0");
         List<String> channels=new ArrayList<String>();
         channels.add("google");
         MessageResult messageResult = messageClient.sendByDimension(message, countrys,tags,netTypes,channels,versions);//send the message
         System.err.println(JsonUtil.beanToJson(messageResult));
     } catch (APIConnectionException e) {
         e.printStackTrace();
     } catch (APIRequestException e) {
         e.printStackTrace();
     }
    



    以下代码是按token发送消息的主要步骤,唯一的不同是需要传入tokenList。

    MessageClient messageClient = new MessageClient(appkey,masterKey);
     try {
         //initialize and set the message
         Message message=new Message();
         message.setTitle(TITLE);//set the message's title
         message.setContent(CONTENT);//set the message' content
         message.setMessageType(MessageType.RICH_MESSAGE);//set the message'type as notification
         message.setMessageUrl("wecloud.io");
         message.setSendType(SendType.REALTIME);//set the send type of the message as delayed
         WarmType warmType=new WarmType();
         //warmType.setOpenBLN(false);
         //warmType.setOpenBEL(false);
         //warmType.setOpenVIB(false);
         message.setWarmType(warmType);
         message.setMessageAction(MessageAction.OPEN_WEB_SITE);
         message.setActionParam("wecloud.io");
         List<Platform> platforms=new ArrayList<Platform>();
         platforms.add(Platform.IOS_PRO);
         message.setPlatforms(platforms);
         //initialize tokenList and add token into the list 
         //at present the tokenList's length cannot be beyond 100
         List<String> tokenList=new LinkedList<String>();
         tokenList.add(传入单个token);
         MessageResult messageResult = messageClient.sendByTokenList(message, tokenList);//send the message
         System.err.println(JsonUtil.beanToJson(messageResult));
     } catch (APIConnectionException e) {
         e.printStackTrace();
     } catch (APIRequestException e) {
         e.printStackTrace();
     }


    附录


    维度对应枚举类

    枚举元素

    含义

    NetType

    _2G

    2G

    _3G

    3G

    _4G

    4G

    WIFI

    WIFI

    Country

    US

    美国

    GB

    英国

    AU

    澳大利亚

    CA

    加拿大

    RU

    俄罗斯

    DE

    德国

    SG

    新加坡

    FR

    法国

    HK

    香港(中国)

    IT

    意大利

    TH

    泰国

    NO

    挪威

    MY

    马来西亚

    KR

    韩国

    SE

    瑞典

    ID

    印度尼西亚

    SA

    沙特阿拉伯

    ES

    西班牙

    DK

    丹麦

    PH

    菲律宾

    NL

    荷兰

    IL

    JP

    日本

    NZ

    新西兰

    BR

    巴西

    BE

    比利时

    CH

    瑞士

    CZ

    捷克

    ZA

    南非

    CN

    中国

    TW
    中国台湾
    IN
    印度
    PK
    巴基斯坦
    NG
    尼日利亚
    MX
    墨西哥
    VN
    越南
    IR
    伊朗
    UA
    乌克兰
    CL
    智利
    PT
    葡萄牙
    TR
    土耳其
    GR
    希腊
    FI
    芬兰
    CO
    哥伦比亚
    HU
    匈牙利
    EG
    埃及
    IE
    爱尔兰
    HR
    克罗地亚
    RO
    罗马尼亚

    OT

    其他

    Tag

    ONLINE_SHOPPING

    网购

    VIDEO

    视频

    GAME

    游戏

    STUDENT

    学生

    JOURNEY

    旅行

    CARTOON

    漫画

    NOVEL

    小说

    SPORTS

    体育

    SOCIAL_NET

    社交网络控

    NOVEL

    小说

    NEWS_READING

    新闻阅读

    POTENTIAL_PAYER

    潜在付费用户

    POTENTIAL_LOST_USER
    潜在流失用户
    NEW_USER
    新用户
    ACTIVE_USER 活跃用户