西瓜消息推送

  1. SDK集成指南
  2. 推送使用
  3. API集成指南

1. SDK集成指南

1.1 版本说明

推送版本号:v0.0.1
注意:消息推送SDK支持android 2.2以及以上系统

1.2 集成流程

1.3 开通推送

首先需要进入西瓜SDK官方网站为应用开通推送服务(点击进入官网) 开通推送前,应用必须要已经在西瓜SDK中建立,如何建立应用,请参考西瓜SDK接入说明文档(快速接入说明)。

1.3.1 进入消息推送

进入推送服务的入口有两个:

  • 服务列表进入
    1.操作如下图,点击消息推送即可进入消息推送服务

    2.消息服务主页

  • 用户中心进入
    1.在西瓜官网首页,如下图位置,点击用户中心

    2.在用户中心选择消息推送,点击进入

    3.消息服务主页

1.3.2 开通推送

1.选择包名,在第一次开通推送服务时,需要手动选择包名,不会自动指定默认包名

说明:

  • 开通推送,必须要先选择包名。
  • 有多包名的时候,选择的第一个包名将不可修改。
  • 添加多包名的时候,既可以手动添加 ,也可以选择添加全部。

2.点击开启推送

3.开通成功,如下图所示

1.4.SDK 集成

目前接入的 API 主要用于应用需要自己处理部分消息或通知的情景。方便应用在服务器端对客户端进行控制。

1.4.1 消息回调

1.4.1.1 原生android接口

  • 接口:

    setXGMessageCallBack(MessageCallBack messageCallBack)
    
  • 参数:

MessageCallBack

public interface MessageCallBack {
    //处理自定义通知
    public void dealWithNotificationMessage(String msgcustom);
    //处理自定义消息
    public void dealWithCustomMessage(String msgcustom);
}
  • 举例:
callback = new MessageCallBack() {

                @Override
                public void dealWithNotificationMessage(String msgcustom) {
                    // TODO Auto-generated method stub

                }

                @Override
                public void dealWithCustomMessage(String msgcustom) {
                    // TODO Auto-generated method stub

                }
};

XGSDK.getInstance().setXGMessageCallBack(callback);

1.4.1.2 Unity 接口

  • 接口:

自定义通知回调:

public abstract void dealWithNotificationMessage(string msg);

自定义消息回调:

public abstract void dealWithCustomMessage(string msg);
  • 参数:
  • 举例:
public class XGSDKCallbackImpl : XGSDKCallback
{
    //自定义通知回调
    public override void dealWithNotificationMessage(string msg)
    {
        //Debug.Log("Unity3D dealWithNotificationMessage" + msg);
        ChannelUtils.DialogHelper.getInstance ().showCallbackTip (msg);

    }

    //自定义消息回调
    public override void dealWithCustomMessage(string msg)
    {
        //Debug.Log("Unity3D dealWithCustomMessage" + msg);
        ChannelUtils.DialogHelper.getInstance ().showCallbackTip (msg);
    }
}

注意:此处的msg可能是空字符串。需要 CP 自己处理相应情况。XGSDK只负责消息推送,但是不参与消息具体内容的逻辑处理。

1.4.1.3 Cocos2d 接口

  • 接口:
继承 XGSDKCallback 然后实现回调,具体需要实现的方法如下:

//dealWithNotificationMessage
virtual void dealWithNotificationMessage(const char* msg)=0;

//dealWithCustomMessage

virtual void dealWithCustomMessage(const char* msg)=0;
  • 参数:
  • 举例:
XGDemoCallback.h
class XGDemoCallback : public XGSDKCallback
{
    void dealWithNotificationMessage(const char* msg);

    void dealWithCustomMessage(const char* msg);
}

XGDemoCallback.cpp
void XGDemoCallback::dealWithNotificationMessage(const char *msg)
{
    CCMessageBox(msg,"dealWithNotificationMessage");
}

void XGDemoCallback::dealWithCustomMessage(const char *msg)
{
    CCMessageBox(msg,"dealWithCustomMessage");
}

注意:此处的msg可能是空字符串。需要cp自己处理相应情况。XGSDK只负责消息推送,但是不参与消息具体内容的逻辑处理。

