Logo Site EngageLab Mark Colored Transparent文件
AppPush
文檔首頁
用戶指南開發者指南資料安全最佳實踐更新日誌
搜尋
登錄
開發者指南/REST API/裝置註冊 API
開發者指南REST API裝置註冊 API...

裝置註冊 API

最新更新：1 天前

裝置註冊 API 提供 AppPush 裝置 Token 註冊相關的伺服端介面，用於取得 registration_id。

透過 Token 取得 registration_id

此介面用於服務端透過 FCM Token 或 APNs Device Token 註冊 AppPush 用戶，並取得 EngageLab 產生的 registration_id。取得 registration_id 後，可將其用於指定用戶推播，以及標籤、別名等裝置相關 API。

使用限制

  • 單次請求支援註冊 1～500 個 Token。
  • 單次請求只能註冊一種平台的 Token，即一批 FCM Token 或一批 APNs Device Token，不支援 FCM 和 APNs 混合註冊。
  • 相同應用程式、平台和 Token 的重複請求具冪等性，不會重複建立用戶，並會傳回原有的 registration_id。
  • 傳回結果與請求中的 Token 順序一致。

呼叫地址

POST /v4/devices/token/registration_id
              
              POST /v4/devices/token/registration_id
此代碼塊在浮窗中顯示

完整請求地址由應用程式所屬資料中心的 Base URL 與上述路徑組成。資料中心地址和驗證方式請參閱 REST API 概述。

請求標頭

Content-Type: application/json Accept: application/json Authorization: Basic base64_auth_string
              
              Content-Type: application/json
Accept: application/json
Authorization: Basic base64_auth_string
此代碼塊在浮窗中顯示

請求參數

名稱 類型 是否必選 說明
platform string 是 Token 所屬平台。可選值：android、ios。FCM Token 使用 android。
tokens array<string> 是 要註冊的 Token 清單，長度為 1～500。同一請求中的 Token 必須屬於 platform 指定的平台。
apns_production boolean iOS 必選 APNs 環境。true 表示正式環境，false 表示開發環境。Android 請求不可傳入此欄位。

Token 格式規則

  • FCM Token：必須為非空字串，長度不超過 400 個字元；僅允許使用可列印 ASCII 字元（0x21～0x7E），不可包含空格、換行或開頭與結尾的空白字元。
  • APNs Device Token：必須為非空、長度不超過 400 個字元且長度為偶數的十六進位字串，僅允許字元 0-9、a-f、A-F，不可包含空格、尖括號或其他分隔符號。

此介面只驗證 Token 的格式，無法確認 Token 目前是否真實有效。Token 是否有效以 FCM 或 APNs 的實際推播結果為準。

Android（FCM）請求範例

curl -X POST 'https://pushapi-sgp.engagelab.com/v4/devices/token/registration_id' \ -u 'appKey:masterSecret' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -d '{ "platform": "android", "tokens": [ "fcm_token_1", "fcm_token_2" ] }'
              
              curl -X POST 'https://pushapi-sgp.engagelab.com/v4/devices/token/registration_id' \
  -u 'appKey:masterSecret' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "platform": "android",
    "tokens": [
      "fcm_token_1",
      "fcm_token_2"
    ]
  }'
此代碼塊在浮窗中顯示

iOS（APNs）請求範例

curl -X POST 'https://pushapi-sgp.engagelab.com/v4/devices/token/registration_id' \ -u 'appKey:masterSecret' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -d '{ "platform": "ios", "tokens": [ "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" ], "apns_production": true }'
              
              curl -X POST 'https://pushapi-sgp.engagelab.com/v4/devices/token/registration_id' \
  -u 'appKey:masterSecret' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "platform": "ios",
    "tokens": [
      "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    ],
    "apns_production": true
  }'
此代碼塊在浮窗中顯示

傳回參數

名稱 類型 說明
results array<object> 各 Token 的註冊結果，順序與請求中的 tokens 一致。
results[].token string 請求中的 Token。
results[].registration_id string EngageLab 用戶唯一識別碼。目前 Token 註冊成功時傳回。
results[].is_new boolean true 表示本次新建用戶；false 表示 Token 已註冊並傳回原有用戶。
results[].code integer 單一 Token 的處理結果碼。0 表示成功，非 0 表示失敗。
results[].message string 單一 Token 處理失敗時的錯誤說明；成功時不傳回。

