本文檔介紹了推送服務器的Web接口的使用方法。

首先區分一下user channel和tag channel的概念：

user channel是以客戶端唯一的uid作為channel的名稱，客戶端連接上來自動sub(sub表示加入channel) tag channel 是客戶端主動通過sub命令加入的通道，比如客戶端sub “location:beijing”，那么它就加入了”location:beijing”的通道，對”location:beijing”下發消息, 該客戶端就會收到消息, 可以把tag channel想象成標簽推送

開發者需要對Web接口以POST方法傳遞數據，Web接口將以JSON格式返回接口調用結果。

假如在服務器配置文件中配置了

[web]
bind localhost:8080

那么可使用如下的Linux命令調用接口或編程調用：

curl –X POST –d POST_DATA http://localhost:8080/METHOD_NAME

其中

POST_DATA 為POST的數據 METHOD_NAME 為需要調用的方法名

METHOD_NAME: pub POST_DATA:

            "expired": "1403521931",
             "appid": "XXX",
             "channel": "xxx@qq.com",
             "channel": "xxx@gmail.com",
             "data": "hello world"
             

• expired: 為unix時間戳，最長為30天(在上面配置文件中設置)，超出這個時間將不再下發此消息的離線消息，且無法繼續通過web service查詢到此消息的相關信息。值得注意的是, 如果提供了大于0的expired，那么默認是會保存離線消息的，沒有收到消息的客戶端在下次登錄時會收到此離線消息，但是如果設置expired為0，表示此消息是即時消息，不需要保存離線消息，所以即時客戶端沒有收到消息，那么也是不會有離線消息產生的。
• channel: 表示要下發的通道名稱，可以提供多個channel。在這個方法里，channel的值對應SDK端提供的UID。
• data: 要下發的數據，這個可以使任何格式的數據，甚至二進制數據也是支持的。一般情況下，可以使用JSON格式的文本賦值給data。下面列出了關于data格式的說明。
• appid: 要推送的appid，appid只能提供一個。

如使用SDK中預置的通知欄消息展現模板，則對于POST數據中 data 字段的格式要求，參照如下JSON串：

{ 
     "type":"notification", //通知欄類型
    "style":"1",                    //通知欄樣式編號
    "config":{ 
        "icondata":"XXXXXXX",   //icon文件的BASE64編碼
        "vibrate":"1",                     //是否震動：1 震動,0 不震動
        "sound":"1",                       //是否發出提示音：1有聲音,0沒聲音
        "title":"XXXXXX",                //通知欄標題
        "ticker":"XXXXXXX",           //狀態欄滾動信息
        "body":"XXXXXXX",           //消息內容
        "clickconfig":{                   //定義了用戶點擊后的行為，請見如下的例子
            "operation":"launchActivity", 
            "package":"com.wbkit.icclient", 
            "targetActivity":"com.wbkit.icclient.MainActivity" 
        } 
    } 
}

clickconfig的例子一：打開應用（Activity）

{
 “operation”：“launchActivity”,          //操作類型：打開Activity
 “package” : “com.example.demo”  //APK包名
 “targetActivity”: “com.example.demo.MainActivity”//Activity
}

clickconfig的例子二：下載APK并安裝

{
 “operation”：“download”,       //操作類型:下載APK）
 “appname”: “捕魚達人”             //APP 名字
 “dlurl”: “http://xxxxxx.apk”        //APK的url
  //PS:下載后自動彈出安裝
}

clickconfig的例子三：打開頁面

{
 “operation”：“loadWebpage”,      //操作類型:打開頁面
  //PS: url和page二選一，如果都填了優先url
 “url”: “http://www.baidu.com”,     //url
 “page”: “.....”            //頁面內容
}

需要使用如下的格式確定data內容

{
 “type”：“transparent”, //透傳類型
 “config”：“{
         	“content”:“XXXXXXX”,//透傳消息內容
	         } ”
}

返回格式

        {
            "status":      "200",
            "pushedCount": 100,
            "offCount":    1,
            "elapsed":     0.52,
            "mid":         "489c4464de66000"
         }
         

• status: 200表示成功, 400 表示請求封包格式錯誤.
• pushedCount: 已經下發的消息數量，這個數值并不代表接收到消息的用戶數量，僅僅表示推送服務器已經對100個連接下發了數據，只有當終端SDK提交了回執，服務器才會認為該用戶收到了消息。
• offCount: 表示提交的user channel中，當前不在線的數量。
• elapsed: 這次推送在服務器端下發所消耗的時間，以毫秒為單位，是一個float型的數字。
• mid: 這次推送消息的唯一任務ID，以后可以通過此mid查詢到相應消息的信息，如客戶接收到的數量，客戶閱讀的數量，消息內容等。