1.4.2 集成打包

在完成SDK集成以后,直接使用西瓜打包工具打出渠道包即可实现推送,打包工具使用请参考《打包指南》,无需做任何特殊配置。

说明: 只有开通过推送的产品才能在打包时自动集成推送,只要第一次开通成功,后续会一直集成推送。

1.4.3 测试推送

发送一个测试消息测试推送是否集成成功,发送测试消息的方式参见推送使用章节(2.推送使用 章节)。

2. 推送使用

2.1 配置

2.1.1 开启推送

在第一次为应用开启推送的时候,将获取到该应用推送相关参数,此参数不可修改。

2.1.2 关闭推送

1.关闭推送以后就不可以推送消息,已经推送的正在执行的不受影响
2.即使关闭了推送,但是打包工具集成的时候,仍然会集成推送SDK

2.1.3 保存设置

1.因为配置中能修改的只有包名,因此保存设置中保存的是修改以后的包名
2.没有配置的包名将不能收到推送的消息
3.包名配置中的所有包名是来源于应用在“渠道接入”中“渠道参数”里配置的包名,因此在这里只能选择,不能输入
4.在推送中如果只配置一个包名,这个包名是可以修改的,如果配置了多包名,第一包名是不能修改的

2.2 推送管理

2.2.1 新建消息

推送的消息分为两类:
1.通知:在手机通知栏上会显示一条通知信息,通知用于提示用户
2.自定义消息:不会展示在手机通知栏上,其内容完全由开发者自己定义;自定义消息直接推送到应用中,应用内部将获取到消息内容,应用自行决定如何处理。

2.2.1.1 通知

1.Android 平台

  • UI:

  • 参数说明:
    关键参数 说明
    后继动作的自定义行为 选择自定义行为,在自定义行为中输入参数,在用户点击通知以后,这些参数将直接传递给应用,应用需要自己解析执行
    发送给个人 需要输入的device token,需要从应用的log中获取或者调用 API获取
    自定义通知栏 根据经验在图标制作时: 大图标:图片为64*64dp或者64*64px的图标,注意四周各留1个dp的空白像素,不至于显示太拥挤 小图标:图片为24*24dp或者24*24px的图标,在超高分辨率的手机中可以用48*48

2.iOS 平台

  • UI:

  • 参数说明:
    关键参数 说明
    角标 消息推送标记数,app图标上角小红圈中显示的数字只能是数值
    categoryID 注册通知时自定义action的Category.identifier,仅在ios8及以上系统有效

2.2.1.2 自定义消息

自定义消息目前只支持android,自定义消息配置参数如图:

2.2.2 测试设备

此处可以添加测试设备,用来过滤测试消息,如果需要发送测试消息,能够接收到测试消息的测试设备都必须在此处进行添加。

3. API集成指南

提供给第三方使用的接口集。

3.1 消息推送接口

3.1.1 功能说明

提供给外部调用推送消息。

3.1.2 调用地址

POST : http://push.xgsdk.com:8443/pushserver/api/push

