オーディエンスのインポート

概要:社内システム (BI、CRMなど) から既に定義済みのオーディエンスセグメントをAppsFlyerオーディエンスにインポートしましょう。そうすることで、オーディエンスを使用して、これらのセグメントを広告パートナーと連携し、維持することができます。

オーディエンスをインポートする必要性

社内システムで定義済みのオーディエンスセグメントがある場合、これらのオーディエンス (デバイスおよび/またはユーザー識別子の一覧) をAppsFlyerにインポートすることで、AppsFlyerのオーディエンス機能を中心に、全てのオーディエンスセグメントを広告パートナーと接続し一元管理することができます。また、識別子の照合やデータの充実、キャンペーンの指標との連携など、他のオーディエンス機能を最大限に活用することができます。

次のユースケースをご覧ください。

 例

リマーケティングプロモーション
誕生月のユーザーを対象にプロモーションを実施したいと考えています。

このためにオーディエンス機能を使った方法をご紹介します。

  1. 社内CRMを使ってユーザーのリストを誕生日と一緒に作成してください。
  2. 誕生月に応じてリストをセグメント化し、広告IDの個別リストをエクスポートしてください。
  3. このリストをオーディエンスとしてAppsFlyerにインポートし、プロモーションを実施したいパートナーと連携してください。
  4. パートナーと関連するオーディエンスを対象とするキャンペーンを設定してください。

追加ユーザーの獲得
アプリ開発スタジオが別のスタジオを買収しました。買収したスタジオは以前同社のアプリをインストール済のユーザーのデバイスIDを把握しています。今回これらのユーザーを対象に、自社アプリをインストールを促すキャンペーンを実施します。

このためにオーディエンス機能を使った方法をご紹介します。

  1. 買収したスタジオからデバイスIDのリストを取得し、AppsFlyerにオーディエンスとしてインポートしてください。
  2. キャンペーンを実施したいパートナーにオーディンスを接続してください。
  3. これらのユーザーを対象に、関連するパートナーとキャンペーンを設定してください。

オーディエンスインポート V2.0

ここからは、新しいオーディエンスインポート機能V2.0(CSVとAPIによるインポートのオプション)に関するコンセプトと手順について説明します。オーディエンスインポートV1.0(CSVとAPI)の従来の手順はこちらをご覧ください。

インポートするオーディエンスの種類

オーディエンスをインポートする際、次のいずれかの種類を指定する必要があります。これにより、AppsFlyerがアップロードされたオーディエンスをどのように処理しパートナーへアップロードするかが決まります。この選択は、オーディエンスが最初にインポートされたときに行われるもので、あとで変更することはできません。

標準的なインポートオーディエンス:

  • 識別子の照合とデータの強化を実施します パートナーにアップロードされたオーディエンスデータを充実させるために、オーディエンスがインポートされた識別子をオーディエンスデータベース内の既存の識別子(同じアプリの同じユーザーのもの)と照合するプロセスです。
  • パートナーへのアップロードは、アカウントのユーザー識別子ポリシーに従って実行されます。
  • この記事で紹介しているV2.0のインポート機能を使ってインポートする必要があります。

現状のままのインポートオーディエンス:

  • 識別子マッチングとデータエンリッチメントの処理は実行されません。
  • アカウントのユーザー識別子ポリシーを無視してパートナーにアップロードされます(つまり、インポートされたすべての識別子がパートナーにアップロードされます)。
  • CSVファイルとしてアップロードされたときには、GAID, IDFA, OAID などのデバイス ID のみを含めることができます。
  • ヘッダーのない識別子のリストは、CSVファイルとしてアップロードされた場合にのみ含めることができます。
  • この記事で紹介しているV2.0のインポート機能、または従来のV1.0インポート機能を使ってインポートできます。

 重要!

  • 2021年11月23日の時点で存在する全てのオーディエンスは、現状のままのオーディエンスと定義され標準オーディエンスに変更することはできません。こららのオーディエンスは、必要に応じて、V2.0インポート機能(同記事で説明)、または従来のV1.0インポート機能を使用して引き続き更新できます。
  • アドミンのみが新しいインポートオーディエンスを現状のままのオーディエンスとして指定できます。

オーディエンスのインポート手順

CSVファイルをアップロードするか、オーディエンスインポートAPIを使用して、オーディエンスをインポートしてください。

CSVファイルのインポート

以下の仕様に従って、CSVファイルを用意してください:

