どのようにお手伝いできますか?

APIによるAudiencesへの追加識別子のアップロード

  • 更新

概要:Audiences Additional Identifiers APIを使用し、BIやCRMなどの社内システムからAppsFlyer Audiencesにユーザー識別子を一括アップロードできます。識別子を基に、対象パートナーでより幅広いオーディエンスにアプローチできるようになります。

APIについて 

Audiences Additional Identifiers APIでは、社内システムから以下のユーザー識別子をAppsFlyer Audiencesに追加できます。

  • 最大2つのハッシュ化したメールアドレス
  • ハッシュ化した電話番号
  • ハッシュ化したE164形式の電話番号

アカウント単位のユーザー識別子の共有ポリシーに従い、これらの識別子をAudiencesのパートナーに送信するよう選択できます。パートナーは、対象のオーディエンスをより正確に識別できるようになります。すべての広告パートナーがすべての識別子に対応しているわけではありません。

このAPIを使用する場面

このAPIは、大量の識別子データをアップロードするためのものです。通常は、一定期間に収集したデータを対象とします。たとえば、過去12か月間にアプリの全ユーザーから収集した、ハッシュ化済みのメールアドレスなどです。特定デバイスの識別子をリアルタイムに個別更新する場合は、AppsFlyer SDKまたはS2S-mobile APIで追加識別子を設定してください。

重要

ハッシュ化:追加識別子のすべての値は、必ずSHA256でハッシュ化してください。ハッシュ化されていない識別子は処理されません。

利用可能になる時期:正確に照合できるよう、このAPIはAppsFlyer SDKから主要な識別子を送信した翌日以降に使用できます(UTC基準)。たとえば、2022年1月3日(UTC)に送信した主要な識別子は、1月4日(UTC)以降にこのAPIで更新できます。

操作

認証

リクエストには、アカウントのAppsFlyer V2.0 APIトークンを含むHTTPヘッダーが必要です。アカウントの管理者に、AppsFlyerの管理画面からトークンを取得するよう依頼してください。

APIの仕様とコード例

識別子の追加・変更(PUT)

APIリクエストURL

https://hq1.appsflyer.com/api/audience-bulk-api/v1/additional-identifiers/app/{app-id}
パラメータ 説明 必須
{app-id} 識別子を収集したアプリのアプリID(AppsFlyerの管理画面に表示される値) はい

APIリクエスト本文

{
  "key_type": "<key_type>",
  "action": "add",
  "data": [
    {
      "key_value": "<key_value>",
      "identifiers": {
        "hashed_emails": [
          "<hashed_email_value>",
          "<hashed_email_value>"
        ],
        "phone_number_sha256": "<phone_number_sha256_value>",
        "phone_number_e164_sha256": "<phone_number_e164_sha256_value>"
      }
    },
    {
      "key_value": "<key_value>",
      "identifiers": {
        "hashed_emails": [
          "<hashed_email_value>",
          "<hashed_email_value>"
        ],
        "phone_number_sha256": "<phone_number_sha256_value>",
        "phone_number_e164_sha256": "<phone_number_e164_sha256_value>"
      }
    }
  ]
}
パラメータ 説明 必須
{key_type}

リクエストの各データ行で、ユーザーを一意に表すために使用する識別子。

ここで指定した値は、リクエスト内のすべての行に適用されます。

指定可能な値:

  • idfa
  • gaid
  • idfv
  • customer_user_id
  • imei
  • oaid
はい
{action} "add" 

いいえ

デフォルト値:"add"

{key_value} 指定したkey_typeに対応する有効な識別子の値 はい
{identifiers}

追加する識別子の名前と値を含むオブジェクト:

  • {hashed_emails}
  • {phone_number_sha256}
  • {phone_number_e164_sha256}

はい

 

* 3つの識別子のうち、少なくとも1つの値を含める必要があります。

{hashed_emails}

ハッシュ化したメールアドレスを最大2つ含む配列

形式:

  • 小文字
  • 空白なし
  • SHA256でハッシュ化

ハッシュ化前の値の例:name@domain.com

いいえ
{phone_number_sha256}

電話番号(下記の注意を参照)

形式:

  • 記号、英字、先頭のゼロは使用不可
  • 国番号を含める
  • SHA256でハッシュ化

ハッシュ化前の値の例:

442070313000

いいえ
{phone_number_e164_sha256}

E164形式の電話番号(下記の注意を参照)

形式

  • E164形式の電話番号
  • SHA256でハッシュ化

ハッシュ化前の値の例:

+442070313000
 

いいえ

注意 

  • 広告パートナーによって、対応する電話番号の形式が異なります。電話番号を追加する場合は、phone_number_sha256とphone_number_e164_sha256の両方を送信することを推奨します。
  • customer_user_idは、このセクションのほかの記事でCUID(カスタマーユーザーID)と呼んでいる識別子と同じです。 key_typeがcustomer_user_idの場合、アカウントのCUIDの値をkey_valueとして使用します。この識別子やほかの対応識別子については、Audiencesのユーザー識別子の共有ポリシーを参照してください。

