メインコンテンツまでスキップ

POST /token/generate

ユーザーの DII (メールアドレスまたは電話番号) から UID2 Token を生成します。DII が有効で、ユーザーがUID2をオプトアウトしていない場合、UID2 Token と関連する値を返します。

Used by: このエンドポイントは、主にパブリッシャーが使用します。

important

optout_check パラメータは値 1 が必須で、ユーザーがオプトアウトしたかどうかをチェックします。

このエンドポイントを直接呼び出すのではなく、UID2 SDK を使って管理することもできます。オプションの概要については、SDKs: Summary を参照してください。

Request Format​

認証の詳細については、 Authentication and Authorization を参照してください。

POST '{environment}/v2/token/generate'

このエンドポイントリクエストについて知っておくべきことは、以下のとおりです:

  • サービスにアクセスする際に使用する API key を秘密にするため、 UID2 Token は認証後に Server-Side でのみ生成する必要があります。
  • すべてのリクエストを秘密鍵で暗号化する必要があります。詳細といくつかのプログラミング言語でのコードの例は リクエストの暗号化とレスポンスの復号化 を参照してください。

Path Parameters​

Path ParameterData TypeAttributeDescription
{environment}string必須インテグレーション環境: https://operator-integ.uidapi.com
本番環境: https://prod.uidapi.com
リージョンごとのオペレーターを含む全リストは Environments を参照してください。
Notes:
  • integ 環境と prod 環境では、異なる API keys が必要です。
  • トークンの有効期限は変更される可能性がありますが、integ 環境では常に prod 環境よりも大幅に短くなります。

Unencrypted JSON Body Parameters​

important

リクエストを暗号化するときには、以下の4つの条件付きパラメータのうち 1つ と、必須パラメータである optout_check の値 1 のみを、JSON ボディのキーと値のペアとして含める必要があります。

Body ParameterData TypeAttributeDescription
emailstring条件付きで必要トークンを生成するメールアドレスです。
email_hashstring条件付きで必要SHA-256 ハッシュし、Base64 エンコード した 正規化 済みメールアドレスです。
phonestring条件付きで必要トークンを生成する 正規化 済み電話番号です。
phone_hashstring条件付きで必要SHA-256 ハッシュし、Base64 エンコード した、正規化 済み電話番号です。
optout_checknumber必須ユーザーがオプトアウトしたかどうかをチェックします。このパラメータは 1 とします。

Request Examples​

important

サービスへのアクセスに使用する API キーを秘密にしておくため、POST /token/generate エンドポイントは、POST /token/refresh とは異なり、Server-Side から呼び出す必要があります。Client-Side でトークンを生成する場合は、Client-Side Integration Options (Web ベースの実装) または UID2 Client-Side Integration Guide for Mobile を参照してください。

以下は、各パラメータの暗号化されていない JSON リクエストボディの例で、このうちの 1 つはトークン生成リクエストに含める必要があります:

{
  "email": "username@example.com",
  "optout_check": 1
}
{
  "email_hash": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=",
  "optout_check": 1
}
{
  "phone": "+12345678901",
  "optout_check": 1
}
{
  "phone_hash": "wdN1alhrbw1Bmz49GzKGdPvGxLhCNn7n3teAOQ/FSK4=",
  "optout_check": 1
}

以下は、メールアドレスハッシュの暗号化トークン生成リクエストの例です:

echo '{"email_hash": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=","optout_check":1}' | python3 uid2_request.py https://prod.uidapi.com/v2/token/generate [Your-Client-API-Key] [Your-Client-Secret]

詳細といくつかのプログラミング言語でのコードの例は、リクエストの暗号化とレスポンスの復号化 を参照してください。

Decrypted JSON Response Format​

注記

レスポンスは、HTTP ステータスコードが 200 の場合のみ暗号化されます。それ以外の場合、レスポンスは暗号化されません。

このセクションには、次のサンプルレスポンスが含まれています:

Successful Response​

復号化に成功すると、指定されたメールアドレス、電話番号、またはそれぞれのハッシュに対するユーザーの Advertising Token および Refresh Token が返されます。

