POST /v2/identity/map

複数のメールアドレス、電話番号、またはそれぞれのハッシュを、raw UID2 とソルトバケット ID にマッピングします。このエンドポイントを使用して、オプトアウト情報の更新をチェックすることもできます。

Used by: このエンドポイントは、主に広告主やデータプロバイダーが使用します。詳細は Advertiser/data provider integration overview を参照してください。

UID2 のオプトアウトワークフローとユーザーがオプトアウトする方法の詳細は、User opt-out を参照してください。

Version

このドキュメントは、このエンドポイントのバージョン 2 のものであり、最新バージョンではありません。最新バージョン v3 の詳細は、POST /v3/identity/map を参照してください。

注記

以前のバージョンを使用している場合は、改善点を活用するためにできるだけ早くアップグレードすることを推奨します。移行ガイダンスは、Migration from POST /v2/identity/map を参照してください。廃止に関する情報は、Deprecation schedule: Endpoint versions を参照してください。

Batch size and request parallelization requirements

知っておくべきことは以下のとおりです:

リクエストの最大サイズは 1MB です。
大量のメールアドレス、電話番号、またはそれぞれのハッシュをマップするには、1 バッチあたり最大 5,000 アイテムで送信してください。同時に送信するバッチは 20 件以内にすることを勧めます。
メールアドレス、電話番号、またはそれぞれのハッシュのマッピングを必ず保存してください。
マッピングを保存しないと、数百万のメールアドレスや電話番号をマッピングする必要がある場合に、処理時間が大幅に増加する可能性があります。しかし、実際に更新が必要なマッピングのみを再計算することで、毎日更新が必要な raw UID2 の数は約 1/365 となり、総処理時間を短縮できます。Advertiser/data provider integration overview と FAQs for advertisers and data providers も参照してください。

Rate limiting

公正な使用とプラットフォームの安定性を確保するために、POST /v2/identity/map エンドポイントは、急激なトラフィックの増加から保護するためにレート制限を適用しています。短時間に多数のリクエストを送信すると、429 エラー応答が返される可能性があります。

レート制限エラーを適切に処理するには、リクエストを再試行する際に exponential backoff とランダムジッターを実装することを勧めます。制限内でスループットを最大化するには、多数の小さなリクエストを送信するのではなく、リクエストごとに最大バッチサイズの 5,000 アイテムを使用してください。

Request format

POST '{environment}/v2/identity/map'

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

important

すべてのリクエストを秘密鍵で暗号化する必要があります。詳細といくつかのプログラミング言語でのコードの例は、Encrypting requests and decrypting responses を参照してください。

Path parameters

Path Parameter	Data Type	Attribute	Description
`{environment}`	string	必須	テスト (インテグレーション) 環境: `https://operator-integ.uidapi.com` 本番環境: `https://prod.uidapi.com` リージョンごとのオペレーターを含む全リストは Environments を参照してください。

注記

インテグレーション環境と本番環境では、異なる API Key が必要です。各環境の認証情報を取得する方法は、Getting your credentials を参照してください。

Unencrypted JSON body parameters

important

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

Body Parameter	Data Type	Attribute	Description
`email`	string array	条件付きで必須	マッピングするメールアドレスのリストです。
`email_hash`	string array	条件付きで必須	マッピングする SHA-256 ハッシュし、Base64 エンコードした正規化済みメールアドレスのリストです。
`phone`	string array	条件付きで必須	マッピングする正規化済み電話番号のリストです。
`phone_hash`	string array	条件付きで必須	マッピングする SHA-256 ハッシュし、Base64 エンコードした正規化済み電話番号のリストです。

Request examples

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

{
  "email": [
    "user@example.com",
    "user2@example.com"
  ]
}

{
  "email_hash": [
      "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=",
      "KzsrnOhCq4tqbGFMsflgS7ig1QLRr0nFJrcrEIlOlbU="
  ]
}

{
  "phone": [
      "+12345678901",
      "+441234567890"
  ]
}

{
  "phone_hash": [
      "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=",
      "Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ="
  ]
}

以下は、電話番号に対する POST /identity/map エンドポイントへの暗号化リクエストの例です:

echo '{"phone": ["+12345678901", "+441234567890"]}' | python3 uid2_request.py https://prod.uidapi.com/v2/identity/map [Your-Client-API-Key] [Your-Client-Secret]

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

Decrypted JSON response format

注記

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

復号化に成功すると、指定したメールアドレス、電話番号、またはそれぞれのハッシュに対する raw UID2 とソルトバケット ID が返されます。

{
  "body": {
    "mapped": [
      {
        "identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=",
        "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=",
        "bucket_id": "a30od4mNRd"
      },
      {
        "identifier": "Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ=",
        "advertising_id": "IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ=",
        "bucket_id": "ad1ANEmVZ"
      }
    ]
  },
  "status": "success"
}

一部の識別子が無効と判断された場合、それらの識別子は "unmapped" リストとしてレスポンスに含まれます。この場合でも、レスポンスステータスは "success" となります。すべての識別子がマッピングされた場合、"unmapped" リストはレスポンスに含まれません。

{
  "body": {
    "mapped": [
      {
        "identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=",
        "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=",
        "bucket_id": "a30od4mNRd"
      }
    ],
    "unmapped": [
      {
        "identifier": "some@malformed@email@hash",
        "reason": "invalid identifier"
      }
    ]
  },
  "status": "success"
}

一部の識別子が UID2 エコシステムからオプトアウトしている場合、オプトアウトした識別子は、見つかった無効な識別子とともに "unmapped" リストに移動されます。この場合でも、レスポンスステータスは "success" です。

{
  "body": {
    "mapped": [
      {
        "identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=",
        "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=",
        "bucket_id": "a30od4mNRd"
      }
    ],
    "unmapped": [
      {
        "identifier": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=",
        "reason": "optout"
      }
    ]
  },
  "status": "success"
}

Response body properties

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

Property	Data Type	Description
`identifier`	string	リクエストボディで指定されたメールアドレス、電話番号、またはそれぞれのハッシュです。
`advertising_id`	string	対応する Advertising ID (raw UID2) です。
`bucket_id`	string	raw UID2 の生成に使用したソルトバケットの ID です。

Response status codes

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

Status	HTTP Status Code	Description
`success`	200	リクエストは成功しました。レスポンスは暗号化されています。
`client_error`	400	リクエストに不足している、または無効なパラメータがありました。
`unauthorized`	401	リクエストにベアラートークンが含まれていない、無効なベアラートークンが含まれている、またはリクエストされた操作を実行するのに許可されていないベアラートークンが含まれていました。
N/A	429	このエンドポイントへのリクエストが多すぎます。待ってからexponential backoffを使用して再試行してください。

status の値が success 以外であれば、message フィールドにその問題に関する追加情報が表示されます。Note: 429 のレスポンスには、JSON 形式のレスポンス本文が含まれていません。

Version​

Batch size and request parallelization requirements​

Rate limiting​

Request format​

Path parameters​

Unencrypted JSON body parameters​

Request examples​

Decrypted JSON response format​

Response body properties​

Response status codes​