概要: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} |
リクエストの各データ行で、ユーザーを一意に表すために使用する識別子。 ここで指定した値は、リクエスト内のすべての行に適用されます。 指定可能な値:
|
はい |
| {action} | "add" |
いいえ デフォルト値:"add" |
| {key_value} | 指定したkey_typeに対応する有効な識別子の値 | はい |
| {identifiers} |
追加する識別子の名前と値を含むオブジェクト:
|
はい * 3つの識別子のうち、少なくとも1つの値を含める必要があります。 |
| {hashed_emails} |
ハッシュ化したメールアドレスを最大2つ含む配列 形式:
ハッシュ化前の値の例:name@domain.com |
いいえ |
| {phone_number_sha256} |
電話番号(下記の注意を参照) 形式:
ハッシュ化前の値の例: 442070313000 |
いいえ |
| {phone_number_e164_sha256} |
E164形式の電話番号(下記の注意を参照) 形式
ハッシュ化前の値の例: +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} |
リクエストの各データ行で、ユーザーを一意に表すために使用する識別子。 ここで指定した値は、リクエスト内のすべての行に適用されます。 指定可能な値:
|
はい |
| {key_value} | 指定したkey_typeに対応する有効な識別子の値 | はい |
| {action} | "remove" |
いいえ デフォルト値:"add" |
| {identifiers} |
値を削除する識別子の名前を含む配列:
|
はい
|
制限事項
{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に対応しています。
|
| 400 | リクエストのdataには、少なくとも1つの要素が必要です | データリストは空にできません。 |
| 400 | 1つのリクエストのdataは、4,000件を超えることはできません | データリストは最大4,000行まで含められます。 |
| 400 | リクエストのdataに、無効な要素が多すぎます | 変更するデータの10%超が、仕様に適合していません。 |
| 404 | 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リクエスト