Master API — APIによるユーザー獲得メトリック

プレミアム機能

概要: 選択したLTV、アクティビティ、Protect360、およびリテンションなど、キャンペーンのパフォーマンスKPI をAPIでCSVまたはJSON 形式で取得します。アプリを1つ以上選択してください。

 重要:

  • このAPIのサポートは、2023年4月30日で終了し、Master API V2のみがサポートされている方法になります。
  • Master API V2は2023年2月9日に使用できるようになります。

Master API — APIによるユーザー獲得メトリック

  • 使用可能な KPI は、オーバービュー、アクティビティ、および Protect360 ダッシュボードにある同等の KPI です。
  • Master API を使用するには、表示するデータを定義するURI を作成します。これは、 Pull API の実装に似ています。結果は CSV または JSON ファイルとして返されます。
  • Master API:
    • AppsFlyerのピボットテーブル で構築されるインフラストラクチャです。
    • 代理店やパートナーはご利用いただけません。

Master APIの仕様

オーバービュー APIコールは、パス、ヘッダー、データクエリを含むJSONで構成されます。デフォルトでは、データはCSVファイルで出力されます。
パス https://hq.appsflyer.com/export/master_report/v4?
HTTPメソッド GET
データの更新頻度
  • Master API データはデイリーで計算されます。更新されたデータは、アプリ固有のタイムゾーンに応じて、24 ~ 48 時間以内に利用できます。
  • ここで説明するデータ更新頻度エンドポイントを使用して、すべてのデータの準備が整っているかどうかを確認します。一部のKPIは、他のKPIよりも早く更新されます。