單項結果碼：

Code 說明
0 Token 註冊成功。
21003 Token 格式不合法。
27000 Token 查詢、註冊或同步失敗。

成功傳回範例

首次註冊時，is_new 為 true：

{ "results": [ { "token": "fcm_token_1", "registration_id": "13065ffa4e1a6cc91c3", "is_new": true, "code": 0 }, { "token": "fcm_token_2", "registration_id": "13065ffa4e1a6cc91c4", "is_new": true, "code": 0 } ] }
              
              {
  "results": [
    {
      "token": "fcm_token_1",
      "registration_id": "13065ffa4e1a6cc91c3",
      "is_new": true,
      "code": 0
    },
    {
      "token": "fcm_token_2",
      "registration_id": "13065ffa4e1a6cc91c4",
      "is_new": true,
      "code": 0
    }
  ]
}
此代碼塊在浮窗中顯示

使用已註冊的 Token 再次請求時，傳回相同的 registration_id，且 is_new 為 false：

{ "results": [ { "token": "fcm_token_1", "registration_id": "13065ffa4e1a6cc91c3", "is_new": false, "code": 0 } ] }
              
              {
  "results": [
    {
      "token": "fcm_token_1",
      "registration_id": "13065ffa4e1a6cc91c3",
      "is_new": false,
      "code": 0
    }
  ]
}
此代碼塊在浮窗中顯示

單一 Token 處理失敗範例

批次處理中某個 Token 格式不合法或註冊失敗時，該項目會透過 code 和 message 傳回錯誤，其他 Token 仍可正常處理。以下範例中的空 Token 格式驗證失敗：

{ "results": [ { "token": "fcm_token_1", "registration_id": "13065ffa4e1a6cc91c3", "is_new": false, "code": 0 }, { "token": "", "is_new": false, "code": 21003, "message": "invalid fcm token format" } ] }
              
              {
  "results": [
    {
      "token": "fcm_token_1",
      "registration_id": "13065ffa4e1a6cc91c3",
      "is_new": false,
      "code": 0
    },
    {
      "token": "",
      "is_new": false,
      "code": 21003,
      "message": "invalid fcm token format"
    }
  ]
}
此代碼塊在浮窗中顯示

請求失敗範例

請求參數整體不合法時，介面會傳回 HTTP 400。例如 iOS 請求未傳入 apns_production：

{ "error": { "code": 21003, "message": "apns_production is required for ios" } }
              
              {
  "error": {
    "code": 21003,
    "message": "apns_production is required for ios"
  }
}
此代碼塊在浮窗中顯示

常見請求錯誤包括：

  • platform 不是 android 或 ios；
  • tokens 為空或超過 500 個；
  • Android 請求傳入 apns_production；
  • iOS 請求缺少 apns_production。

呼叫傳回

HTTP 狀態碼

參閱文件：HTTP-Status-Code

錯誤碼

下表為請求層級的錯誤碼。批次請求中單一 Token 的處理錯誤會透過 results[].code 和 results[].message 傳回，不影響其他 Token 的處理。

Code 說明 詳細解釋 HTTP Status Code
0 success 請求成功；各 Token 的處理結果請查看 results。 200
21003 Parameter value is invalid platform、tokens 或 apns_production 不合法。 400
21004 basic auth failed Master Secret 錯誤。 401
21008 app_key is not a 24 size string AppKey 長度不合法。 400
23010 Rate limit exceeded for the API 目前 AppKey 的介面呼叫頻率超過限制。 400
27000 Server inner err 服務內部錯誤，請稍後重試。 500
27001 app_key does not exist or basic info is invalid 未提供 Basic Auth、AppKey 不存在或應用程式驗證資訊無效。 401
27002 parameter is invalid 請求本文缺失、JSON 格式錯誤或參數類型錯誤。 400
Icon Solid Transparent White Qiyu
聯繫銷售