qy-platform/ThinkPHP/Library/Vendor/Jpush/doc/api.md

# JPush PHP Server SDK Doc

JPush PHP Server SDK主要提供4部分API

* [Push API](http://docs.jpush.io/server/rest_api_v3_push/)
* [Report API](http://docs.jpush.io/server/rest_api_v3_report/)
* [Device API](http://docs.jpush.io/server/rest_api_v3_device/)
* [Schedule API](http://docs.jpush.io/server/rest_api_push_schedule/)


### Init API : 初始化

在调用推送之前，我们必须先初始化JPush，调用以下代码可以进行快速初始化

```php
$client = new JPush($app_key, $master_secret);
```

在初始化JPush的时候，可以指定一些初始参数，如**日志路径**，**失败请求最大重试次数**

```php
$client = new JPush($app_key, $master_secret, $log_path, $max_retry_times);
```

PS:

* 默认日志路径为`./jpush.log`,即保存在当前运行目录，如果想关闭日志，可以指定为`null`。
* 默认请求失败最大重试次数为3，如果想请求关闭失败重试功能，可以指定为`null`。

### Push API : 构建推送PushPayload

在初始化JPush后，调用以下代码将返回一个推送Payload构建器，它提供丰富的API来帮助你构建PushPayload。

```php
$push = $client->push();
```
通过[JPush Push API](docs.jpush.io/server/rest_api_v3_push/) 我们知道，一个PushPayload是由以下几个部分构成的：

* Platform
* Audience
* Notification
* Message
* SmsContent
* Options

接下来我们将了解如何用PushPayload构建器灵活地创建PushPayload。

#### Platform Setter

我们可以通过以下代码指定Platform的对象为`all`

```php
$push->setPlatform('all')
```
如果想指定为特定平台:

```php
$push->setPlatform('ios', 'android')
```

亦或者:

```php
$push->setPlatform(array('ios', 'android'))
```

#### Audience Setter

我们可以通过以下代码指定Audience的对象为`all`

```php
$push->addAllAudience()
```

当然，为了保持API风格的统一，我们也提供一下方法将Audience指定的`all`

```php
$push->setAudience('all')
```

以下示例如何指定Audience的Tags

```php
$push->addTags('tag1');
```

如果需要同时指定多个Tags, 可以用一下方法调用

```php
$push->addTags(array('tag1', 'tag2'));
```

其他诸如 `addAlias()`, `addRegistrationId()`, `addTagAnd()`的使用方法与`addTags()`类似，在此不做赘述。

PS:可以多次调用addXXX操作，最终将在多次结果中取并集。

#### Notification Setter

如果你只是想简单地给所有平台推送相同的消息的话，调用以下方法：

```php
$push->setNotificationAlert($alert)
```

我们也提供单独添加各个移动平台的Notification的方法。

**添加iOS Notification:**

```php
$push->addIosNotification($alert=null, $sound=null, $badge=null, $content_available=null, $category=null, $extras=null)
```

参数说明:

* alert:`String|Array` 通知内容，这里指定了，将会覆盖上级统一指定的`setNotificationAlert()`信息；内容为空则不展示到通知栏。支持 emoji 表情。
    * iOS8.2及以上alert支持JSON格式，可以指定alert为一个Array，如`$alert=array("key1"=>"value1", "key2"=>"value2")`
* sound:`String` 通知提示声音，如果无此字段，则此消息无声音提示；有此字段，如果找到了指定的声音就播放该声音，否则播放默认声音,如果此字段为空字符串，iOS 7 为默认声音，iOS 8 为无声音。
    * 如果为null或者不显式指定，则填充为默认值`''`空字符串
    * 如果不想指定Sound，可以显式的指定为`JPush::DISABLE_SOUND`
* badge:`Int` 应用角标，如果不填，表示不改变角标数字；否则把角标数字改为指定的数字；为 0 表示清除。支持`+1`,`-1`这样的字符串，表示在原有的badge基础上进行增减。
    * 示例：`0`, `1`, `+1`, `-1`
    * 如果为null或者不显式指定，则填充为默认值`+1`
    * 如果想不指定Badge，可以显式的指定为`JPush::DISABLE_BADGE`
* content_abaliable:`Bool` 推送唤醒，为真是表示是`Background Remote Notification`, 不指定则表示是`Remote Notification`
* category: `String` iOS8才支持。设置APNs payload中的"category"字段值
* extras: `Array` 扩展字段，这里自定义 Key/value 信息，以供业务使用
    * 示例：`$extras=array("key1"=>"value1", "key2"=>"value2")`

**添加Android Notification**

```php
$push->addAndroidNotification($alert=null, $title=null, $builderId=null, $extras=null)
```

参数说明:

* alert:`String` 通知内容，这里指定了，将会覆盖上级统一指定的`setNotificationAlert()`信息；内容为空则不展示到通知栏。
* title:`String` 通知标题，如果指定了，则通知里原来展示 App名称的地方，将展示成这个字段。
* builderId:`Int` 通知栏样式ID
* extras:`Array` 扩展字段，这里自定义 Key/value 信息，以供业务使用
    * 示例：`$extras=array("key1"=>"value1", "key2"=>"value2")`

**添加WinPhone Notification**

```php
$push->addWinPhoneNotification($alert=null, $title=null, $_open_page=null, $extras=null)
```

参数说明:

* alert:`String` 通知内容，这里指定了，将会覆盖上级统一指定的`setNotificationAlert()`信息；内容为空则不展示到通知栏。
* title:`String` 通知标题，会填充到 toast 类型 text1 字段上。
* \_open\_page:`String` 点击打开的页面名称
* extras:`Array` 扩展字段，这里自定义 Key/value 信息，以供业务使用
    * 示例：`$extras=array("key1"=>"value1", "key2"=>"value2")`

#### Message Setter

我们可以通过以下方法设置自定义消息Message

```php
$push->setMessage($msg_content, $title=null, $content_type=null, $extras=null)
```

参数说明:

* msg_content:`String` 消息内容本身
* title:`String` 消息标题
* content_type:`String` 消息类型
* extras:`Array` 扩展字段，这里自定义 Key/value 信息，以供业务使用
    * 示例：`$extras=array("key1"=>"value1", "key2"=>"value2")`

#### Sms Message Setter

我们可以通过以下方法设置短信推送消息

```php
$push->setSmsMessage($content, $delay_time)
```

参数说明:

* content:`String` 短信文本，不超过480字符
* delay_time:`Int` 只对Android平台有效，表示指定时间内没收到Push即发送短信

#### Options Setter

我们可以通过以下方法设置Options

```php
$push->setOptions($sendno=null, $time_to_live=null, $override_msg_id=null, $apns_production=null, $big_push_duration=null)
```

参数说明:

* sendno:`Int` 推送序号, 纯粹用来作为 API 调用标识，API 返回时被原样返回，以方便 API 调用方匹配请求与返回。
    * 如未指定或者指定为`null`，则随机生产一个sendno序号
* time\_to\_live:`Int` 离线消息保留时长(秒)，推送当前用户不在线时，为该用户保留多长时间的离线消息，以便其上线时再次推送。
    * 默认 86400 （1 天），最长 10 天。
    * 设置为 0 表示不保留离线消息，只有推送当前在线的用户可以收到。
* override\_msg\_id:`Int` 要覆盖的消息ID，如果当前的推送要覆盖之前的一条推送，这里填写前一条推送的 msg_id 就会产生覆盖效果，
    * 该 msg_id 离线收到的消息是覆盖后的内容；
    * 即使该 msg\_id Android 端用户已经收到，如果通知栏还未清除，则新的消息内容会覆盖之前这条通知；覆盖功能起作用的时限是：1 天。如果在覆盖指定时限内该 msg\_id 不存在，则返回 1003 错误，提示不是一次有效的消息覆盖操作，当前的消息不会被推送。
* apns\_production:`Bool` APNs是否生产环境，True 表示推送生产环境，False 表示要推送开发环境；如果不指定则为推送生产环境。JPush 官方 API LIbrary (SDK) 默认设置为推送 “开发环境”。
    * 如未指定或者指定为`null`, 则默认指定为`false`
* big\_push\_duration:`Int` 定速推送时长(分钟), 又名缓慢推送，把原本尽可能快的推送速度，降低下来，给定的n分钟内，均匀地向这次推送的目标用户推送。
    * 最大值为1400.未设置则不是定速推送。

#### Common Method

**获得当前构建对象**

```php
$push->build();
```

**将当前构建对象打印在控制台**

```php
$push->printJSON()
```

**发送推送**
该方法内部将自动调用构建方法获得当前构建对象，并转化为JSON向JPush服务器发送请求

```php
$push->send()
```

PS: 构建PushPayload的API每一次都会返回自身的引用，所以我们可用使用链式调用的方法提高代码的简洁性，如:

```php
$result = $client->push()
    ->setPlatform(array('ios', 'android'))
    ->addAlias('alias1')
    ->addTag(array('tag1', 'tag2'))
    ->setNotificationAlert('Hi, JPush')
    ->addAndroidNotification('Hi, android notification', 'notification title', 1, array("key1"=>"value1", "key2"=>"value2"))
    ->addIosNotification("Hi, iOS notification", 'iOS sound', JPush::DISABLE_BADGE, true, 'iOS category', array("key1"=>"value1", "key2"=>"value2"))
    ->setMessage("msg content", 'msg title', 'type', array("key1"=>"value1", "key2"=>"value2"))
    ->setOptions(100000, 3600, null, false)
    ->send();
```

### Report API

在初始化JPush后，调用以下代码将返回report对象，它提供丰富的API来帮助你获取Report数据。

```php
 $report = $client->report()
 ```


#### 获取送达统计

调用一下代码可以获取送达统计

```php
$result = $report->getReceived('1150720279');
```

如果你想一次性查询多个MsgId的送达统计，可以使用以下方法调用

```php
$result = $report->getReceived('1150720279,1492401191,1150722083');
```

或者

```php
$result = $report->getReceived(array('1150720279', '1492401191', '1150722083'));
```


#### 获取消息统计

调用一下代码可以获取消息统计

```php
$report->getMessages('541778586,1235578218')
```

消息统计与送达统计一样，接受一个数组的参数，在这里不做赘述

#### 获取用户统计

调用一下代码可以获得用户统计

```php
$report->getUsers($time_unit, $start, $duration)
```

参数说明:

* time_unit:`String` 时间单位, 可取值HOUR, DAY, MONTH
* start:`String` 起始时间
    * 如果单位是小时，则起始时间是小时（包含天），格式例：2014-06-11 09
    * 如果单位是天，则起始时间是日期（天），格式例：2014-06-11
    * 如果单位是月，则起始时间是日期（月），格式例：2014-06
* duration:`String` 持续时长
    * 如果单位是天，则是持续的天数。以此类推
    * 只支持查询60天以内的用户信息，对于time_unit为HOUR的，只支持输出当天的统计结果。



### Device API

在初始化JPush后，调用以下代码将返回device对象，它提供丰富的API来帮助操作Device API

```php
$device = $client->device();
```

#### 操作Device(registration_id)

**查询指定设备的别名与标签**

```php
$device->getDevices($registration_id);
```


**更新指定设备的别名与标签**

```php
$device-> updateDevice($registrationId, $alias = null, $addTags = null, $removeTags = null)
```

参数说明:

* $alais:`String` 别名
* $addTags:`Array` 增加的Tags
* $removeTags:`Array` 移除的Tags

**获取在线用户的登录状态**

```php
$device->getDevicesStatus($registrationId)
```

参数说明:

* registrationId可以指定为一个registrationId的数组，亦可以指定为字符串，多个registrationId以逗号分隔

#### 操作Tag

**获取Tag列表**

```php
$device->getTags()
```

**判断指定设备是否在指定Tag之下**

```php
$device->isDeviceInTag($registrationId, $tag)
```

**更新Tag**

```php
$device->updateTag($tag, $addDevices = null, $removeDevices = null)
```

参数说明:

* tag:`String` 指定的标签
* addDevices:`Array` 增加到指定Tag中的registration_id
* removeDevices:`Array` 从指定Tag中移除的registration_id

**删除Tag**

```php
$device->deleteTag($tag);
```

#### 操作Alias

**获取指定Alias下的设备**

```php
$device->getAliasDevices($alias, $platform=null)
```

参数说明:

* alias: `String` 指定的别名
* platform: `String|Array` 指定的平台，不填表示所有的平台
    * String参数示例: `$platform='ios,android'`
    * Array参数示例: `$platform=array('ios', 'android')`

**删除别名**

```php
$device->deleteAlias($alias)
```

### Schedule API

在初始化JPush后，调用以下代码将返回schedule对象，它提供丰富的API来帮助操作Schedule API

```php
$schedule = $client->schedule();
```

#### 创建定时任务

定时任务分为Single与Periodical两种，可以通过调用以下方法创建定时任务

```php
$schedule->createSingleSchedule($name, $push_payload, $trigger)
$schedule->createPeriodicalSchedule($name, $push_payload, $trigger)
```

参数说明:

* name: `String` 定时任务的名称
* push_payload: `PushPayload` Push的构建对象，通过Push模块的`build()`方法获得
* trigger: `Array` 触发器对象

具体调用示例参考[Schedule Example](https://github.com/jpush/jpush-api-php-client/blob/master/examples/schedule_example.php)

#### 更新定时任务

```php
$schedule->updateSingleSchedule($schedule_id, $name=null, $enabled=null, $push_payload=null, $trigger=null)
$schedule->updatePeriodicalSchedule($schedule_id, $name=null, $enabled=null, $push_payload=null, $trigger=null)
```

#### 获取定时任务列表

```php
$schedule->getSchedules($page=1);
```

#### 获取指定定时任务

```php
$schedule->getSchedule($schedule_id);
```

#### 删除指定定时任务

```php
$schedule->deleteSchedule($schedule_id);
```