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

POST /token/generate

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

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

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

important

どのオプションを使用する場合でも、UID2 を生成するために送信するデータは、送信前に正規化、ハッシュ化、およびエンコードする必要があります。詳細については、Normalization and encoding を参照してください。

Request format​

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

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

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

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

Path parameters​

Path ParameterData TypeAttributeDescription
{environment}string必須テスト (インテグレーション) 環境: https://operator-integ.uidapi.com
本番環境: ユーザーの所在地に応じて最適な URL が異なります。ユースケースに最適な URL の選択方法および有効なベース URL の全リストは、Environments を参照してください。
Notes:
  • integ 環境と prod 環境では、異なる API Key が必要です。
  • トークンの有効期限は変更される可能性がありますが、integ 環境では常に prod 環境よりも大幅に短くなります。

Unencrypted JSON body parameters​

important

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

Body ParameterData TypeAttributeDescription
emailstring条件付きで必須トークンを生成するメールアドレスです。
email_hashstring条件付きで必須SHA-256 ハッシュし、Base64 エンコード した 正規化 済みメールアドレスです。
phonestring条件付きで必須トークンを生成する 正規化 済み電話番号です。
phone_hashstring条件付きで必須SHA-256 ハッシュし、Base64 エンコード した、正規化 済み電話番号です。

Request examples​

important

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

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

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

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

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

詳細といくつかのプログラミング言語でのコードの例は、Encrypting requests and decrypting responses を参照してください。

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_fromnumberUID2 Token のリフレッシュを検討するタイミングを示す Unix タイムスタンプ (ミリ秒単位) です。
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