推送号SDK v1.0 使用说明文档

此 SDK ( version: 7.x.x ) 适用于PHP >= 5.3.0。

此 SDK 包含了如下几个功能：

数据的上传和下载。

• 发送推信
• 发送圈子消息
• 新建/删除发布者标签
• 获取发布者标签
• 获取我的消息（最近20条）
• 删除消息

---

预备工作

• 申请账号

首先，您需要通过正常的注册途径，注册获得推送号普通账号，通过C1认证，然后与客服人员联系(请发邮件至：guokai@tuisonghao.com)，申请开通开发者权限，权限开通后，您将获得两个秘钥access_key和secret_key，两个秘钥需要秘密保存，用于身份识别和签名。

• 下载SDK，引入文件

下载源码后，在您的代码中引入文件

<?php
require_once('./TSHApi.php');

• 返回数据格式

API返回值遵循以下json格式

{
    "code":<int>,
    "data":<array>,
    "info":<string>
}

其中，data和info根据不同接口函数，返回含义不同，错误码列表如下所示

错误码	含义
200	成功
101	操作失败
102	access_key错误
103	签名错误
104	未进行身份认证
105	参数错误
106	权限错误
301	检测为垃圾信息，不准发布
302	检测为质疑垃圾信息，等待人工审核

使用SDK

• 初始化

我们已经最大程度集成了sdk与服务器的交互细节，在使用SDK的时候，只需要初始化API类，调用相关函数即可，函数内部将自动进行封装、签名、发起请求等操作。

$access_key = 'YOUR_ACCESS_KEY';
$secret_key = 'YOUR_SECRET_KEY';
$tsh = new TSHApi($access_key,$secret_key);

• 发送推信

推信是以广播的形式发送给所有订阅者的消息，以消息流的模式展现给订阅者。每个用户都可以免费订阅其他人，并选择是否接收推信消息推送。推信必须有文字，可以最多附带9张图片，支持gif动图。

函数调用

//函数原型
/*
 * 发表feed
 * @author  archmage
 * @version 1.0
 * @param   $content string 发表的内容
 * @param   $imgs array 图片在本地的路径, 最多9张
 * @param   $is_push int 是否推送, 0: 不推送，1：推送
 * @param   $to_cates array 分发给哪些用户组，传入cate id，如果为空则分发给所有用户，默认为空
 */
public function publish($content,$imgs = array(), $is_push = 0,$to_cates='');

//使用示例
$content = "今天是2018年1月2日-";
$is_push = 1;
$imgs = array('./1.jpg','./2.gif');
$to_cates = array(1,3);
$r = $tsh->publish($content,$imgs,$is_push,$to_cates);
var_dump($r);

返回值

操作成功，data中返回消息id, "data":{"feed_id":6353829126722485251},操作失败，将返回对应错误码，以及在info中有提示信息。

• 发送圈子消息

圈子是发布者建立的付费消息群，用户进行C1认证之后，可以建立圈子，进入圈子需要支付一定费用，每个圈子通常是围绕某一个主题进行知识分享，信息交流。

函数调用

//函数原型
/*
 * 发表圈子消息
 * @author  archmage
 * @version 1.0
 * @param   $group_id int 圈子的id
 * @param   $content string 发表的内容
 * @param   $imgs array 图片在本地的路径, 最多9张
 */
public function group_publish($group_id, $content,$imgs = array());

//使用示例
$content = "今天是2018年1月2日-";
$group_id = 212601;
$imgs = array('./1.jpg','./2.gif');
$r = $tsh->group_publish($group_id, $content,$imgs);
var_dump($r);

返回值

操作成功，data中返回消息id, "data":{"feed_id":6353829126722485251},操作失败，将返回对应错误码，以及在info中有提示信息

• 新建/删除发布者标签

发布者可以为发送的每一条推信附带标签，标签需要预先建立，每个用户最多可以建立10个标签。

函数调用

//函数原型
/**
 * 新建推信标签
 * @author  archmage
 * @access  public
 * @version 1.0
 * @param   string $cate_name
 * @return  boolean
 */
public function add_cate($cate_name);


 /*
 * 删除发布者推信标签
 */
public function del_my_cate($cate_id);

// 使用示例
$name = "我的标签1";
$r = $tsh->add_cate($name);
var_dump($r);

$r = $tsh->del_my_cate(12345);
var_dump($r);

返回值

boolean

• 获取发布者标签

返回发布者推信标签。

函数调用

//函数原型
/*
 * 获取发布者标签
 */
public function list_my_cate();

//函数调用
$tsh->list_my_cate();

返回值

{
    "code":200,
    "data":[
        {
            "id":"10629",
            "user_id":"55498",
            "name":"9527",
            "subers_num":"0",
            "rank":"4",
            "status":"1"
        },
        {
            "id":"20131",
            "user_id":"55498",
            "name":"我的标签1",
            "subers_num":"0",
            "rank":"5",
            "status":"1"
        }
    ],
    "info":null
}

字段说明

字段	含义
id	标签的id
user_id	标签作者id
name	标签名字
suber_num	订阅该标签用户数量
rank	标签排名（在该作者所有标签中）
status	状态 （1：正常）

• 获取我的消息（最近20条）

用户可以获取最近发送的20条消息（包括推信和向圈子发送的消息）

函数调用

/*
 * 获取我发表的消息，只能获取最近20条。
 */
public function list_my_feed();

$r = $tsh->list_my_feed();
var_dump($r);

返回示例

{
    "code":200,
    "data":[
        {
            "id":"6353814228203888643",
            "user_id":"55498",
            "weight":"1",
            "to_cates":{
            },
            "content":"来自api的消息1514867360",
            "imgs":{
            },
            "ctime":"2018-01-02 12:29:20",
            "comment_num":"0",
            "like_num":"0",
            "status":"1",
            "cate_id":"0",
            "allow_comment":"1",
        },
        {
            "id":"6351298495292139523",
            "user_id":"55498",
            "weight":"1",
            "to_cates":{
            },
            "content":"按时12",
            "imgs":{
            },
            "ctime":"2017-12-26 13:52:42",
            "comment_num":"0",
            "like_num":"0",
            "status":"1",
            "cate_id":"0",
            "allow_comment":"1"
        }
    ],
    "info":null
}

字段说明

字段	含义
id	消息的id
user_id	消息作者id
weight	是否推送给用户(0:不通知用户;1:通知用户;)
to_cates	发布到哪些标签下面
content	内容
imgs	图片
ctime	发布时间
comment_num	评论数量（仅圈子内消息有效）
like_num	点赞数量
status	状态 （1：正常）
cate_id	圈子的id（如果是圈子的消息，否则为0）
allow_comment	是否允许评论（仅圈子消息）

• 删除消息

函数调用

//函数原型
/*
 * 删除我的某一条feed
 * @param   $feed_id string
 */
public function del_my_feed($feed_id);

//调用示例
$tsh->del_my_feed(6351298495292139523);

返回值

{
    "code": 200,
    "data": 1,
    "info": null
}