{
  "body": {
    "advertising_token": "A4AAAABlh75XmviGJi-hkLGs96duivRhMd3a3pe7yTIwbAHudfB9wFTj2FtJTdMW5TXXd1KAb-Z3ekQ_KImZ5Mi7xP75jRNeD6Mt6opWwXCCpQxYejP0R6WnCGnWawx9rLu59LsHv6YEA_ARNIUUl9koobfA9pLmnxE3dRedDgCKm4xHXYk01Fr8rOts6iJj2AhYISR3XkyBpqzT-vqBjsHH0g",
    "identity_expires": 1724899014352,
    "refresh_expires": 1724981814352,
    "refresh_from": 1724896314352,
    "refresh_response_key": "TS0H0szacv/F3U8bQjZwjSaZJjxZbMvxqHn1l3TL/iY=",
    "refresh_token": "AAAAAGYzgUszke2sV9CxXnxyFfUU+KDCJUCXNbj1/FVcCjvR7K07jYaWe44wxM6SOTwG7WQB4XfIcquMqH57iHUnAu1zacYf9g58BtbhKCYWTwrdpB0fSqTANBXOYy+yBnl6tLRwVv32LqRCj76D8meO4tw+MKlUAc2EoFzFNPSfZLpA3Jk4q68vH6VJH/WIuu1tulrVm5J8RZAZnmTlEcsPdjoOC6X4w3aAwiwtbeGw7yOO0immpVoC5KaXnT9olRPTlrt8F9SvebLIcqkYhvRMPpl1S89yeneyGo++RnD9qSHIrfu9To3VwYW018QuvyA15uv4No4BoAzyPuHqzQ8gAs6csWwZ7VwfYD7DSJXlQiIpwzjA2Hl8mgg/5fcXwKEJ"
  },
  "status": "success"
}

Optout​

以下は、ユーザーがオプトアウトした場合のレスポンス例です。

{
  "status": "optout"
}

Response Body Properties​

レスポンスボディには、次の表に示すプロパティが含まれます。

PropertyData TypeDescription
advertising_tokenstringユーザーの暗号化された Advertising Token (UID2) です。
refresh_tokenstringUID2 Service と最新の identity トークンのセットを交換できる暗号化されたトークンです。
identity_expiresnumberAdvertising Token の有効期限を示す Unix タイムスタンプ (ミリ秒単位) です。
refresh_fromnumberSDK for JavaScript (SDK for JavaScript Reference Guide を参照してください) が UID2 Token のリフレッシュを開始するタイミングを示す Unix タイムスタンプ(ミリ秒単位)。
TIP: SDK を使用していない場合は、このタイムスタンプから UID2 Token もリフレッシュすることを検討してください。
refresh_expiresnumberRefresh Token の有効期限を示す Unix タイムスタンプ (ミリ秒単位) です。
refresh_response_keystringPOST /token/refresh リクエストでレスポンス復号化のために使用される鍵です。

Response Status Codes​

次の表は、status プロパティの値と、それに対応する HTTP ステータスコードの一覧です。

StatusHTTP Status CodeDescription
success200リクエストは成功しました。レスポンスは暗号化されています。
optout200リクエストは成功しました。ユーザーがオプトアウトしたため、トークンを生成できませんでした。
client_error400リクエストに不足している、または無効なパラメータがありました。
unauthorized401クエストにベアラートークンが含まれていない、無効なベアラートークンが含まれている、またはリクエストされた操作を実行するのに許可されていないベアラートークンが含まれていました。

status の値が success 以外であれば、message フィールドにその問題に関する追加情報が表示されます。

Test Identities​

TypeIdentityPurposeNext Endpoint
Emailvalidate@example.comキャッシュした advertising_token が、指定したメールアドレスの advertising_token と一致するかテストします。POST /token/validate
Emailoptout@example.comこのメールアドレスをリクエストに使用すると、常に optout レスポンスが生成されます。POST /token/generate
Emailrefresh-optout@example.comこのメールアドレスをリクエストに使用すると、常に refresh_token による ID レスポンスが生成され、その結果 optout レスポンスが生成されます。POST /token/refresh
Phone+12345678901キャッシュした advertising_token が、指定した電話番号の advertising_token と一致するかテストします。POST /token/validate
Phone+00000000002この電話番号をリクエストに使用すると、常に optout レスポンスが生成されます。POST /token/generate
Phone+00000000000この電話番号をリクエストに使用すると、常に refresh_token による ID レスポンスが生成され、その結果optoutレスポンスが生成されます。POST /token/refresh