本SDK是为方便PHP开发者在服务端调用百度云推送服务而提供的PHP语言开发工具包。
开发者可以通过修改sdk根目录中的configure.php对SDK进行配置。
大部分业务方法在调用成功时直接返回 key => value 形式的数组。在失败时则根据SUPPRESS_EXCPTION的配置不同，将返回false或抛出异常。在返回false的时候，使用getLastError及getLaseErrorCode获取错误信息。具体错误信息可参见：云推送服务端API错误码。
关于数据项中的 -1： 在一些数据统计接口中，鉴于0存在统计上的数值意义，为保证类型上的统一，所以使用了特殊的值 -1，用于表示该统计项不被支持或尚未有统计数据产生。
以下文档如无特殊说明，只描述正确返回格式。
msg_type API中出现的msg_type，用于表示消息的内容类型，可能的值有以下几种：
range_type API中出现的range_type，用于表示消息的推送范围类型，可能的值有以下几种：
消息格式 在推送通知消息时，对于消息的格式存在一定要的结构性要求，并且不同平台存在差异，具体可参见 消息格式说明
如果之前推送是透传消息，即msg_type字段值是0，此时，如果要兼容各大厂商代理的推送，需要使用双文本的消息进行推送，这样保证不支持厂商推送的透传消息正常下发，如果一直是通知消息或者新接入的app可以忽略双文本消息，直接进行msg_type为1的通知推送。具体可参见 消息格式说明中的双文本消息的说明
3.0版本的云推送服务，为了更好的统计数据及简化使用，对应用的支持平台进行区分，每个应用仅支持一个平台，2.0版本中的每个应用在升级至3.0后，将拆分为两个相同appid的应用，所以需要在使用SDK的过程中设置 device_type 参数指定操作那一个平台的应用，device_type 的取值有以下两种：
push服务的包装对象。包装rest api的业务方法。
Description： 创建一个PushSDK实例。
Parameters：
apiKey string [optional] 开发者apikey。
secretKey string [optional] 开发者当前secretKey，在应用重新生成secret key后，旧的secret key将失效。
curlopts array [optional] 用于cUrl::curl_setopt方法的控制参数。 @See curl_setopt相关内容
Example：
$ak = 'ak of your app';
$sk = 'sk of your app';
$sdk = new PushSdk($ak,$sk);
// to do something...
Description： 设置或变更 api key
Parameters：
Return value：
void
Description： 设置或变更 secret key
Parameters：
Return value：
void
Description： 设置或变更 device key，关于device_type的的说明，请参见:关于device_type参数使用说明
Parameters：
Return value：
void
Description： 获得方法调用所生成的 RequestId
Parameters：
null
Return value：
int | null：成功调用服务端方法后，由服务端返回的RequestId。在追踪问题时。需要提供这个值。在产生SDK端异常时，返回null。
Example：
// get the sdk instance
$rs = $sdk -> pushAll('send the message and failed.');
// 当rs的返回值为false，则表示方法调用失败
if($rs === false){
$errMsg = $sdk -> getLastErrorMsg();
$errCode = $sdk -> getLastErrorCode();
$logId = $sdk -> getRequestId();
// log the exception
print_r("Call SDK Failed：[RequestId:$logId][error:$errCode,$errMsg];");
}
Description： 获得最后一次调用所产生的错误消息。
Parameters：
null
Return value：
String：调用失败的错误描述信息。
Description： 获得最后一次调用所产生的错误码。
Parameters：
null
Return value：
int：调用失败原因的错误码。
Description： 根据channel_id，向单个设备推送消息。
Parameters：
注意： 消息体大小，对于Android消息不大于4KB；iOS消息不大于2KB。在使用双文本推送时，建议推送通知类型消息，即msg_type = 0, extra_msg_type = 1；如果有长连接透传消息的请求建议使用双文本推送，msg_type = 1, extra_msg_type = 0。建议推送代理时，每次使用不同的topic，否则相同的设备推送多条相同消息时，端上只会收到一条消息。
Return value：
Array(key => value) 内容为服务端返回的array对象，包含以下内容。
Example：
// 创建消息内容
$msg = array(
'description' => 'notice msg',
);
// 消息控制选项。
$opts = array(
'msg_type' => 1,
);
// 发送
$rs = $sdk -> pushMsgToSingleDevice('0001112223334445'，$msg，$opts);
if($rs !== false){
print_r($rs); // 将打印出 msg_id 及 timestamp
}
Description： 广播，向当前应用下所有设备发送一条消息
Parameters：
注意： 消息体大小，对于Android消息不大于4KB；iOS消息不大于2KB。在使用双文本推送时，建议推送通知类型消息，即msg_type = 0, extra_msg_type = 1；如果有长连接透传消息的请求建议使用双文本推送，msg_type = 1, extra_msg_type = 0。建议推送代理时，每次使用不同的topic，否则相同的设备推送多条相同消息时，端上只会收到一条消息。
Return value：
Array(key => value) 内容为服务端返回的array对象，包含以下内容。
Example：
// 创建消息内容
$msg = array(
'description' => 'notice msg',
);
// 消息控制选项。
$opts = array(
'msg_type' => 1,
);
// 发送
$rs = $sdk -> pushMsgToAll($msg，$opts);
if($rs !== false){
print_r($rs); // 将打印出 msg_id 及 timestamp
}
Description： 组播，向一个指定的组内的所有设备发送一条消息
Parameters：
注意： 消息体大小，对于Android消息不大于4KB；iOS消息不大于2KB。在使用双文本推送时，建议推送通知类型消息，即msg_type = 0, extra_msg_type = 1；如果有长连接透传消息的请求建议使用双文本推送，msg_type = 1, extra_msg_type = 0。建议推送代理时，每次使用不同的topic，否则相同的设备推送多条相同消息时，端上只会收到一条消息。
Return value：
Array(key => value) 内容为服务端返回的array对象，包含以下内容。
Example：
// 创建消息内容
$msg = array(
'description' => 'notice msg',
);
// 消息控制选项。
$opts = array(
'msg_type' => 1,
);
// 发送
$rs = $sdk -> pushMsgToTag('MyTagName'，$msg，$opts);
if($rs !== false){
print_r($rs); // 将打印出 msg_id 及 send_time
}
Description： 批量单播，向一组指定的设备(channel_id)，发送一条消息
Parameters：
注意： 消息体大小，对于Android消息不大于4KB；iOS消息不大于2KB。在使用双文本推送时，建议推送通知类型消息，即msg_type = 0, extra_msg_type = 1；如果有长连接透传消息的请求建议使用双文本推送，msg_type = 1, extra_msg_type = 0。建议推送代理时，每次使用不同的topic，否则相同的设备推送多条相同消息时，端上只会收到一条消息。
Return value：
Array(key => value) 内容为服务端返回的array对象，包含以下内容。
// 创建消息内容
$msg = array(
'description' => 'notice msg',
);
// 消息控制选项。
$opts = array(
'msg_type' => 1,
);
// 发送给以下五个设备，每个设备ID应与终端设备上产生的 channel_id 一一对应。
$idArr = array(
'000000000000001',
'000000000000002',
'000000000000003',
'000000000000004',
'000000000000005',
);
// 发送
$rs = $sdk -> pushBatchUniMsg($idArr，$msg，$opts);
if($rs !== false){
print_r($rs); // 将打印出 msg_id 及 send_time
}
Description： 根据 msg_id，查询消息推送状态，到达数，预计数等信息。
Parameters：
Return value：
Array(key => value) 内容为服务端返回的array对象，包含以下内容。
Example：
// 发送一条广播消息，并在二分钟后查看消息状态。
// 创建消息内容
$msg = array(
'description' => 'notice msg',
);
// 消息控制选项。
$opts = array(
'msg_type' => 1,
);
// 发送
$rs = $sdk -> pushMsgToAll($msg，$opts);
if($rs !== false){
print_r($rs); // 将打印出 msg_id 及 timestamp
$msg_id = $rs['msg_id'];
sleep(120); // 延时二分钟，用于消息下发及数据统计。
$info = $sdk -> queryMsgStatus($msg_id);
print_r($info);
}
Description： 根据 timer_id，获取一个定时或周期任务的消息推送记录。
Parameters：
Return value：
Array(key => value) 内容为服务端返回的array对象，包含以下内容。
Example：
// 发送一条5分钟后的定时广播消息，并在10分钟后查看消息状态。
// 创建消息内容
$msg = array(
'description' => 'notice msg',
);
// 消息控制选项。
$opts = array(
'msg_type' => 1,
'send_time' => time() + 5 * 60
);
// 发送
$rs = $sdk -> pushMsgToAll($msg，$opts);
if($rs !== false){
print_r($rs); // 将打印出 msg_id 及 timestamp
$timer_id = $rs['timer_id'];
// 延时10分钟，用于消息下发及数据统计。
sleep(60 * 10);
// 取得发送记录。
$record = $sdk -> queryTimerRecords($timer_id);
if($record !== false && count($record['result']) > 0){
// 查询发送状态
print_r($sdk -> queryMsgStatus($record['result'][0]['msg_id']));
}
}
Description： 查询尚未完成的定时推送任务信息列表。
Parameters：
Return value：
Array(key => value) 内容为服务端返回的array对象，包含以下内容。
Example：
// 发送一条5分钟后的定时广播消息. 并即时查看任务状态。
// 创建消息内容
$msg = array(
'description' => 'notice msg',
);
// 消息控制选项。
$opts = array(
'msg_type' => 1,
'send_time' => time() + 5 * 60
);
// 发送
$rs = $sdk -> pushMsgToAll($msg，$opts);
if($rs !== false){
print_r($rs); // 将打印出 msg_id，timer_id 及 timestamp
$timer_id = $rs['timer_id'];
$list = $sdk -> queryTimerList();
if($list !== false && $list -> total_num > 0){
foreach($list as $item){
if($item['timer_id'] === $timer_id)){
print_r($item); //将打印相关信息。
}
}
}
}
Description： 根据 topic_id，获取该分类主题的消息推送记录。
Parameters：
Return value：
Array(key => value) 内容为服务端返回的array对象，包含以下内容。
Example：
// 创建消息内容
$msg = array(
'description' => 'notice msg',
);
// 消息控制选项。
$opts = array(
'msg_type' => 1,
'topic_id' => 'topic1',//为批量单播消息指定topic
);
// 发送给以下五个设备，每个设备ID应与终端设备上产生的 channel_id 一一对应。
$idArr = array(
'000000000000001',
'000000000000002',
'000000000000003',
'000000000000004',
'000000000000005',
);
// 发送
$rs = $sdk -> pushBatchUniMsg($idArr，$msg，$opts);
if($rs !== false){
print_r($rs); // 将打印出 msg_id 及 send_time
$msg_id = $rs['msg_id'];
$list = $sdk -> queryTopicRecords('topic1');
if($list !== false && $list -> total_num > 0){
foreach($item as $list){
if($item['msg_id'] === $msg_id)){
print_r($item); //将打印相关信息。
}
}
}
}
Description： 查询批量单播所使用过的分类主题及推送和到达的数据量
Parameters：
Return value：
Array(key => value) 内容为服务端返回的array对象，包含以下内容。
Example：
// 查询所用到的分类主题列表，并配合queryTopicRecords查询最近推送过的10条消息
//拿到分类主题列表。
$topicList = $sdk -> queryTopicList();
if($topicList !== false && $topicList -> total_num > 0){
foreach($topicList['result'] as $item){
// 查询推送记录
$msgList = $sdk -> queryTopicRecords($item['topic_id'],array('limit' => 10));
print_r($msgList);
}
}
Description： 创建一个标签组
Parameters：
Return value：
Array(key => value) 内容为服务端返回的array对象，包含以下内容。
Description： 删除一个已存在的标签组
Parameters：
Return value：
Array(key => value) 内容为服务端返回的array对象，包含以下内容。
Example：
// 创建一个组，随后删除。
$rs = $sdk -> createTag('tmpTag');
if($rs !== false && $rs['result'] === 0){ //判断是否创建成功
echo "create tag ok! \n";
$delRs = $sdk->deleteTag('tmpTag');
if($rs !== false && $rs['result'] === 0){ //判断是否删除成功
echo "delete tag ok! \n";
}
}
Description： 查询已存在的标签组
Parameters：
Return value：
Array(key => value) 内容为服务端返回的array对象，包含以下内容。
Example：
$rs = $sdk->queryTags();
if($rs === false){ //确认返回。
//get error。
echo $sdk -> getLastErrorMsg();
echo "/n";
}else if($rs['total_num'] > 0){
foreach($rs['result'] as $item){
extract($item);
echo "tid：$tid; tagname:$tag，createTime:$create_time";
}
}
Description： 添加设备到已创建的标签组。
Parameters：
Return value：
Array 内容为服务端返回的array对象，每个元素包含以下内容。
Example：
/创建一个有五个设备的组，并向该组发送一条消息。
// 创建消息内容
$msg = array(
'description' => 'notice msg',
);
// 消息控制选项。
$opts = array(
'msg_type' => 1
);
// 发送给以下五个设备，每个设备ID应与终端设备上产生的 channel_id 一一对应。
$idArr = array(
'000000000000001',
'000000000000002',
'000000000000003',
'000000000000004',
'000000000000005',
);
$rs = $sdk->createTag('tag_new');
if($rs !== false){
if($sdk -> addDevicesToTag('tag_new',$idArr) !== false){
// 发送
$rs = $sdk -> pushMsgToTag('tag_new'，$msg，$opts);
// check result and other something。
// ....
}
}
Description： 将添加到组的设备从组中移除。
Parameters：
Return value：
Array 内容为服务端返回的array对象，每个元素包含以下内容。
Description： 查询当前组内的设备数量。
Parameters：
Return value：
Array(key => value) 内容为服务端返回的array对象，包含以下内容。
Example
// 添加以下五个设备，每个设备ID应与终端设备上产生的 channel_id 一一对应。
$idArr = array(
'000000000000001',
'000000000000002',
'000000000000003',
'000000000000004',
'000000000000005',
);
$rs = $sdk->createTag('tag_new');
if($rs !== false){
if($sdk -> addDevicesToTag('tag_new',$idArr) !== false){
//查询设备数
$rs = $sdk -> queryDeviceNumInTag('tag_new');
// log
print_r($rs); // device_num is 5。
}
}
Description： 取得当前APP的30天内的设备数统计
Parameters：
null
Return value：
array(key => value) 内容为服务端返回的array，包含以下内容：
Description： 取得一个分类主题的30天内的消息统计
Parameters：
Return value：
array(key => value) 内容为服务端返回的array，包含以下内容：
在SDK的使用过程中遇到的异常包括以下两类：
| 错误码 | 错误信息 |
|---|---|
| 1 | SDK initialization error |
| 2 | SDK running error |
| 3 | SDK params missing |
| 4 | SDK params invalid |
| 5 | http status is ok，but REST returned invalid json string |
服务端异常： 能成功与服务端交互，但由于业务功能，参数等内容产生的，由服务端下发的异常信息。