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

首先區(qū)分一下user channel和tag channel的概念：

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

開發(fā)者需要對(duì)Web接口以POST方法傳遞數(shù)據(jù)，Web接口將以JSON格式返回接口調(diào)用結(jié)果。

假如在服務(wù)器配置文件中配置了

[web]
bind localhost:8080

那么可使用如下的Linux命令調(diào)用接口或編程調(diào)用：

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

其中

POST_DATA 為POST的數(shù)據(jù) METHOD_NAME 為需要調(diào)用的方法名

METHOD_NAME: pub POST_DATA:

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

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

如使用SDK中預(yù)置的通知欄消息展現(xiàn)模板，則對(duì)于POST數(shù)據(jù)中 data 字段的格式要求，參照如下JSON串：

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

clickconfig的例子一：打開應(yīng)用（Activity）

{
 “operation”：“l(fā)aunchActivity”,          //操作類型：打開Activity
 “package” : “com.example.demo”  //APK包名
 “targetActivity”: “com.example.demo.MainActivity”//Activity
}

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

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

clickconfig的例子三：打開頁(yè)面

{
 “operation”：“l(fā)oadWebpage”,      //操作類型:打開頁(yè)面
  //PS: url和page二選一，如果都填了優(yōu)先url
 “url”: “http://www.baidu.com”,     //url
 “page”: “.....”            //頁(yè)面內(nèi)容
}

需要使用如下的格式確定data內(nèi)容

{
 “type”：“transparent”, //透?jìng)黝愋? “config”：“{
         	“content”:“XXXXXXX”,//透?jìng)飨?nèi)容
	         } ”
}

返回格式

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

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

tagpub是專門針對(duì)tag channel下發(fā)的命令，也支持離線消息，但是離線消息會(huì)消耗多一些資源。如果只需要實(shí)時(shí)下發(fā)，請(qǐng)把expired設(shè)置為0。 METHOD_NAME: tagpub POST_DATA:

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

• channel: tag channel的名稱, 可以提供多個(gè)
• data: 需要下發(fā)的數(shù)據(jù)
• appid: appid與tag channel相關(guān)聯(lián), 只能提供app下的tag channel
• expired: 同pub方法

返回格式:

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

各項(xiàng)意義同pub方法

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

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 請(qǐng)求封包有錯(cuò)誤
• 500 服務(wù)器內(nèi)部錯(cuò)誤（通常跟redis有關(guān)）

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

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

參數(shù)說明：

• appid: 與標(biāo)簽相關(guān)聯(lián)的appid，只能有一個(gè)此參數(shù)
• tag: 要加入的標(biāo)簽組的TAG，也只能有一個(gè)此參數(shù)
• uid: 要加入標(biāo)簽的用戶uid，可以是多個(gè)

返回結(jié)果：

        {
            "status": "200"
         }
         

status說明

• 200 成功
• 400 請(qǐng)求封包有錯(cuò)誤
• 500 服務(wù)器內(nèi)部錯(cuò)誤（通常跟redis有關(guān)）

METHOD_NAME: unsub-tag POST_DATA：

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

參數(shù)說明

• appid: 與標(biāo)簽相關(guān)聯(lián)的appid，只能有一個(gè)此參數(shù)
• tag: 要去除的標(biāo)簽組的TAG名稱，只能有一個(gè)此參數(shù)
• uid: 要移除標(biāo)簽的用戶uid，可以提供多個(gè)

返回格式：

       {
            "status": "200" 
        }

status說明

• 200 成功
• 400 請(qǐng)求封包有錯(cuò)誤
• 500 服務(wù)器內(nèi)部錯(cuò)誤（通常跟redis有關(guān)）

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: 接口查詢的結(jié)果，200為正確執(zhí)行
• content: 消息的內(nèi)容
• expire: 消息過期的時(shí)間戳
• readCount: 此消息被客戶端點(diǎn)擊(閱讀)的數(shù)量
• recvCount: 此消息被客戶端接收到的數(shù)量
• startTime: 此消息下發(fā)的時(shí)間
• totalCount: 總下發(fā)量
• 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, //當(dāng)前在"location:Beijing"這個(gè)標(biāo)簽TAG下有456人，包括在線及不在線用戶
         "location:Guangzhou": 23 //當(dāng)前在"location:Beijing"這個(gè)標(biāo)簽TAG下有23人，包括在線及不在線用戶
      }

METHOD_NAME: app-size POST_DATA:

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

• online: 為1表示查詢?cè)诰€的user數(shù)量，如果為0表示查詢總數(shù)量，包括離線
• appid: 可以提供多個(gè)appid進(jìn)行查詢

返回格式:

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

其中返回的數(shù)字表示數(shù)量，具體含義依賴于調(diào)用時(shí)online方法的值。