tagpub是專門針對tag channel下發的命令，也支持離線消息，但是離線消息會消耗多一些資源。如果只需要實時下發，請把expired設置為0。 METHOD_NAME: tagpub POST_DATA:

            "channel": "localtion:beijing",
             "channel": "location:guangzhou",
             "data": "hello world",
             "appid": "XXX",
             "expired": "1403521931"

• channel: tag channel的名稱, 可以提供多個
• data: 需要下發的數據
• appid: appid與tag channel相關聯, 只能提供app下的tag channel
• expired: 同pub方法

返回格式:

         {
            "status":      "200",
            "pushedCount": 100,
            "elapsed":     0.52,
            "mid":         "489c4465de66000"
         }
         

各項意義同pub方法

此方法將向appid下的所有在線用戶或者全部用戶下發，區別只下發在線用戶或全部用戶是通過expired來區分的，如果expired為0，那么就只對在線的用戶下發，不保存離線消息。

METHOD_NAME: allpub POST_DATA:

             "appid": "XXX",
             "data": "hello world",
             "expired": "1403521931"<code>
             

返回格式:

        {
            "status":      "200",
            "pushedCount": 100,
            "elapsed":     0.52,
            "mid":         "489c4466de66000" 
         }
         

status說明：

• 200 成功
• 400 請求封包有錯誤
• 500 服務器內部錯誤（通常跟redis有關）

提供了一個接口可以把某一些用戶的uid加入到某一tag channel下，此操作是冪等的。 METHOD_NAME：sub-tag POST_DATA：

             "appid": "XXX",
             "tag": "localtion:beijing",
             "uid": "xxx@qq.com",
             "uid": "xxxx@gmail.com" 

參數說明：

• appid: 與標簽相關聯的appid，只能有一個此參數
• tag: 要加入的標簽組的TAG，也只能有一個此參數
• uid: 要加入標簽的用戶uid，可以是多個

返回結果：

        {
            "status": "200"
         }
         

status說明

• 200 成功
• 400 請求封包有錯誤
• 500 服務器內部錯誤（通常跟redis有關）

METHOD_NAME: unsub-tag POST_DATA：

            "appid": "XXX",
             "tag": "localtion:beijing",
             "uid": "xxx@qq.com",
             "uid": "xxxx@gmail.com", 

參數說明

• appid: 與標簽相關聯的appid，只能有一個此參數
• tag: 要去除的標簽組的TAG名稱，只能有一個此參數
• uid: 要移除標簽的用戶uid，可以提供多個

返回格式：

       {
            "status": "200" 
        }

status說明

• 200 成功
• 400 請求封包有錯誤
• 500 服務器內部錯誤（通常跟redis有關）

METHOD_NAME: message POST_DATA:

        "mid": "489c4466de66000"          

返回格式:

        {
             "status":"200"
             "489c4466de66000": 
               {
                    "content":"hello world!",        
                    "expire":"1404378620",
                    "readCount":"0",
                    "recvdCount":"0",
                    "startTime":"1403407632",
                    "totalCount":"2",
                    "appid": "XXX"
                }
        }
        

 返回說明：

• status: 接口查詢的結果，200為正確執行
• content: 消息的內容
• expire: 消息過期的時間戳
• readCount: 此消息被客戶端點擊(閱讀)的數量
• recvCount: 此消息被客戶端接收到的數量
• startTime: 此消息下發的時間
• totalCount: 總下發量
• 489c4466de66000: 查詢的mid
• appid: appid

METHOD_NAME: userchannel POST_DATA:

            "channel": "xxx@qq.com",
            "channel": "xxxx@gmail.com" 

返回:

     {
         "status": "200",
         "xxx@qq.com": 1, //此uid在線
         "xxxx@gmail.com": 0 //此uid不在線
      }
      

METHOD_NAME: tagchannel POST_DATA:

            "channel": "location:Beijing",
            "channel": "location:Guangzhou"

返回:

     {
         "status": "200",
         "location:Beijing": 456, //當前在"location:Beijing"這個標簽TAG下有456人，包括在線及不在線用戶
         "location:Guangzhou": 23 //當前在"location:Beijing"這個標簽TAG下有23人，包括在線及不在線用戶
      }

METHOD_NAME: app-size POST_DATA:

            "online": 1,
            "appid": "xxx",
            "appid": "yyy" 

• online: 為1表示查詢在線的user數量，如果為0表示查詢總數量，包括離線
• appid: 可以提供多個appid進行查詢

返回格式:

    {
         "status": "200",
         "xxx": 1234, //appid為xxx的app目前在線（或總數）用戶數為1234人
         "yyy": 567 //appid為yyy的app目前在線（或總數）用戶數為567人
      }

其中返回的數字表示數量，具體含義依賴于調用時online方法的值。