データ更新頻度エンドポイント:

  • データ更新頻度のエンドポイントは、使用可能な最新のデータの日付を返します。形式は yyyy-mm-dd です(例 2019-12-31
  • 例:2020年1月2日に、2019年12月31日すべてのデータを取得する場合 -
    12月のMaster APIリクエストを送信する前に、データ更新頻度エンドポイントを照会して、2019年12月31日が使用可能であることを確認してください。つまり、エンドポイントは 2019-12-31 以上の値を返す必要があります。

https://hq1.appsflyer.com/master/lastupdate?api_token=[APIトークン]

Master APIの仕様

API パラメータ

https://hq.appsflyer.com/export/master_report/v4?api_token=api_token &app_id=app_id&from=yyyy-mm-dd&to=yyyy-mm-dd&groupings=groupings&kpis=kpis

コールパラメーター

パラメータ名

パラメータの値 必須?
api_token  AppsFlyerAdmin_us-en.png管理者はトークンを取得する必要があります。APIトークンを取得するには、 管理画面右上メールアドレス > APIトークンをクリックします。 はい 
app_id
  • AppsFlyerに表示されるアプリ識別子
  • AppsFlyerに表示されているとおりにアプリIDを挿入します。
  • iOSアプリの先頭にidを付与してください。
  • app_id=allを使用してすべてのアプリを照会します。
はい
from

LTVアトリビューション日付期間の下限。

  • 形式:文字列 yyyy-mm-dd
  • 例: from: 2020-01-02
はい 
活用  

LTVアトリビューション日付期間の上限。

  • 範囲内の日数:1~31日
  • 1日のみの場合fromto の値は同一になります。
  • 形式: yyyy-mm-dd
  • 例: from: 2021-01-01, to: 2021-01-31 =31日
必須
groupings

パラメーターでグループ化し、コンマで区切ります。使用可能なリストについては、グループ化の表を参照してください。

例:groupings=pid,geo

必須
KPI

含めるKPIのリスト(それぞれをコンマで区切って指定)KPIリストについては、以下の KPI表を参照してください。

例:kpis=installs,clicks, impressions,sessions,retention_day_7

必須
フィルター

データは、1つ以上のフィルターオプションを使用してフィルター処理できます。

いいえ
currency アプリ固有の通貨を設定するには currency=preferred とセットしてください。 いいえ
timezone

アプリ固有のタイムゾーンを使用してデータを返すには、timezone=preferred を設定します。参照:ローカリゼーションルール 

いいえ
形式

デフォルト設定で、レスポンスデータはすべてCSVファイル形式となります。JSONフォーマットでの受け取りを希望する場合は、&format=jsonをURLに追加ください。

いいえ

グループ化

これらのディメンションを使うことで、データをグループで表示し、情報をより簡単に、より正確に精査することが可能になります。詳細はこちらをご覧ください。

グループ化
API 名
表示名でグループ化 LTV KPI リテンションKPI アクティビティKPI Protect360 コホート

app_id

アプリID

はい

はい

はい

はい

はい

pid

メディアソース

はい

はい

はい

はい

はい

af_prt

代理店

はい

はい

はい

はい

いいえ

C

キャンペーン

はい

はい

はい

はい

はい

af_adset

Adset

はい

はい

はい

いいえ

いいえ

af_ad

広告

はい

はい

はい

いいえ

いいえ

af_channel

Channel

はい

はい

はい

はい

いいえ

af_siteid

パブリッシャーID

はい

はい

はい

はい

はい

af_keywords

Keywords

はい

はい

はい

いいえ

いいえ

is_primary

プライマリーアトリビューション

はい

いいえ

はい

はい

いいえ

af_c_id

Campaign ID

はい

いいえ

はい

はい

いいえ

af_adset_id

Adset ID

はい

いいえ

はい

いいえ

いいえ

af_ad_id

Ad ID

はい

いいえ

はい

いいえ

いいえ

install_time

インストール時間

はい

はい

はい*

はい

はい

attributed_touch_type

タッチタイプ

はい

はい

はい

はい

いいえ

はい

はい

はい

はい

はい

* アクティビティのコンテキストでは、KPIはインストール時間をイベント時間と見なします。

KPI

KPIはアプリの状況を確認するための指標となります。KPIは、以下のタブでタイプ別にグループ化されています。

LTVリテンションアクティビティコホートProtect360
生涯価値 - インストールされた日から本日までのイベント集計値
KPI API名 説明
インプレッション 選択した期間におけるインプレッション数
クリック 選択した期間におけるクリック数
インストール数 選択した期間におけるインストール数
cr コンバージョン率
sessions 選択した期間にインストールしたユーザーのセッション数
loyal_users 選択した期間にインストールしたロイヤルユーザー数
loyal_users_rate ロイヤルユーザー率(ロイヤルユーザー数 ÷ インストール数)
cost

選択した期間の総コスト
参照:制限事項

収益 選択した期間にインストールしたユーザーの生涯収益
ROI 選択した期間における投資対効果
arpu_ltv 選択した期間にインストールしたユーザーの1ユーザーあたりの平均収益
average_ecpi 特定の期間におけるeCPI
コストとインストールがコールに含まれている場合にのみ使用できます。
アンインストール 特定の期間にアンイストールしたユーザー
uninstalls_rate アンインストール率
event_counter_[event%20name]* イベントの発生数
unique_users_[event%20name]* イベントが発生したユニークユーザー数
sales_in_usd_[event%20name]* レポートされたイベントの収益
* イベント名は小文字にする必要があります。

算出KPI

Master APIレポートでは、上記のKPIに加え、算出KPIを追加することが可能です。これにより、独自の計算レポートをMaster API レポートに含めることができます。

KPI計算式の中には、いくつでもKPIを挿入いただいても構いません。

標準の算術演算子がサポートされています:%2bとしてエンコードされた加算(+)、減算(-)、乗算(*)、%2fとしてエンコードされた除算(/)。

計算式を挿入するKPIは、フィールド名は必ず 「calculated_kpi_」から始め、そのあとに有用な文字列で続けてください。例:calculated_kpi_purchaserate

 例

最初の3日間の合算リテンション

kpis=installs,loyal_users_rate&calculated_kpi_3days_retention=
retention_day_1%2Bretention_day_2%2Bretention_day_3

インプレッション毎の平均収益

kpis=installs&calculated_kpi_rev_per_impression=revenue%2Fimpression

コホート7日目のROI

kpis=installs,roi,arpu_ltv,cost,revenue&calculated_kpi_roi_day_7=
(cohort_day_7_total_revenue_per_user-average_ecpi)%2Faverage_ecpi

フィルター(オプション)

パラメータ名 説明 必須?

pid

メディアソースの絞り込みに利用します。カンマ区切りで複数指定可能です。

pid=organic,applovin_int

いいえ

C

キャンペーン名の絞り込みに利用します。カンマ区切りで複数指定可能です。

c=my_sample_campaign

いいえ

af_prt

代理店名の絞り込みに利用します。カンマ区切りで複数指定可能です。

af_prt=moburst

いいえ

af_channel

チャネル名の絞り込みに利用します。カンマ区切りで複数指定可能です。

af_channel=Instagram

いいえ

af_siteid

パブリッシャーIDの絞り込みに利用します。カンマ区切りで複数指定可能です。

af_siteid=12345678

いいえ

国の絞り込みに利用します。カンマ区切りで複数指定可能です。

geo=US,DE

いいえ

時間枠の項目

次の時間粒度オプションを使用できます:デイリー

時間枠項目の ToFrom を仕様して、選択した時間範囲で必要な粒度を決定してください。

 例

  • 日単位の粒度: 次のような日付範囲を選択します。 From=2017-08-15&to=2017-08-17 

ローカライゼーション

現地通貨とアプリ固有のタイムゾーンは、 アプリ設定ページから設定します。Master APIのデータは、システムの既定の通貨とタイムゾーン、またはアプリ固有のタイムゾーンと通貨を使用してデータを抽出できます。

以下が適用されます:

  • アプリ固有のタイムゾーン/通貨の使用は、すべてのアプリが同じタイムゾーン/通貨を持つ場合にのみサポートされます。それ以外の場合は、UTC と USD が使用されます。タイムゾーンと通貨は別々です。つまり、すべてのアプリの通貨が同じでタイムゾーンが同じでない場合は、アプリ固有の通貨を使用できますが、アプリ固有のタイムゾーンは使用できません。
  • リクエストされた時間範囲内にダッシュボードでリクエストされたタイムゾーンが変更された場合、生成されたレポートには、最新のタイムゾーンの変更から始まる値が含まれます。

次のパラメーターを使用して、アプリ固有の設定を選択します。注意:preferredパラメーターを使用しない場合は、通貨の場合は USD、タイムゾーンの場合は UTCという既定の設定が適用されます。

パラメータ名 説明 必須?

currency

金額はアプリ設定画面で設定された通貨です。

currency=preferred

いいえ

timezone

使用されるタイムゾーンは、アプリ設定画面で設定されたタイムゾーンに従います。

timezone=preferred

いいえ

タイムゾーンに対応してレポートが表示されるためには、timezone=preferredパラメーターは必ず使用する必要があります。

コール例

Master APIで利用できるURLを用意しました。コピーペーストでご活用ください。
URLを使う前に以下の点をお気をつけください:

  • アプリ名 com.greatapp をアプリIDのアプリ名に置き換えます。
  • [api_token] を 御社アカウントのAPIトークンに置き換えてください。
  • 開始日付と終了日付を必要な日付範囲に置き換えてください。
  • 要件に応じて KPIを変更してください。
  • アプリ固有のタイムゾーンと通貨を使用して、次のものやクエリURLを使用してレポートを取得できます。
    &timezone=preferred &currency=preferred
精巧なFacebookレポート

Facebook広告のパフォーマンスを比較する:

https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp&from=[from_date]&to=[to_date]&pid=facebook
&groupings=pid,c,af_adset_id,af_ad_id
&kpis=installs,clicks,impressions,sessions,loyal_users,cost,revenue,arpu_ltv,roi
精巧なGoogle広告レポート
Google 広告のパフォーマンスを比較する:
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp,id123456789&from=[from_date]&to=[to_date]&pid=googleadwords_int
&groupings=pid,c,af_adset_id,af_ad_id
&kpis=installs,sessions,loyal_users,cost,revenue,arpu_ltv,roi
国別レポート
例:アカウントに紐づくすべてのアプリのUSとカナダのみのデータを抽出 -
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=all&from=[from_date]&to=[to_date]&groupings=geo,pid,c&kpis=
installs,clicks,impressions,sessions,loyal_users,cost,revenue,arpu_ltv,
roi&geo=us,ca	
キーワード有効性レポート
インストールするために利用したキーワード毎にROIやそのほかのK`PIを比較できます。
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp&from=[from_date]&to=[to_date]&groupings=af_keywords
&kpis=roi,arpu_ltv,average_ecpi,installs,loyal_users_rate,cost,revenue
代理店パフォーマンスレポート
利用しているすべての代理店のパフォーマンスを比較できます。
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp,id123456789&from=[from_date]&to=[to_date]&groupings=af_prt,pid,c&kpis=installs,
loyal_users_rate
アフィリエイトパフォーマンスレポート
どのアフィリエイトからのインストールが一番質が高いかをメディアソース 'affiliates' から探すことが可能です。
(アフィリエイトのインストール計測についての詳細はこちら
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp&from=[from_date]&to=[to_date]&groupings=af_siteid&pid=affiliates
&kpis=installs,loyal_users_rate,arpu_ltv,retention_day_1,retention_rate_day_1,
retention_day_7,retention_rate_day_7,retention_day_15,retention_rate_day_15,
retention_day_30,retention_rate_day_30
アトリビューションタイプレポート
クリック、インプレッション、オーガニック、どのユーザーが一番価値あるかを確認できます。
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp,id123456789&from=[from_date]&to=[to_date]&groupings=attributed_touch_type
&kpis=installs,sessions,loyal_users_rate,arpu_ltv
ネットワーク別リテンションレポート
すべてのアプリのアプリインストール1日後、7日後、15日後、22日後、30日後のリテンションをすべてのメディアソースで比較できます。
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=all&from=[from_date]&to=[to_date]&groupings=pid,c
&kpis=installs,loyal_users_rate,retention_day_1,retention_rate_day_1,
retention_day_7,retention_rate_day_7,retention_day_15,retention_rate_day_15,
retention_day_22,retention_rate_day_22,retention_day_30,retention_rate_day_30

制限事項とトラブルシューティング

制限事項

  • コストデータ
    • さまざまなコストディメンションが利用可能であることから、広告セット、広告、地域、チャンネル、サイトIDは 広告ネットワークによって異なります
    • eCPIを取得するには:コストデータが利用可能な場合は、インストールとコストの両方をコールに含めます。
    • 基本的に、オウンドメディアを含むAppsFlyerのURLを使う全てのメディアソースで、リクエストするディメンションに関わらずコストデータが提供可能です。ただし、URLにコストパラメータが存在する必要があります。独自のAPIをもつセルフレポーティングネットワークは一部のディメンションのコストデータのみに対応しています。
      たとえば、 Facebook は同じコールでGeoとChannelによるグループ化をサポートしていません。これらのいずれかによる個別のグループ化がサポートされています。
    • コストデータはあるが、最近のインストールデータがないキャンペーン(約7日間)はマスターAPIではご利用いただけません。
  • グループ化:特定のグループ化は、LTV KPI、アクティビティ、またはリテンションKPI でのみ使用できます。特定のKPIが利用不可の場合、”N/A” とAPIから返答されます。例えば、retention_rate_day_7 を af_channel でグループするようにリクエストをすると、“N/A” と返します。
  • レポートあたりの最大行数: 20万行
  • イベント名: Master API は現在、スラッシュ / を含むイベント名をサポートしていません。この制限を克服するには、イベント名のユーザー / を避けます。
  • 処理時間:複数のアプリを選択すると、処理時間が長くなり、応答に時間がかかることがあります。

トラブルシューティング

 

メッセージ

備考

200 OK  
  • 症状:ファイルが返されない
  • トークンが送信されていません
401 Unauthorized The Supplied API Token is Invalid
  • サーバーがリクエストを認証できませんでした。APIトークンが見つからないか、または無効です。
  • URLに正しいAPIトークンが含まれていることを確認してください。APIトークンは、api_tokenパラメーターで渡されます。
404 Not found
  • ネットワークに問題があります
  • Master APIのご利用契約がありません
416 No Groupings Selected
  • Master APIは集計データを提供します。どのKPIを元にデータを集計するか指定いただく必要があります。
  • ご希望のグルーピンググルーピング パラメーターにてご指定ください。
403 Unrecognized date format. 日付を確認して修正してください。
403 From date can't be after To date.
(from の日付は to の日付より後に設定できません)
日付を確認して修正してください。
403 From and To dates must have the same granularity format.
(From と To の日付は同じ粒度形式にする必要があります。)
日付を確認して修正してください。
403 No KPIs provided.(KPIが指定されていません。)  
403 One or more of the formula's operators are not supported when not Unicode.
(数式の 1つ以上の演算子は、Unicode でない場合、サポートされません。)
 
403 No calculated KPI name provided.
(計算されたKPI名が指定されていません。)
 
416 Something went wrong(不具合が発生しました)Please re-try to download in a minute, choose a narrower time range, or contact AppsFlyer support.
(1分後に再試行するか、より狭い時間範囲を選択するか、AppsFlyerサポートにお問い合わせください。)
  • 日付形式が yyyy-mm-dd に準拠していることを確認してください。
  • KPIタイプがコホートの場合は、コホート日の範囲が 1 ~ 90 であることを確認します。
    コホート 0日目はサポートされていません。
416 The requested time range is in UTC only (prior to the timezone change)
(リクエストされた時刻範囲はUTCのみ(タイムゾーン変更前)です。)
 
403 Not authorized app-ids: <app_id>
(アプリID <app_id> は承認されていません。)
 
  • このエラーは管理画面に登録していないアプリに関するリクエストを送信した場合に表示されます。
  • app_id パラメータのアプリIDが正しいことを確認してください。
  • アンドロイドの場合は、package IDがアプリIDになります。

    iOSの場合は、 bundle IDではなくApp IDがアプリIDとなります。

416 Please select authorized app-id
(承認されたアプリIDを選択してください)
 
416 No Groupings Selected  
416 間違ったAPIフィールド

項目が存在しないか、許可されていません。

416 Other reason(その他の理由)

レポートのサイズが 200Kを超えています。