在調用推送之前，我們必須先初始化 JPushClient，調用以下代碼可以進行快速初始化： ```php $client = new \JPush\Client($app_key, $master_secret); ``` 在初始化 JPushClient 的時候，可以指定日志路徑： ```php $client = new \JPush\Client($app_key, $master_secret, $log_path); ``` 默認日志路徑為 `./jpush.log`,即保存在當前運行目錄，如果想關閉日志，可以指定為 null。 ## Push API 在初始化 JPushClient 后，調用以下代碼將返回一個推送 Payload 構建器，它提供豐富的API來幫助你構建 PushPayload。 ```php $push = $client->push(); ``` 通過 JPush Push API 我們知道，一個 PushPayload 是由以下幾個部分構成的： Cid 平臺 觀眾 通知 信息 短信內容 選項 ## Cid ```php $push->setCid($cid); ``` ## Platform 平臺 ```php $push->setPlatform('all'); // OR $push->setPlatform('ios', 'android'); // OR $push->setPlatform(['ios', 'android']); ``` ## Audience 觀眾 ```php $push->addAllAudience(); $push->addTag('tag1'); // OR $push->addTag(['tag1', 'tag2']); ``` 其他諸如 `addAlias()`, `addRegistrationId()`, `addTagAnd()`, `addTagNot()`, `addSegmentId()`, `addAbtest()` 的使用方法與 `addTag()` 類似，在此不做贅述。 ## Notification 通知 // 簡單地給所有平臺推送相同的 alert 消息 ```php $push->setNotificationAlert('alert'); ``` ## iOS Notification iOS通知 ```php // iosNotification($alert = '', array $notification = array()) // 數組 $notification 的鍵支持 'sound', 'badge', 'content-available', 'mutable-content', category', 'extras', 'thread-id' 中的一個或多個 // 調用示例 $push->iosNotification(); // OR $push->iosNotification('hello'); // OR $push->iosNotification('hello', [ 'sound' => 'sound', 'badge' => '+1', 'extras' => [ 'key' => 'value' ] ]); ``` 參數說明: |參數| 說明| |-|-| |alert| 表示通知內容，會覆蓋上級統一指定的 alert 信息；默認內容可以為空字符串，表示不展示到通知欄, 支持字符串和數組兩種形式| |sound |表示通知提示聲音，默認填充為空字符串| |badge |表示應用角標，把角標數字改為指定的數字；為 0 表示清除，支持 '+1','-1' 這樣的字符串，表示在原有的 badge 基礎上進行增減，默認填充為 '+1'| |content-available| 表示推送喚醒，僅接受 true 表示為 Background Remote Notification，若不填默認表示普通的 Remote Notification| |mutable-content| 表示通知擴展, 僅接受 true 表示支持 iOS10 的 UNNotificationServiceExtension, 若不填默認表示普通的 Remote Notification| |category| IOS8才支持。設置 APNs payload 中的 'category' 字段值| |thread-id| 表示通知分組，ios 的遠程通知通過該屬性來對通知進行分組，同一個 thread-id 的通知歸為一組| |extras|表示擴展字段，接受一個數組，自定義 Key/value 信息以供業務使用| ## Android Notification Android 通知 ```php // androidNotification($alert = '', array $notification = array()) // 調用示例同 IOS，數組 $notification 的鍵支持 'title', 'builder_id', 'priority', 'category', 'style', 'alert_type', 'big_text', 'inbox', 'big_pic_path', 'large_icon', 'intent', 'extras' 中的一個或多個 ``` 參數說明: |參數 |說明| |-|-| |alert |表示通知內容，會覆蓋上級統一指定的 alert 信息；默認內容可以為空字符串，表示不展示到通知欄| |title |表示通知標題，會替換通知里原來展示 App 名稱的地方| |builder_id |表示通知欄樣式 ID| |priority |表示通知欄展示優先級，默認為 0，范圍為 -2～2 ，其他值將會被忽略而采用默認值| |category |表示通知欄條目過濾或排序，完全依賴 rom 廠商對 category 的處理策略| |style |表示通知欄樣式類型，默認為 0，還有1，2，3可選，用來指定選擇哪種通知欄樣式，其他值無效。有三種可選分別為 bigText=1，Inbox=2，bigPicture=3| |alert_type| 表示通知提醒方式， 可選范圍為 -1～7 ，對應 Notification.DEFAULT_ALL = -1 或者 Notification.DEFAULT_SOUND = 1， |Notification.DEFAULT_VIBRATE = 2， Notification.DEFAULT_LIGHTS = 4 的任意 “or” 組合。默認按照 -1 處理。| |big_text |表示大文本通知欄樣式，當 style = 1 時可用，內容會被通知欄以大文本的形式展示出來，支持 api 16 以上的 rom| |inbox |表示文本條目通知欄樣式，接受一個數組，當 style = 2 時可用，數組的每個 key 對應的 value 會被當作文本條目逐條展示，支持 api 16 以上的 rom| |big_pic_path| 表示大圖片通知欄樣式，當 style = 3 時可用，可以是網絡圖片 url，或本地圖片的 path，目前支持 .jpg 和 .png 后綴的圖片。圖片內容會被通知欄以大圖片的形式展示出來。如果是 http／https 的 url，會自動下載；如果要指定開發者準備的本地圖片就填 sdcard 的相對路徑，支持 api 16 以上的 rom| |large_icon| 表示通知欄大圖標，圖標路徑可以是以 http 或 https 開頭的網絡圖片，如："http:jiguang.cn/logo.png"，圖標大小不超過 30k； 也可以是位于 drawable 資源文件夾的圖標路徑，如："R.drawable.lg_icon"；| |intent |表示擴展字段，接受一個數組，自定義 Key/value 信息以供業務使用| |extras |表示擴展字段，接受一個數組，自定義 Key/value 信息以供業務使用| ## WinPhone Notification WinPhone通知 ```php $push->addWinPhoneNotification($alert=null, $title=null, $_open_page=null, $extras=null) ``` 參數說明: |參數 |說明| |-|-| |alert| 表示通知內容，會覆蓋上級統一指定的 alert 信息；內容為空則不展示到通知欄| |title |通知標題，會填充到 toast 類型 text1 字段上| |_open_page| 點擊打開的頁面名稱| ## Message 信息 ```php // message($msg_content, array $msg = array()) // 數組 $msg 的鍵支持 'title', 'content_type', 'extras' 中的一個或多個 // 調用示例 $push->message('Hello JPush'); // OR $push->message('Hello JPush', [ 'title' => 'Hello', 'content_type' => 'text', 'extras' => [ 'key' => 'value' ] ]); ``` 參數說明: |參數 |說明| |-|-| |msg_content |消息內容本身| |title| 消息標題| |content_type |消息內容類型| |extras| 表示擴展字段，接受一個數組，自定義 Key/value 信息以供業務使用| ## Sms Message 短信內容 ```php $push->setSms($delay_time, $temp_id, array $temp_para = []) ``` 參數說明: |參數|內容| |-|-| |delay_time:|表示短信發送的延遲時間，單位為秒，不能超過 24 小時(即大于等于 0 小于等于 86400)。僅對 android 平臺有效。| |temp_id|短信補充的內容模板 ID。沒有填寫該字段即表示不使用短信補充功能。| |temp_para|短信模板中的參數| **已棄用** ```php $push->setSmsMessage($content, $delay_time) ``` 參數說明: |參數|內容| |-|-| |content| 短信文本，不超過 480 字符| |delay_time|表示短信發送的延遲時間，單位為秒，不能超過 24 小時(即大于等于 0 小于等于 86400)。僅對 android 平臺有效。默認為 0，表示立即發送短信| ## Options 選項 ```php // options(array $opts = array()) // 數組 $opts 的鍵支持 'sendno', 'time_to_live', 'override_msg_id', 'apns_production', 'big_push_duration', 'apns_collapse_id' 中的一個或多個 ``` 參數說明: |可選項| 說明| |-|-| |sendno |表示推送序號，純粹用來作為 API 調用標識，API 返回時被原樣返回，以方便 API 調用方匹配請求與返回| |time_to_live |表示離線消息保留時長(秒)，推送當前用戶不在線時，為該用戶保留多長時間的離線消息，以便其上線時再次推送。默認 86400 （1 天），最長 10 天。設置為 0 表示不保留離線消息，只有推送當前在線的用戶可以收到| |override_msg_id| 表示要覆蓋的消息ID，如果當前的推送要覆蓋之前的一條推送，這里填寫前一條推送的 msg_id 就會產生覆蓋效果| |apns_production| 表示 APNs 是否生產環境，True 表示推送生產環境，False 表示要推送開發環境；如果不指定則默認為推送開發環境| |apns_collapse_id| APNs 新通知如果匹配到當前通知中心有相同 apns-collapse-id 字段的通知，則會用新通知內容來更新它，并使其置于通知中心首位；collapse id 長度不可超過 64 bytes| |big_push_duration |表示定速推送時長(分鐘)，又名緩慢推送，把原本盡可能快的推送速度，降低下來，給定的 n 分鐘內，均勻地向這次推送的目標用戶推送。最大值為1400.未設置則不是定速推送| ## Common Method常用方法 ```php // 發送推送 // 該方法內部將自動調用構建方法獲得當前構建對象，并轉化為 JSON 向 JPush 服務器發送請求 $push->send(); ``` 構建 PushPayload 的 API 每一次都會返回自身的引用，所以我們可用使用鏈式調用的方法提高代碼的簡潔性，如: ```php $response = $push() ->setCid('xxxxxx') ->setPlatform(['ios', 'android']) ->addTag(['tag1', 'tag2']) ->setNotificationAlert('Hello, JPush') ->iosNotification('hello', [ 'sound' => 'sound', 'badge' => '+1', 'extras' => [ 'key' => 'value' ] ]) ->androidNotification('hello') ->message('Hello JPush', [ 'title' => 'Hello', 'content_type' => 'text', 'extras' => [ 'key' => 'value' ] ]) ->send(); // OR 也可以提前準備好所有的參數，然后鏈式調用，這樣代碼可讀性更好一點 $cid = 'xxxxxx'; $platform = array('ios', 'android'); $alert = 'Hello JPush'; $tag = array('tag1', 'tag2'); $regId = array('rid1', 'rid2'); $ios_notification = array( 'sound' => 'hello jpush', 'badge' => 2, 'content-available' => true, 'category' => 'jiguang', 'extras' => array( 'key' => 'value', 'jiguang' ), ); $android_notification = array( 'title' => 'hello jpush', 'builder_id' => 2, 'extras' => array( 'key' => 'value', 'jiguang' ), ); $content = 'Hello World'; $message = array( 'title' => 'hello jpush', 'content_type' => 'text', 'extras' => array( 'key' => 'value', 'jiguang' ), ); $options = array( 'sendno' => 100, 'time_to_live' => 100, 'override_msg_id' => 100, 'big_push_duration' => 100 ); $response = $push->setCid($cid) ->setPlatform($platform) ->addTag($tag) ->addRegistrationId($regId) ->iosNotification($alert, $ios_notification) ->androidNotification($alert, $android_notification) ->message($content, $message) ->options($options) ->send(); ``` ## 獲取 Cid ```php $push->getCid($count = 1, $type = 'push'); ``` ## Report API ```php $report = $client->report(); ``` 獲取送達統計 ```php $report->getReceived('msg_id'); // OR $report->getReceived(['msg_id1', 'msg_id2']); ``` 送達狀態查詢 ```php $msg_id0 = 66666666666; $report->getMessageStatus($msg_id0, 'rid0'); # OR $report->getMessageStatus($msg_id0, ['rid0', 'rid1']); #OR $report->getMessageStatus($msg_id0, ['rid0', 'rid1'], '2017-12-21'); ``` 獲取消息統計 ```php // getMessages(getMessages($msgIds)); // 消息統計與送達統計一樣，接受一個數組的參數，在這里不做贅述 ``` 獲取用戶統計 調用一下代碼可以獲得用戶統計 ```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 ```php $device = $client->device(); ``` 操作 Device(registration_id) ```php // 查詢指定設備的別名與標簽 $device->getDevices($registration_id); ``` ```php // 更新指定設備的別名與標簽 // 更新 Alias $device->updateAlias($registration_id, 'alias'); // 添加 tag, 支持字符串和數組兩種參數 $device->addTags($registration_id, 'tag'); // OR $device->addTags($registration_id, ['tag1', 'tag2']); // 移除 tag，支持字符串和數組兩種參數 $device->removeTags($registration_id, 'tags'); // OR $device->removeTags($registration_id, ['tag1', 'tag2']); // 清空所有 tag $device->clearTags($registration_id); // 更新 mobile $device->updateMoblie($registration_id, '13800138000'); // 取消手機綁定 $device->clearMobile($registration_id); // getDevicesStatus($registrationId) // 獲取在線用戶的登錄狀態（VIP專屬接口）,支持字符串和數組兩種參數 $device->getDevicesStatus('rid'); // OR $device->getDevicesStatus(['rid1', 'rid2']); ``` ## 操作標簽 ```php // 獲取標簽列表 $device->getTags() // 判斷指定設備是否在指定標簽之下 $device->isDeviceInTag($registrationId, $tag); // 更新標簽 // 為標簽添加設備，支持字符串和數組兩種參數 $device->addDevicesToTag($tag, 'rid'); $device->addDevicesToTag($tag, ['rid1', 'rid2']); // 為標簽移除設備，支持字符串和數組兩種參數 $device->removeDevicesFromTag($tag, 'rid'); $device->removeDevicesFromTag($tag, ['rid1', 'rid2']); // 刪除標簽 $device->deleteTag('tag'); 操作別名 // 獲取指定別名下的設備 $device->getAliasDevices('alias'); // 刪除別名 $device->deleteAlias('alias'); Schedule API $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 觸發器對象 更新定時任務 ```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); // 獲取指定定時任務 $schedule->getSchedule($schedule_id); // 刪除指定定時任務 $schedule->deleteSchedule($schedule_id); // 獲取定時任務對應的所有 msg_id $schedule->getMsgIds($schedule_id); ``` ## Exception Handle 當 API 請求發生錯誤時，SDK 將拋出異常，Pushpayload 具體錯誤代碼請參考 API 錯誤代碼表。 PHP SDK 主要拋出兩個異常 \JPush\Exceptions\APIConnectionException 和 \JPush\Exceptions\APIRequestException 分別對應請求連接產生的異常和請求響應的異常。 這兩種異常都需要捕獲，為簡單起見，也可以捕獲他們的父類異常 JPush\Exceptions\JPushException（見 README）。另外 APIRequestException 異常還提供其他方法供開發者調用。 ```php try { $pusher->send(); } catch (\JPush\Exceptions\APIConnectionException $e) { // try something here print $e; } catch (\JPush\Exceptions\APIRequestException $e) { // try something here print $e; } ```