Logo Site EngageLab Mark Colored Transparentドキュメント
AppPush
ドキュメントホーム
ユーザーガイド開発者ガイドデータとプライバシーベストプラクティス更新履歴
検索
ログイン
開発者ガイド/REST API/デバイス登録 API
開発者ガイドREST APIデバイス登録 API...

デバイス登録 API

最新更新：1日前

デバイス登録 API は、AppPush のデバイストークンを登録し、registration_id を取得するためのサーバー向けインターフェースを提供します。

Token から registration_id を取得

この API を使用すると、サーバーから FCM Tokens または APNs Device Tokens を使って AppPush ユーザーを登録し、EngageLab が生成した registration_id を取得できます。取得した registration_id は、特定ユーザーへのプッシュや、タグ、エイリアスなどのデバイス関連 APIs に使用できます。

利用制限

  • 1 回のリクエストで 1～500 個の Tokens を登録できます。
  • 1 回のリクエストでは、1 つのプラットフォームの Tokens のみ登録できます。FCM Tokens のバッチまたは APNs Device Tokens のバッチのいずれかであり、FCM と APNs を同じリクエストに混在させることはできません。
  • 同じアプリケーション、プラットフォーム、Token に対する再リクエストは冪等です。ユーザーは重複して作成されず、既存の registration_id が返されます。
  • 結果は、リクエスト内の Tokens と同じ順序で返されます。

エンドポイント

POST /v4/devices/token/registration_id
              
              POST /v4/devices/token/registration_id
このコードブロックはフローティングウィンドウ内に表示されます

完全なリクエスト URL は、アプリケーションが所属するデータセンターの 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 はい Tokens が属するプラットフォーム。指定可能な値は android と ios です。FCM Tokens には android を使用します。
tokens array<string> はい 登録する Tokens の一覧。件数は 1～500 です。同じリクエスト内のすべての Tokens は、platform で指定したプラットフォームに属している必要があります。
apns_production boolean iOS では必須 APNs 環境。true は本番環境、false は開発環境を示します。Android リクエストではこのフィールドを指定できません。

Token の形式規則

  • FCM Token：空でない 400 文字以内の文字列である必要があります。印字可能な ASCII 文字（0x21～0x7E）のみ使用できます。スペース、改行、先頭または末尾の空白は使用できません。
  • APNs Device Token：空でない、文字数が偶数の 400 文字以内の 16 進数文字列である必要があります。使用できる文字は 0-9、a-f、A-F のみです。スペース、山括弧、その他の区切り文字は使用できません。

この API は 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 でエラーを返します。ほかの Tokens は引き続き正常に処理できます。次の例では、空の 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"
    }
  ]
}
このコードブロックはフローティングウィンドウ内に表示されます

リクエスト失敗例

リクエストパラメーター全体が不正な場合、API は 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 が含まれていない。

API レスポンス

HTTP ステータスコード

HTTP ステータスコードを参照してください。

エラーコード

次の表は、リクエストレベルのエラーコードです。バッチリクエスト内の個々の Token の処理エラーは results[].code と results[].message で返され、ほかの Tokens の処理には影響しません。

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 の API 呼び出し頻度が上限を超えています。 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
お問い合わせ