3.1.3 调用参数

  • Android平台
{
“msgId”:“XXXXXXXXX”, 消息ID 最长64位,可选
“msgName”:”XXXXXXXX”, //消息名,最长75个字符,必填
“msgType”:“XXXXXXX”, // notification 和 message,必填
“msgTitle”:“XXXXXXXXXX”, 消息标题 45个字符以内,在平台类型为android时消息类型为notification必填,消息类型为message不填和平台为IOS不填
“msgContent”:”XXXXXXXXX”, 消息内容,通知为400个字符以内,消息为1500个字符以内,必填
“appId”:“XXXXXXX”, 西瓜的应用id,必填
“afterAction”:“XXXXXX”, 后续动作 app、activity、url、custom,msgtype为notification时必填,msgtype为message不填
“actionActivity”:“XXXXXXX”, //如果after_action为activity 就设置这个值为activity的名字
“actionUrl”:”XXXXXXXXXXX”, //如果after_action为url 就必须设置这个值,必须以http://和https:// 开头
“actionCustom”: “XXXXXXXX”, //如果after_action为custom  就设置这个值长度在200个字符以内
“extraParams”:
“{
\“key1\”:\”value1\”,
\“key2\”:\”value2\”,
\“key3\”:\”value3\”
}”, //扩展参数,参数值必须是字符串,内容是json格式的,其中的key value对最多10个,其中key不能大于50个字符,value不能大于150个字符,且可不能为“d”、“p”,可选
”uids“:”XXXXX,XXXXX,XXXXX”, //用户ID的一个list,value为渠道中的用户ID,用户ID之间用”,”号隔开,总的用户ID 最大500个,每个最长128位
“sendType”:”XXXXXXXX”, //发送类型 immediate(立即发送)和schedule (定时发送),必填
“sendTime”:”XXXXXXXXX”, //如果是send_type为schedule就设置这个发送时间,时间必须晚于当前时间1分钟以上 格式:yyyy-MM-dd HH:mm:ss,可选
“expireTime”:”XXXXXXXXX”,//过期时间,如果是定时发送,就必须晚于send_time 30分钟以上,但是不能晚于4天,如果是立即发送,就必须晚于当前时间 30分钟以上,格式:yyyy-MM-dd HH:mm:ss,可选
“isTest”:“XXXX”, //true表示测试消息 false表示非测试消息,必填
“platform”:”XXXXX”, //平台 android和ios 必填
“customSound”:”xxxxx”, // 音频文件的文件名。如果该值非空,则认为使用自定义声音
“commitTime”:”XXXXXXXX”, 消息提交时间  格式:yyyy-MM-dd HH:mm:ss 必填
“sign”:”XXXXXXXXXXXXXXXXXX” //签名字段 , 必填
}
  • iOS平台

{
“msgId”:“XXXXXXXXX”, 消息ID 最长64位,可选
“msgName”:”XXXXXXXX”, //消息名,最长75个字符,必填
“msgType”:“XXXXXXX”, // 固定填写notification,必填
“msgContent”:”XXXXXXXXX”, 消息内容,通知为400个字符以内必填
“appId”:“XXXXXXX”, 西瓜的应用id,必填
“extraParams”:
“{
\“key1\”:\”value1\”,
\“key2\”:\”value2\”,
\“key3\”:\”value3\”
}”, //扩展参数,参数值必须是字符串,内容是json格式的,其中的key value对最多10个,其中key不能大于50个字符,value不能大于150个字符,且可不能为“d”、“p”,可选
”uids“:”XXXXX,XXXXX,XXXXX”, //用户ID的一个list,value为渠道中的用户ID,用户ID之间用”,”号隔开,总的用户ID 最大500个,每个最长128位
“sendType”:”XXXXXXXX”, //发送类型 immediate(立即发送)和schedule (定时发送)
“sendTime”:”XXXXXXXXX”, //如果是send_type为schedule就设置这个发送时间,时间必须晚于当前时间10分钟以上 格式:yyyy-MM-dd HH:mm:ss
“expireTime”:”XXXXXXXXX”,//过期时间,必须晚于send_time 30分钟以上,但是不能晚于4天 格式:yyyy-MM-dd HH:mm:ss
“isTest”:“XXXX”, //true表示测试消息 false表示非测试消息
“platform”:”XXXXX”, //固定填写ios
“customSound”:”xxxxx”, // 音频文件的文件名。如果该值非空,则认为使用自定义声音
“commitTime”:”XXXXXXXX”, 消息提交时间  格式:yyyy-MM-dd HH:mm:ss
“sign”:”XXXXXXXXXXXXXXXXXX” //签名字段
}

3.1.4 样例请求

{
    "msgId": "api_test_000001",
    "msgName": "api_test_one",
    "msgType": "notification",
    "msgTitle": "api_test_one",
    "msgContent": "api test one",
    "appId": "91000335",
    "afterAction": "app",
    "extraParams": "{\"key1\":\"111111111111\",\"key2\":\"222222222222\"}",
    "uids":"4399__1603184450, amigo__312DCFE962A44017B5239DE2285DCB88,amigo__7CA63A3F4850445482DD9F09A9B7C458",
    "sendType": "immediate",
    "expireTime": "2016-03-25 19: 21: 00",
    "isTest": "true",
    "platform": "android",
    "commitTime": "2016-03-24 16: 30: 00",
    "sign": "y/2NFL2yD4k3RK/Dv4locyeo9cw="
}

