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

JPush PHP Server SDK Doc

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

• Push API
• Report API
• Device API
• Schedule API

Init API : 初始化

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

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

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

$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。

$push = $client->push();

通过JPush Push API 我们知道，一个PushPayload是由以下几个部分构成的：

• Platform
• Audience
• Notification
• Message
• SmsContent
• Options

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

Platform Setter

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

$push->setPlatform('all')

如果想指定为特定平台:

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

亦或者:

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

Audience Setter

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

$push->addAllAudience()

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

$push->setAudience('all')

以下示例如何指定Audience的Tags

$push->addTags('tag1');

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

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

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

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

Notification Setter

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

$push->setNotificationAlert($alert)

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

添加iOS Notification:

$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

$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

$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

$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

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

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

参数说明:

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

Options Setter

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

$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

获得当前构建对象

$push->build();

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

$push->printJSON()

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

$push->send()

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

$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数据。

 $report = $client->report()

获取送达统计

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

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

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

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

或者

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

获取消息统计

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

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

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

获取用户统计

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

$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

$device = $client->device();

操作Device(registration_id)

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

$device->getDevices($registration_id);

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

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

参数说明:

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

获取在线用户的登录状态

$device->getDevicesStatus($registrationId)

参数说明:

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

操作Tag

获取Tag列表

$device->getTags()

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

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

更新Tag

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

参数说明:

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

删除Tag

$device->deleteTag($tag);

操作Alias

获取指定Alias下的设备

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

参数说明:

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

删除别名

$device->deleteAlias($alias)

Schedule API

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

$schedule = $client->schedule();

创建定时任务

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

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

参数说明:

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

具体调用示例参考Schedule Example

更新定时任务

$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)

获取定时任务列表

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

获取指定定时任务

$schedule->getSchedule($schedule_id);

删除指定定时任务

$schedule->deleteSchedule($schedule_id);