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
联系销售