3.1.5 返回参数

在正常情况下,返回结果的HTTP状态码为200,错误情况下返回的HTTP状态码为500。

{
“ret”:”XXXXXXXXXXXXXXX” //fail,success
“data”:
{
“errorCode”:”********”,//当ret为 fail的时候根据此值判断错误原因
}
}

3.1.6 签名要求

所有的第三方接口都需要使用HMAC-SHA1 算法来生成签名,该签名算法需要base_string 和key。再对加密结果进行base64编码传输:
1.签名的key为西瓜为应用分配的XgServerKey
2.签名的base_string 是把参数key按字母排序,按key1=value1&key2=value2&...来拼接签名源串,将值为空的参数和sign签名字段去掉,再在最后拼接上XgServerKey,注意的是这里拼接XgServerKey时不需要用&,直接拼上XgServerKey就可以了 base_string = “key1=value1&key2=value2&...”+XgServerKey;

  • 对base_string 使用HMAC-SHA1进行加密
  • 对加密结果使用base64编码

3.2 错误码描述

API通过HTTP Status Code来说明请求是否成功, 200表示成功, 500表示失败。

3.2.1 HTTP常见Status Code及其含义

表中错误码只是表示http请求是否成功,是http协议规定的错误码:

错误码 错误码描述
200 OK 请求成功
201 CREATED 创建成功
202 ACCEPTED 更新成功
400 BAD REQUEST 请求的地址不存在或者包含不支持的参数
401 UNAUTHORIZED 未授权
403 FORBIDDEN 被禁止访问
404 NOT FOUND 请求的资源不存在
500 INTERNAL SERVER ERROR 内部错误

3.2.2 API服务返回码

表中返回码是返回的消息体中code的值,就是在请求成功后,也有可能出现业务逻辑上的错误:

错误码 错误码描述
10000 AppId为空
10001 Platform为空或则不为” android” 和”ios”
10002 不存在对应ID的应用或则应用没有开通推送
10003 签名不匹配
10004 消息ID不合法,长度不能大于64个字符
10005 消息名不合法,不能为空且长度不能大于75个字符
10006 消息类型不合法,消息类型必须为notification和message
10007 消息title不合法,长度不能大于45个字符,且在平台为android,消息类型为notification时必填,其他状态下不填
10008 消息内容不能为空,消息类型为notification时,消息内容不能大于400个字符,消息类型为message是,消息内容不能大于1500个字符
10009 afteraction参数不能为空,只有android平台的notification有此参数,并且参数值为:app、activity、url、custom
10010 actionactivity参数在afteraction为activity时不能为空,且长度不能大于2048
10011 Actionurl参数在afteraction为url时不能为空,且需要以http:// 或者https://开头
10012 Actioncustom参数在afteraction为custom时不能为空,且长度不能大于200个字符
10013 extraParams参数值必须是json串,其中的key value对最多10个,其中key不能大于50个字符,value不能大于150个字符,且可不能为“d”、“p”
10014 Uids不能为空,必须为json字符串,key为渠道ID(固定填写西瓜分配给应用的渠道ID),value为渠道中的用户ID,用户ID之间用”,”号隔开,总的用户ID 最大500个,每个最长128位
10015 sendType参数异常,参数值只能是immediate(立即发送)和schedule (定时发送)
10016 Sendtime字段非法,send_type为schedule就设置这个发送时间,时间必须晚于当前时间1分钟以上 格式:yyyy-MM-dd HH:mm:ss
10017 expiretime字段非法,如果是定时发送,就必须晚于send_time 30分钟以上,但是不能晚于4天,如果是立即发送,就必须晚于当前时间 30分钟以上,格式:yyyy-MM-dd HH:mm:ss
10018 isTest参数非法,参数必须为”true”或则”false”
10019 commitTime参数非法,参数不能为空,格式必须为:yyyy-MM-dd HH:mm:ss
10020 消息存储异常
10021 创建消息发送任务异常