制限事項

識別子の追加・変更リクエストには、以下の制限が適用されます。

  • 既存の値がある場合は、リクエストで送信した値で上書きされます。
  • {data}オブジェクトは、1リクエストにつき最大4,000行(key_values)を含められます。

識別子を追加するリクエストの例

HTTP PUT
body:
{
  "key_type": "idfv",
  "action": "add",
  "data": [
    {
      "key_value": "CDDA802e-AAAA-BBBB-CCCC-DDDDDDDDDDDD",
      "identifiers": {
        "hashed_emails": [
          "34d31be18022626de6b311d6a76e791176d2691b6eef406f524d8f56364c187a",
          "d8c2aec999baad2464e521873ee4465caaf7ff6db8c8b4a25b09ca07694e4dee"
        ],
        "phone_number_sha256": "6c91c4c640f6ef0162833260db4f13dec0df2b683092f4dba7e874bef1acea37",
        "phone_number_e164_sha256": "f3d7e96c73fb0de1b66acfce541d7af758fbd4f3fa3af0ea4e10110000d3625e"
      }
    }
  ]
}

識別子の削除(PUT)

APIリクエストURL

https://hq1.appsflyer.com/api/audience-bulk-api/v1/additional-identifiers/app/{app-id}
パラメータ 説明 必須
{app-id} 識別子を収集したアプリのアプリID(AppsFlyerの管理画面に表示される値) はい

APIリクエスト本文

{
  "key_type": "<key_type>",
  "action": "remove",
  "data": [
    {
      "key_value": "<key_value>",
      "identifiers": [
        "hashed_emails",
        "phone_number_sha256",
        "phone_number_e164_sha256"
      ]
    },
    {
      "key_value": "<key_value>",
      "identifiers": [
        "hashed_emails",
        "phone_number_sha256",
        "phone_number_e164_sha256"
      ]
    }
  ]
}
パラメータ 説明 必須
{key_type}

リクエストの各データ行で、ユーザーを一意に表すために使用する識別子。

ここで指定した値は、リクエスト内のすべての行に適用されます。

指定可能な値:

  • idfa
  • gaid
  • idfv
  • customer_user_id
  • imei
  • oaid
はい
{key_value} 指定したkey_typeに対応する有効な識別子の値 はい
{action} "remove"

いいえ

デフォルト値:"add"

{identifiers}

値を削除する識別子の名前を含む配列:

  • {hashed_emails}
  • {phone_number_sha256}
  • {phone_number_e164_sha256}

はい


* 3つの識別子のうち、少なくとも1つを含める必要があります。

制限事項

{data}オブジェクトは、1リクエストにつき最大4,000行(key_values)を含められます。

識別子を削除するリクエストの例

HTTP PUT
body:
{
  "key_type": "gaid",
  "action": "remove",
  "data": [
    {
      "key_value": "cdda802e-aaaa-bbbb-cccc-dddddddddddd",
      "identifiers": [
        "hashed_emails",
        "phone_number_sha256",
        "phone_number_e164_sha256"
      ]
    }
  ]
}

レスポンス

コード メッセージ 説明
202 処理を受け付けました 次回の処理期間にリクエストを適用します。
400 リクエスト本文には有効なkey_typeが必要です

以下のkey_typesに対応しています。

  • idfa
  • gaid
  • idfv
  • customer_user_id
  • imei
  • oaid
400 リクエストのdataには、少なくとも1つの要素が必要です データリストは空にできません。
400 1つのリクエストのdataは、4,000件を超えることはできません データリストは最大4,000行まで含められます。
400 リクエストのdataに、無効な要素が多すぎます 変更するデータの10%超が、仕様に適合していません。
404 AppsFlyer | ページが見つかりません

以下を確認してください。

  • APIリクエストURLの{app-id}が正しいこと。
  • HTTPヘッダーに正しいAppsFlyer V2.0 APIトークンが含まれていること。アカウントの管理者は、AppsFlyerの管理画面からこのトークンを取得できます。

レスポンスの例

{
"message": "Accepted for processing",
"received": 1000,"invalid": 2,
"trace-id": "698ed323-c787-45b5-b792-463c67c94064"
}
{
"error": "Request body must have a valid key_type",
"trace-id": "18a5f685-ea4d-4ca9-beab-a542a3786d12"
}
{
"error": "Request must have 'data' with at least 1 element",
"trace-id": "c155a7fa-b573-4efe-9bfb-5ae7de40e7fd"
}
{
"error": "Request 'data' should not exceeds the size of 4000 in a single request”,
"trace-id": "b325a7fa-b573-4efe-9bfb-5ae7de40e72c"
}
{
"error": "Request data has too many invalid 'data' elements",
"valid": 2,
"invalid": 30,
"trace-id": "33551c1d-5682-405e-a959-c8729ca74735"
}

リクエスト数の制限

  • 毎秒5リクエスト
  • 毎分350リクエスト