形式

  • アップロードするユーザー識別子ごとに1列に配置してください
  • 各列に識別子の名前を記載したヘッダー行(すべて小文字)を用意してください
  • 空白行は含めないでください
  • 最大行数:1000万行
  • Excelで作成した場合は、以下の画像のようにCSV (カンマ区切り) (*.csv) ファイルで保存してください

    CSV.jpg

識別子ハッシュ

列と識別子

  • データは、各列のデータを識別するためにヘッダー行を使用して取り込まれます。そのため、
    • 列の並び順には、特に指定がありません。
    • アップロードされていない識別子の欄を設ける必要はありません。
    • 以下で詳しく説明するとおり、各行に必要な識別子が含まれていれば、1つのCSVファイルに必要な数の識別子をインポートすることができます。
  • 使用できる識別子:
    • app_id
    • idfv
    • idfa
    • gaid
    • oaid
    • imei
    • cuid
    • emails
    • phone
    • phone_e164
    • braze_id
    • amplitude_id
  • 必須の識別子:
    • Androidオーディエンス:app_id + 次のいずれか一つ:gaidoiadimeicuidbraze_id または amplitude_id
    • iOSオーディエンス:app_id + 次のうち1つ:idfv または cuid または braze_id または amplitude_id
    注:app_id は「現状のまま (as-is) 」のオーディエンスには必要ありません。

CSVファイルの例:

new-import-android-example.csv
new-import-ios-example.csv

CSVファイルを使って新しいオーディエンスを作成しインポートする方法:

  1. インテグレーション > オーディエンスへ進みます。

  2. オーディエンスをインポートボタンをクリックしてください。
    新しいオーディエンス画面が開き、Define (定義) タブが表示されます。

  3. 一意のオーディエンス名を入力してください。

  4. オーディエンスのプラットフォームを選択してください:Android / iOS

  5. オーディエンスが標準オーディエンスか現状のままのオーディエンスかを指定してください。
    • 標準オーディエンスの場合は、ボックスにチェックを入れないでください。
    • 現状のままのオーディエンスの場合は、ボックスにチェックを入れてください。(注:このオプションはアドミンのみが利用できます。)
  6. オーディエンスを保存して続行をクリックしてください。
    インポートタブが表示されます。
  7. CSVを使用してインポートセクションで、新しい端末/ユーザーを追加というデフォルトのままにしてください(新規オーディエンスのため)。
  8. アップロードするCSVファイルを選択してください。
    Uploaded successfully / 正常にアップロードされましたという確認メッセージが表示されるのを待ってください。
  9. 次へをクリックします。
    Connect / 連携タブが表示されます。
  10. (オプション)オーディエンスをパートナーに接続する手順に従ってください。
  11. 完了をクリックしてください。

オーディエンスはオーディエンス管理画面に表示され、パートナーにインポートされ接続されています。ただし、インポートされたオーディエンスは、データの更新頻度が日次で処理されるため、新たにインポートされたオーディエンスリストはまだパートナーにアップロードできないことをご注意ください。

CSVファイルを使用して既存オーディエンスを更新する方法:

  1. インテグレーション > オーディエンスへ進みます。

  2. アップロードしたいオーディエンス名をクリックしてください。
    オーディエンスの編集画面が開き、Define/定義タブが表示されます。

  3. オーディエンス名を編集したい場合は、ここで編集してください。それ以外の場合は、インポートタブを選択して新しいCSVファイルをアップロードしてください。

  4. CSVを使用してインポートするセクションで、アップロードされたリストをどう処理するかを選択してください。
    • 新しい端末 / ユーザーを追加:既存オーディエンスにデバイス/ユーザーを追加します。
    • 既存オーディエンスからデバイス / ユーザーを削除:オーディエンスからアップロードされたリスト内のデバイス/ユーザー識別子を削除します。
    • 既存オーディエンスを新しいデバイス/ユーザーで上書き:オーディエンス全体をアップロードされたリストに置き換えます。
  5. アップロードするCSVファイルを選択してください。
    Uploaded successfully / 正常にアップロードされましたという確認メッセージが表示されるのを待ってください。
  6. 次へをクリックします。
    Connect / 連携タブが表示されます。
  7. 必要に応じて、このオーディエンスのパートナー接続を変更してください。
  8. 完了をクリックしてください。

CSVファイルを使用してオーディエンスが更新されました。ただし、インポートされたオーディエンスはデータの更新頻度が日次で処理されるため、修正されたオーディエンスリストはまだパートナーにアップロードされていませんのでご注意ください。

メッセージ 原因 対処法
Uploaded successfully(正常にアップロードされました)    
Seems like your device list is empty.Add some device IDs to it and try again(デバイスリストが空です。デバイスIDを追加してから再度実行してください) CSVファイルが空です。

