マスターAPI - カスタマイズ可能な集計データAPI

  • 広告主
  • 開発者

はじめに

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は、以下のタブでタイプ別にグループ化されています。

LTVリテンションアクティビティコホートProtect360
生涯価値 - インストールされた日から本日までのイベント集計値
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] レポートされたイベントの収益

 警告

イベント名は大文字小文字を区別します。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. 期間選択

マスターAPIはいづれかの単位を選択できます:
  • 日単位
  • 週単位
期間フィールドの To(いつから)From(いつまで)を使用してご希望の範囲の期間指定ができます。KPIは指定した期間に応じて日単位または週単位で表示されます。

 重要:

日単位または週単位のいづれかを選択した場合、指定した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を使う前に以下の点をお気をつけください。

  1. アプリの名前を「com.greatapp」からご自身のアンドロイドまたはiOSのアプリIDに変更ください。
  2. [TOKEN]の箇所をご自身のアカウントのAPIトークンをご入力ください。
  3. ご希望の期間に変更ください(from_date, to_dateの箇所を変更)
  4. ご希望に応じて、KPIを変更ください。
  5. アプリがデフォルト設定(UTC±00:00 とUSD)とは異なる場合は、 &timezone=preferred&currency=preferredをクエリーURLに追加ください。
精巧な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
リターゲティングユーザー有効性レポート
ユーザー獲得とリターゲティング、どちらのキャンペーンタイプがより収益をだしているかを比較できます。
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
ネットワークリテンションレポート
すべてのアプリのアプリインストール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

制限事項

コストデータ

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が正しいことを確認してください。

 注意

アンドロイドの場合は、package IDがアプリIDになります。

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

KPIが未指定

エラーメッセージ

Request id: <request_id>.[Error] No kpis provided

エラーコード

403

説明

マスターAPIは集計データを提供します。どのKPIを元にデータを集計するか指定いただく必要があります。

解決法

ご希望のKPIKPIパラメータとしてご指定ください。

間違ったAPIフィールド

エラーメッセージ

Wrong API Fields: <api_field>

エラーコード

416

説明

1つまたは複数のAPIフィールドに誤りがあります。APIフィールドはkpis またはgroupings パラメーターにてご指定いただけます。

解決法

正しいAPIフィールド名を指定するようにしてください。利用可能なKPIまたはGroupingsのフィールドをご確認ください。

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
この記事は役に立ちましたか?
1人中1人がこの記事が役に立ったと言っています