オーディエンス—追加識別子API

推奨
マーケター デベロッパー
最終更新日：

概要:Audiences追加識別子APIを使用して、社内システム（ビジネスインテリジェンスやCRMなど）からAppsFlyerオーディエンスにユーザー識別子を一括アップロードし、これらの識別子に基づいてより幅広いオーディエンスコミュニケーションを関連パートナーに提供します。

APIについて 

Audiences追加識別子APIを利用することで、社内システムから以下のユーザー識別子をAppsFlyerオーディエンスに追加できます。

  • ハッシュ化されたメールアドレス（最大2つ）
  • ハッシュ化された電話番号
  • ハッシュ化されたE164電話番号

後にこれらの識別子をオーディエンスパートナーに送信することを選択できます（アカウントレベルのユーザー識別子ポリシーに従って）、これによりパートナーはターゲットオーディエンスをより正確に識別できます。すべての広告パートナーがすべての識別子をサポートするわけではないことに注意してください。

このAPIはいつ使用するべきですか？

このAPIは、大量の識別子データをアップロードする際に使用するよう設計されています。これは通常、時間の経過と共に収集されたデータを指します（例：過去12か月間にアプリのすべてのユーザーから収集されたハッシュ化されたメール）。特定のデバイスからの識別子をリアルタイムに個別更新するには、AppsFlyer SDKまたはS2SモバイルAPIで追加識別子を設定してください。

重要！

暗号化:すべての追加識別子値は、SHA256ハッシュで暗号化する必要があります。暗号化されていない識別子は処理されません。

タイミング:識別子の正確な一致を保証するため、Audiences追加識別子APIは、AppsFlyer SDKによって主要な識別子がレポートされた翌日からすぐに使用できます（UTC）。例えば、2022年1月3日（UTC）に報告された識別子は、2022年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}
パラメーター 説明 必須
{アプリ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>"
      }
    }
  ]
}
パラメーター 説明 必須
{キータイプ}

リクエストの各データ行でユーザーを表現する唯一の値として用いられる識別子。

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

可能な値：

  • idfa
  • gaid
  • idfv
  • customer_user_id
  • imei
  • oaid
 はい
{アクション}

追加

いいえ

デフォルト値：追加
{キー値}

指定されたkey_typeの有効な識別子の値

 はい

{識別子}

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

  • {ハッシュ化されたメール}
  • {電話番号_sha256}
  • {電話番号_e164_sha256}

はい

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

{ハッシュ化されたメール}

最大2つのハッシュ化されたメールアドレスの配列

形式：

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

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

いいえ

{電話番号_sha256}

電話番号（下記注記参照）

形式：

  • 記号、文字、先頭のゼロは使用不可
  • 国コードを含める
  • SHA256ハッシュ

ハッシュ化前の値の例：

442070313000

いいえ
{電話番号_e164_sha256}

E164形式の電話番号（下記の注記を参照）

形式

  • E164電話番号
  • SHA256ハッシュ

ハッシュ化前の値の例：

+442070313000

いいえ

注記 

広告パートナーによってサポートされる電話番号の形式は異なります。したがって、電話番号を追加する場合は、両方の識別子を送信することをおすすめします：phone_number_sha256 と phone_number_e164_sha256。

制限事項

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

  • 以前に存在していた値（ある場合）は、リクエストで送信された値によって上書きされます。
  • {data}オブジェクトには、リクエストごとに最大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}
パラメーター 説明 必須
{アプリ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"
      ]
    }
  ]
}
パラメーター 説明 必須
{キータイプ}

リクエストの各データ行でユーザーを表現する唯一の値として用いられる識別子。

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

可能な値：

  • idfa
  • gaid
  • idfv
  • customer_user_id
  • imei
  • oaid
 はい
{キー値}

指定されたkey_typeの有効な識別子の値

 はい
{アクション}

削除

いいえ

デフォルト値：追加

{識別子}

削除したい識別子の名前を含む配列：

  • {ハッシュ化されたメール}
  • {電話番号_sha256}
  • {電話番号_e164_sha256}

はい


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

制限事項

{data}オブジェクトには、リクエストごとに最大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

リクエストには少なくとも1つの要素を持つ「データ」が必要です

データリストは空にできません。

400

リクエストの「データ」は1回のリクエストで4000を超えてはいけません

データリストには最大4,000行含めることができます。

400

リクエストデータに無効な「データ」要素が多すぎます

変更するデータの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"
}

レート制限

  • 1秒につき5リクエスト
  • 1分につき350リクエスト