CSVに少なくとも1つのデバイスIDが含まれていることを確認してください。

We couldn’t understand one or more of your device IDs(デバイスIDの識別ができません)
  • CSVフォマットが正しくありません
  • アップロードしたファイルがCSV形式ではありません。
  • CSVファイルは、有効なCSVエディター以外のプログラムによって編集および保存されました(例、Microsoft Excel)
  • デバイスIDの形式に誤りがあります。
  • CSVが必要な形式に沿っていることを確認してください。
  • すべてのデバイスIDが正しいフォーマットであることを確認してください。
  • Excelを使用した場合、上記のとおりCSVファイルで保存してください。
Cannot use import v1 while applying user account policy on audience(オーディエンスにユーザーアカウントポリシーを適用する場合、インポートV1.0を使用できません) V1.0のインポート構成を使用して、標準オーディエンスのCSVファイルをアップロードしました。標準オーディエンスはV2.0の構成でのCSVを使用してアップロードする必要があります。 アップロードするCSVファイルを、上記のフォーマット、列、識別子に合わせて編集してください。
We just had a temporary connection problem and couldn’t upload your file.You can try again now(接続に一時的な問題が発生したため、ファイルをアップロードできませんでした。今すぐ再試行してください) ネットワークエラーの可能性があります。 再度CSVファイルをアップロードしてください。
確認メッセージ

オーディエンスインポートAPIの使用

オーディエンスインポートAPIは、オーディエンスからデバイスを追加または削除するために使用されます。次の手順を使用して、APIリクエストURLとAPIリクエストBodyを生成してください。

APIリクエストURL

https://hq1.appsflyer.com/audiences-import-api/v2/{action}?api_token={api_token}
パラメーター 説明 必須
{action}
  • デバイスの追加:add
  • デバイスの削除:remove
はい
{api_token}

オーディエンスAPIトークンのインポート:

  • このトークンは、オーディエンスダッシュボードからコピーされたURLに含まれています(APIを使用してオーディエンスをインポートまたは更新する方法については、以下の手順を参照してください)。
  • 注意: これは、アカウントの AppsFlyer API トークン (V1.0 または V2.0) と同じ ではありません
はい

APIリクエストBody

{
  "import_key": "<import_key>",
  "platform": "<platform>",
  "devices":[
    {
    "<identifier_1_name>":"<identifier_1_value>",
    "<identifier_2_name>":"<identifier_2_value>",
    "<identifier_n_name>":"<identifier_n_value>"
    }
  ]
}
パラメーター 説明 必須
{import_key}

オーディエンスを識別するユニークなキー

  • 追加と削除の両方のエンドポイントで同じ import_key を使用してください。
はい
{platform}

android または ios

はい
{devices}

各デバイス/ユーザーに追加する識別子

  • 利用可能な識別子と必須の識別子の一覧は、上記の列と識別子を参照してください。
  • デバイスやユーザーに必要な識別子をいくつでもインポートすることができますが、それぞれに必要な識別子を提供する必要があります。
  • 1回のAPIコールで使用できる最大デバイス数は1万件です。
はい

APIを使って新しいオーディエンスをインポートする方法:

  1. インテグレーション > オーディエンスへ進みます。
  2. オーディエンスをインポートボタンをクリックしてください。
    新しいオーディエンス画面が開き、Define (定義) タブが表示されます。
  3. 一意のオーディエンス名を入力してください。
  4. オーディエンスのプラットフォームを選択してください:Android / iOS
  5. オーディエンスが標準オーディエンスか現状のままのオーディエンスかを指定してください。
    • 標準オーディエンスの場合は、ボックスにチェックを入れないでください。
    • 現状のままのオーディエンスの場合は、ボックスにチェックを入れてください。(注:このオプションはアドミンのみが利用できます。)
  6. オーディエンスを保存して続行をクリックしてください。
    インポートタブが表示されます。
  7. APIを使用してインポートセクションで、新しい端末/ユーザーを追加というデフォルトのままにしてください(新規オーディエンスのため)。
  8. APIリクエストURLをコピーしてください(APIトークンは既に含まれています)。
  9. APIリクエストBodyをコピーしてください。
  10. 次へをクリックします。
    Connect / 連携タブが表示されます。
  11. (オプション)オーディエンスをパートナーに接続する手順に従ってください。
  12. 完了をクリックしてください。
  13. ユーザー/デバイスの識別子を含むAPIリクエストを準備し、以下のサンプルのように、AppsFlyerにPOSTしてください。

