はじめに
AppsFlyerのカスタマイズ可能な集計データAPIは、ご希望のグルーピング及びKPIを指定して、カスタムレポートを作成できます。生涯価値 (LTV)、リテンション、コホート、アクティビティ、Protect360 に関するそれぞれのKPIを、1つのアプリまたは複数のアプリまとめて、レポートにすることができます。
こちらはAppsFlyerのプレミアム機能になります。
注意
マスターAPIは代理店やパートナーの方はご利用できません。
また、表示したいデータに応じてグループをそれぞれ定義することが可能です。
APIを利用するためには、見たいデータを含むURLを作成します。AppsFlyerのプルAPIと同様に、CSVファイルで結果を返します。
マスターAPIはAppsFlyerのピボットテーブルの元となる機能となります。AppsFlyerのプレミアム機能として、セットでご利用する形となります。
マスターAPIの構造
マスターAPIのURLは必須部分とオプショナルの部分に分かれます。詳細は下記を参照ください。 マスターAPIのベースエンドポイント、必須パラメーター、グルーピング、KPI、計算後KPI、フィルター、期間、そしてローカライゼーションに関する値が含まれます。
1.マスターAPIのベースエンドポイント
マスターAPIへの通信はすべて下記のエンドポイントから始まる必要があります。
https://hq.appsflyer.com/export/master_report/v4?
マスターAPIのURLに含める可変パラメーターはすべて'?' の文字に続けて入力します。
2. 必須パラメーター
マスターAPIのURLの基本フォーマットは以下の通りとなります。
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=[app_id]&from=[from_date]&to=[to_date]&groupings=[list]&kpis=[list]
重要:
- KPI、グルーピング、そしてそのほかのパラメータはすべて小文字で設定をお願いします。
- すべてのアカウントはアカウント登録時にAPI Keyが生成されます。アカウントオーナー(アドミ権限者)が変更になった場合は、API Keyもリセットされます。もしアカウントオーナーが変更になった場合は、,Master API URL内のAPI keyを新しいものに 忘れ図に変更ください。
下表は必須のパラメーターとなります。
パラメータ名 | 説明 | 例 | 必須? |
---|---|---|---|
api_token |
お客様のアカウントを特定するためのAPIアクセス用トークンとなります。管理画面の APIアクセス ページ でご確認いただけます |
123510e9-1111-2222-3333-123bd8eeca9f |
はい |
from |
開始日 |
2016-08-02, 2017-w23 |
はい |
活用 |
終了日 |
2016-08-08, 2017-w24 |
はい |
app_id |
レポートに含めるアプリのアプリID。カンマで分けて入力またはすべての場合は"all"と入力します。 |
app_id=app_id1,app_id2 app_id=all |
はい |
groupings |
カンマで分けます。選択したクエリに対して、パラメーター毎のグループを表示します。 |
groupings=pid,geo |
はい |
KPI |
カンマで分けて入力。下記参照。 |
kpis=installs,clicks, impressions,sessions,retention_day_7 |
はい |
3. 利用可能なグルーピング
これらのディメンションを使うことで、データをグループで表示し、情報をより簡単に、より正確に精査することが可能になります。詳細はこちらをご覧ください。
ディメンション | 表示名 | 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 |
タッチタイプ |
はい |
はい |
はい |
はい |
いいえ |
国 |
国 |
はい |
はい |
はい |
はい |
はい |
4. KPI
KPIはアプリの状況を確認するための指標となります。KPIは、以下のタブでタイプ別にグループ化されています。
KPI | 説明 |
---|---|
インプレッション | 選択した期間におけるインプレッション数 |
クリック | 選択した期間におけるクリック数 |
インストール数 | 選択した期間におけるインストール数 |
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 | 説明 |
---|---|
retention_day_[x] | X日後のアクティブユーザー数 |
retention_rate_day_[x] | インストールしたユーザーのうち、X日後のアクティブユーザー数 |
retention_week_[x] | X週間後のアクティブユーザー数 |
retention_rate_week_[x] | インストールしたユーザーのうち、X週間後のアクティブユーザー数 |
KPI | 説明 |
---|---|
activity_average_dau | 選択した期間における平均DAU |
activity_average_mau | 選択した期間における平均MAU(1MAU日:過去30日におけるユニークユーザー数) |
activity_average_dau_mau_rate | 平均DAU/MAU率 |
activity_average_arpdau | 1DAUあたりの平均収益:その1日のすべてのユニークユーザーあたりの平均収益 |
activity_sessions | 選択した期間におけるセッション数 |
activity_revenue | 選択した期間における収益 |
activity_event_counter_[event%20name] | 選択した期間におけるユーザーによるイベント数 |
activity_sales_in_usd_[event%20name] | 選択した期間における収益イベントからの収益 |
activity_average_unique_users_[event%20name] |
選択した期間における特定のイベントを実施した平均ユニークユーザー数 |
AppsFlyerのコホートレポートでは、異なる期間の複数のコホートレポートを異なる指標を使って比較することが可能です。
セッション
KPI | 説明 |
---|---|
cohort_day_[x]_total_sessions_per_user | コホート X日:X日目までのユーザー毎の累積セッション数(X日目を含む) |
cohort_day_[x]_sessions_per_user | コホート X日:X日目のみのセッション数 |
cohort_[x]_days_total_sessions_per_user |
X日目までのセッション数を日別で取得できます。 例えば、URLでcohort_3_days_total_sessions_per_userと指定するとレポートに以下の3列を生成します: |
収益
KPI | 説明 |
---|---|
cohort_day_[x]_total_revenue_per_user | コホートX日: ユーザーあたりの累積収益 (X日目を含む) |
cohort_day_[x]_revenue_per_user | コホートX日:X日目のみのARPU |
cohort_[x]_days_total_revenue_per_user |
X日目までのユーザーあたりの総収益を日別で取得できます。 例えば、URLでcohort_3_days_total_revenue_per_userを指定するとレポートでは以下の3列を生成します: |
cohort_day_[x]_total_event_[eventname]_revenue_per_user |
特定のアプリ内イベントにおけるコホートX日目のユーザーあたりの累積収益 |
cohort_day_[x]_event_[eventname]_revenue_per_user | コホートX日の特定のアプリ内イベントにおけるユーザーあたりの収益 |
イベント
KPI | 説明 |
---|---|
cohort_day_[x]_total_event_[eventname]_per_user | コホートX日:X日目までのユーザーあたりの累積イベント数 (X日目を含む) |
cohort_day_[x]_event_[eventname]_per_user | コホートX日:X日目のみのイベント数 |
cohort_[x]_days_total_event_[eventname]_per_user |
X日目までのユーザーあたりの総イベント数を日別で取得できます。 例えば、URLでcohort_3_days_total_events_per_user と指定すると、レポートでは以下の3つの列を生成します。: |
KPI | 説明 |
---|---|
protect360_total_installs | 非オーガニックインストールの総数 |
blocked_installs | デバイスランク、CTIT、インストールバリデーション及びサイトIDブラックリストにより、ブロックした総インストール数 |
blocked_installs_rate | インストールブロック率 |
blocked_installs_device_rank | デバイスランクによりブロックしたインストール数 |
blocked_installs_validation | バリデーションルールによりブロックしたインストール数 |
blocked_installs_siteid_blacklist | サイトIDブラックリストによりブロックしたインストール数 |
blocked_installs_ctit_anomalies | CTIT異常によりブロックしたインストール数 |
blocked_installs_bots | ボットからのブロックしたインストール数 |
blocked_installs_click_flood | クリック洪水からブロックしたインストール数 |
blocked_installs_hijacking | ハイジャックからブロックしたインストール数 |
protect360_total_clicks | 総クリック数 |
blocked_clicks | ブロックしたクリック数 |
blocked_clicks_rate | ブロックしたクリック率 |
protect360_total_in_apps | 非オーガニックアプリ内イベントの合計数 |
blocked_in-app-events | ブロックしたアプリ内イベント数 |
blocked_in-app-events_rate | ブロックしたアプリ内イベント率 |
install_fraud_new_devices_installs | 新規端末のインストール数 |
install_fraud_new_devices_installs_rate | 新規端末のインストール率 |
install_fraud_new_devices_loyal_user_rate | 新規端末のロイヤルユーザー率 |
install_fraud_lat_devices_installs | LAT端末のインストール数 |
install_fraud_lat_devices_install_rate | LAT端末のインストール率 |
install_fraud_lat_devices_loyal_user_rate | LAT端末のロイヤルユーザー率 |
install_fraud_suspicious_devices_installs | 不審な端末のインストール数 |
install_fraud_suspicious_devices_install_rate | 不審な端末のインストール率 |
install_fraud_suspicious_devices_loyal_user_rate | 不審な端末のロイヤルユーザー率 |
install_fraud_clean_device_installs | クリーンデバイスのインストール数 |
install_fraud_clean_device_install_rate | クリーンデバイスのインストール率 |
install_fraud_clean_device_loyal_user_rate | クリーンデバイスのロイヤルユーザー率 |
click_flood_under_5_min_rate | クリック洪水:CTITが5分未満の比率 |
click_flood_from_5_to_60_min_rate | クリック洪水:CTITが5分以上60分未満の比率 |
click_flood_over_60_min_rate | クリック洪水:CTITが60分以上の比率 |
contribution_rate | 貢献率 |
install_hijacking_up_to_10_sec_rate | インストールハイジャック:10秒未満 |
install_hijacking_10_to_30_sec_rate | インストールハイジャック:10秒以上30秒未満 |
install_hijacking_over_30_sec_rate | インストールハイジャック:30秒以上 |
警告
イベント名は大文字小文字を区別します。AppsFlyerに送っているイベント名と必ず同一のイベント名の使用をお願いします。
5. 計算後KPI
マスターAPIレポートでは、上記のKPIに加え、計算後KPIを追加することが可能です。この方法により、自動的に必要なKPIをマスター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
6. フィルター
パラメータ名 | 説明 | 例 | 必須? |
---|---|---|---|
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 |
いいえ |
7. 期間選択
- 日単位
- 週単位
重要:
日単位または週単位のいづれかを選択した場合、指定したKPIがそれに対応するものであることを確認してください。詳細についてはこちらをご確認ください。
例
日別レポートを希望する場合は、From=2017-08-15&to=2017-08-17
、週単位レポートを希望する場合は、From=2017-w04&to=2017-w12
のように指定ください。
8.ローカライゼーション
管理画面のアプリ設定画面にて、ご希望の通貨及びタイムゾーンを設定できます。以下のパラメーターを利用することで、同じ設定をマスターAPIレポートに反映することができます。
パラメータ名 | 説明 | 例 | 必須? |
---|---|---|---|
currency |
通貨関連のレポートはすべてアドミ権限者が設定した通貨にて表示されます。 |
currency=preferred |
いいえ |
timezone |
アドミ権限者が設定したアプリのタイムゾーンに応じてレポートが生成されます。 |
timezone=preferred |
いいえ |
- デフォルトの設定のままかどうかに関わらず、もしすべてのアプリが同じ設定の場合は、その設定が使用されます。アプリ毎に設定が異なる場合は、UTC±00:00 とUSDが使用されます。
- ローカライゼーション(タイムゾーンと通貨の設定)は週単位のリテンションKPIには対応していません。
- 選択した期間中に、管理画面でタイムゾーン設定を変更した場合、生成されたレポートには変更した時点以降のデータしか含まれません。
注意
タイムゾーンに対応してレポートが表示されるためには、timezone=preferredパラメーターは必ず使用する必要があります。
レスポンスフォーマット
レスポンスはすべてV5フォーマットとなります。
デフォルト設定で、レスポンスデータはすべてCSVファイル形式となります。JSONフォーマットでの受け取りを希望する場合は、&format=json
をURLに追加ください。
リクエストサンプル
マスターAPIで利用できるURLを用意しました。コピーペーストでぜひご活用ください。URLを使う前に以下の点をお気をつけください。
- アプリの名前を「com.greatapp」からご自身のアンドロイドまたはiOSのアプリIDに変更ください。
- [TOKEN]の箇所をご自身のアカウントのAPIトークンをご入力ください。
- ご希望の期間に変更ください(from_date, to_dateの箇所を変更)
- ご希望に応じて、KPIを変更ください。
- アプリがデフォルト設定(UTC±00:00 とUSD)とは異なる場合は、
&timezone=preferred
と¤cy=preferred
をクエリーURLに追加ください。
出稿しているすべての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
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
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
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
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
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp&from=[from_date]&to=[to_date]&groupings=is_primary&kpis=revenue
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
制限事項
コストデータ
eCPIを含むコストデータは、常に利用可能とは限りません。ネットワークがコストデータを提供できるかどうかは、ネットワークの種類によります。例えば、AppsFlyerのリンクなのかセルフレポーティングなのか、またどのディメンションを利用したいのか、などによります。
基本的に、オウンドメディアを含むAppsFlyerのURLを使う全てのメディアソースで、リクエストするディメンションに関わらずコストデータが提供可能です。ただし、URLにコストパラメータが存在する必要があります。独自のAPIをもつセルフレポーティングネットワークは一部のディメンションのコストデータのみに対応しています。
例えば、FacebookはGeoとChannelで同時にグループ化することができません。(どちらか1つのみであれば可能です)
コストデータ連携が可能なアドネットワークの全リストをご覧になりたい場合は こちらをご確認ください。
重要!
- 特定のグルーピングはLTV、アクティビティ、リテンションのKPIでのみ利用可能です。特定のKPIが利用不可の場合、”N/A”とAPIから返答されます。例えば、「retention_rate_day_7」を「af_channel」でグループするようにリクエストをすると、“N/A”と返します。
- データ鮮度: データは 1日単位で集計されます。データが反映されるまでの時間は、UTCマイナスのタイムゾーンの場合は最大で48時間、UTCプラスのタイムゾーンの場合は24時間要する可能性がございます。
- 最大行数:200K
トラブルシューティング
このセクションではよくあるマスターAPIのエラーと対処方法を解説します。
指定されたAPIトークンが無効
エラーメッセージ
The Supplied API Token is Invalid
エラーコード
401
説明
サーバーがリクエストを認証できませんでした。APIトークンが見つからないか、または無効です。
解決法
URLに正しいAPIトークンが含まれていることを確認してください。APIトークンは、api_token
パラメーターで渡されます。
不正なアプリID
エラーメッセージ
Request id: <request_id>.Not authorized app-ids: <app_id>
エラーコード
416
説明
このエラーは管理画面に登録していないアプリに関するリクエストを送信した場合に表示されます。
解決法
app_id
パラメータのアプリIDが正しいことを確認してください。
KPIが未指定
エラーメッセージ
Request id: <request_id>.[Error] No kpis provided
エラーコード
403
説明
マスターAPIは集計データを提供します。どのKPIを元にデータを集計するか指定いただく必要があります。
解決法
ご希望のKPI をKPI
パラメータとしてご指定ください。
間違ったAPIフィールド
No Groupings Selected
エラーメッセージ
No Groupings Selected
エラーコード
416
説明
マスターAPIは集計データを提供します。どのKPIを元にデータを集計するか指定いただく必要があります。
解決法
ご希望のグルーピング をグルーピング
パラメーターにてご指定ください。
週別と日別データ
エラーコード
403
説明
週別データを取得する際は、日付を指定することはできません。逆の場合も同様です。
解決法
週別データの場合は週を指定:
https://hq1.appsflyer.com/master/v4?api_token=<API_TOKEN>&from=2019-w4&to=2019-w4&groupings=geo,pid&kpis=installs,retention_week_2&app_id=com.sample.app
日別データの場合は日付を指定:
https://hq1.appsflyer.com/master/v4?api_token=<API_TOKEN>&from=2019-08-01&to=2019-08-04&groupings=geo,pid&kpis=installs,retention_day_2&app_id=com.sample.app