APIを使用して既存オーディエンスを更新する方法:

  1. インテグレーション > オーディエンスへ進みます。

  2. アップロードしたいオーディエンス名をクリックしてください。
    オーディエンスの編集画面が開き、Define/定義タブが表示されます。

  3. オーディエンス名を編集したい場合は、ここで編集してください。それ以外の場合は、インポートタブを選択してください。

  4. APIを使用してインポートするセクションで、アップロードされたリストをどう処理するかを選択してください。
    • 新しい端末 / ユーザーを追加:既存オーディエンスにデバイス/ユーザーを追加します。
    • 既存オーディエンスからデバイス / ユーザーを削除:既存オーディエンスからデバイス/ユーザー識別子を削除します。
  5. APIリクエストURLをコピーしてください(APIトークンは既に含まれています)。
    • 重要!このオプションを変更すると、コピーされるコードのエンドポイントのパスが変更されます。今回のAPIリクエストおよび今後のAPIリクエストにおいて、実行するアクションに適したエンドポイントを必ず使用してください。
  6. APIリクエストBodyをコピーしてください。
  7. 次へをクリックします。
    Connect / 連携タブが表示されます。
  8. 必要に応じて、このオーディエンスのパートナー接続を変更してください。
  9. 完了をクリックしてください。
  10. ユーザー/デバイスの識別子を含むAPIリクエストを準備し、以下のサンプルのように、AppsFlyerにPOSTしてください。

デバイスを追加するリクエストのサンプル

HTTP POST 
https://hq1.appsflyer.com/audiences-import-api/v2/add?api_token=
Accept: application/json
Content-Type: application/json
body: {
     "import_key": "EKFH2UMC5PPCU8J7M5QQCBPKIH89E6NCOB7XQFWMC",
     "platform": "android", 
     "devices":[
      {0}
   ]
}
コード メッセージ 説明

200

The request was successful(リクエストは成功しました)

オーディエンスが正常にインポートされました。

400 Invalid audience platform, this audience is already configured for Android/iOS. To use a different platform, please create a new audience in the UI(オーディエンスのプラットフォームが無効です。このオーディエンスはすでにAndroid / iOS用に設定されています。別のプラットフォームを使用するには、UIにて新しいオーディエンスを作成してください) リクエスト本体で指定されたプラットフォームとオーディエンス作成のプラットフォームが一致していません。
400 X or more of your rows do not contain an app id.You must attach an app id to each row. (複数の行にアプリIDが含まれていません。App IDを各行に付ける必要があります)

オーディエンスが標準オーディエンスと指定されている場合、各行にapp_idを含める必要があります。

400 X or more of your rows does not contain a valid unique identifier (複数の行に有効な一意の識別子が含まれていません)

すべての行または一部の行に、以下の識別子のうち少なくとも1つが有効な形式で含まれていません。

  • Androidオーディエンス:gaidoiadimeicuidbraze_id または amplitude_id
  • iOSオーディエンス:idfvcuidbraze_id または amplitude_id
400 Cannot process more than Y devices per request (n devices counted in this request)(一つのリクエストにつきY以上のデバイスを処理できません (このリクエストには n 個のデバイスがふくまれています))

リクエストBodyに、1万件以上のデバイスIDリストが含まれています。

400 Device list cannot be empty(デバイスリストは空にできません)

リクエストBodyに空のデバイスリストが含まれています。

リクエストにつき最低1つのデバイスIDを提供する必要があります。

400 We couldn’t understand one or more of your device IDs(デバイスIDの識別ができません) すべてまたは一部のデバイスIDが有効なフォーマットではありません。

400

X or more of devices to remove contain more than one identifier per device(削除するデバイスのX個以上に、デバイスごとに複数の識別子が含まれています)

デバイスごとに複数の識別子を含む削除リクエストが送信されました

403 Forbidden(禁止されています) 許可されていないリクエスト:インポートキーが間違っているか、見つかりません。
500 Could not parse request(リクエストを解析できませんでした)

無効なリクエストBodyの形式です(指定された形式のJSONではないか、そもそもJSONではありません

上記のリクエストサンプルを参照してください。

レスポンスコード

APIに関する制限事項

  • 1つのリクエストにつき、1つのオーディエンスにのみデバイスを追加できます。
  • 1つのリクエストにつき、1つのオーディエンスからのみデバイスを削除できます。
  • 1つのリクエストにつき、最大1万件のデバイスIDを送信できます。
この記事は役に立ちましたか?