Adjust KPIサービス
Adjust KPIサービスはAdjustのPull APIで、計測したいモバイルアプリの統計をプログラム上でリクエストすることができます。このサービスを可能にするRESTful JSON APIについて以下に説明します。

APIに発行できるクエリは、概要イベントコホートの3種類です。これらは、Adjust管理画面の所定のセクションと対応して、関連するKPIを直接引き出すことができます。

各クエリはアプリに設定したネットワークトラッカー、または所定の親トラッカーのいずれにも実行できます。したがって、各リソースには2つのエンドポイントがあります。1つは全ネットワークトラッカーのデータをデフォルトでグループ化するトラッカートークン無しのエンドポイント、そしてもう1つは、トラッカートークンを特定して、指定のサブトラッカーグループまで掘り下げて確定するエンドポイントです。

APIの仕様に進む前に、このAPIを補完するためにAdjustが構築したRクライアントについて確認することをお勧めします。もしもすでにRを使っている場合は、このクライアントでAdjustのデータをRセッションに取り込む際の便利さがおわかりかと思います。

トラッカーの概念はAPIデータの理解に不可欠ですので、トラッカーの関連用語について確認しておくことをおすすめします。特に、ネットワーク、キャンペーン、アドグループ、クリエイティブといったコンポーネントのトラッカーの階層構造の概念について把握ください。

注記: KPIサービスは、Business Proプラン以上のお客様にご利用いただけます。管理画面から現在ご利用の価格パッケージをご確認ください。

注:以下のページでは、最小長のトラッカートークンを使用しています。Adjust キャンペーンウィザードに表示されたトラッカートークン全体を必ず使用してください。

バージョニング

APIバージョンの主なリリース。混乱を避けるため、APIバージョンは全エンドポイントのURLパスに明記されています。例えば、http://api.adjust.com/kpis/v1/..では、バージョン1にアクセスすることになります。

レスポンスのフォーマット

APIでは2つのレスポンスフォーマット、CSVとJSONに対応しており、JSONがデフォルトとなっています。異なるフォーマットを特定するには、それに応じたエンドポイントを末尾に付けるか (例: .csv をエンドポイントパスの最後に追加する) または、 Accept: text/csv HTTP ヘッダーをリクエストと共に送信してください。このドキュメントでは、リクエストとレスポンスの例には主にJSONを使用しています。

認証

KPIサービスへのアクセスはAdjustユーザーアカウントに関連付けられます。各ユーザーアカウントには関連のユーザートークンがあり、これによりKPIへのアクセスを個別にコントロールすることができます。

ユーザートークンを取得するには、管理画面の マイアカウント(Account Settins) > あなたのデータ(Your Data)の順にクリックしてアクセスしてください。以下の認証に関する説明に記載されているユーザートークンとは、このことを意味します。

各ユーザートークンには管理画面ユーザーと同じ制限があります。カスタムユーザーの許可設定を設定した場合、KPIサービスを通したアクセスには管理画面のアクセスと同じルールが適用されます。

ユーザートークンはいつでも更新することができます。

ユーザートークンを使ってAPIに対して認証を行うには以下の2つのオプションがあります。そのユースケースに応じて希望のオプションを選んでください。

  • HTTP GETパラメータとして。 - 任意のAPIクエリに user_token=your_user_token を加える。
  • HTTP認証ヘッダーとして。 - 以下のHTTPヘッダーを追加する:`Authorization: Token token=your_user_token`

このドキュメントの例はすべてHTTPヘッダー認証を前提としていますが、正しいトークンでGETパラメータを簡単に例に追加することもでき、その場合も有効となります。

アプリトークンとトラッカートークン

混乱を避けるためにも明記しますが、ここで記載のエンドポイント全てにおいて、:app_tokenおよび:tracker_tokenの部分は実際のトークン値に置き換えられて、有効なリクエストURL を取得できるようになります。例えば以下のとおりです。

https://api.adjust.com/kpis/v1/2eb2na2w54c3/trackers/15jvui

上記のURLの場合、アプリトークン2eb2na2w54c3およびトラッカートークン15jvuiの有効なURLとなります。このドキュメント内のすべての例において、アプリトークン2eb2na2w54c3が使われていますので、これをご自身のアプリトークンと置き換えてください。

概要クエリ

概要クエリはアプリKPIイベントKPIのデータ提供を行います。大抵の場合、アプリが実行している全ネットワークまたは特定のトラッカーに対する一定期間のメトリック (クリック数や、セッション数インストール数など) に興味がある方が多いと思います。また、収益first_events (初回イベント数) などのカスタムAdjustイベントに対してKPIをリクエストすることもできます。さらにオプションで、プラットフォームデバイスのスコープを適用することもできます。

エンドポイント

GET https://api.adjust.com/kpis/v1/:app_token{.csv|.json} 
GET https://api.adjust.com/kpis/v1/:app_token/trackers/:tracker_token{.csv|.json}

クエリパラメータ

対応クエリパラメータの一覧:予想パラメータ値に関する詳細もご覧ください。

 
パラメータ名形式説明
start_dateYYYY-MM-DD選択期間の開始日
end_dateYYYY-MM-DD選択期間の終了日
utc_offset[+-]HH:MM、例:utc_offset=-05:00またはutc_offset=10:00タイムゾーンのUTCオフセット
KPI文字列、例:clicks,installs,mausコンマで区切られたアプリKPIのリスト。アプリKPIのどのような組み合わせでも可。
event_kpis文字列、例:token1_events,token1_revenue_per_userコンマで区切られたイベントKPIのリスト。各KPIはイベントトークン1つまたはallでプレフィックスが指定されている必要があります。下記の例を参照してください。
reattributed文字列truefalse、または allインストールまたはリアトリビュートされたユーザー別、または全ユーザー(デフォルト)でKPIをフィルタリング
sandbox文字列trueまたはfalseサンドボックスまたはプロダクションデータ向けにリクエストを発行することができます。デフォルトではプロダクションが想定されます。
impression_based文字列trueまたはfalseリクエストは、クリックまたはインプレッションベースのビューとして発行されます。デフォルトでは、クリックベースが想定されます。
attribution_type文字列clickimpression、またはallクリックまたはインプレッションのいずれか、またはクリックとインプレッションの組み合わせ(これはimpression_basedパラメータを上書きします)
attribution_source文字列、 first またはdynamicアプリ内アクティビティがユーザーのインストールソース(first)に割り当てられられるか、あるいはインストールソースとその後のリアトリビューションのソース(dynamic)の間で分割されるかを決定します。デフォルトの設定はdynamicとなっています。
countries文字列、例:de,usコンマで区切られたISO 3166 alpha-2の国名のリスト。
os_names文字列、例:ios,androidコンマで区切られたOS名のリスト。有効なOS名を以下で確認してください。
device_types文字列、例:phone,tabletコンマで区切られた端末タイプのリスト。有効な端末タイプを以下で確認してください。
grouping文字列、例:trackers,countriesパラメータをグループ化。グループ化についての詳細は下記を参照してください。


アプリKPI

対応のアプリKPI(kpisパラメータに値としてパスすることのできるもの)の一覧表 
アプリKPI説明
clicksクリック数
impressionsインプレッション数
installsインストール数
uninstallsアンインストール数
uninstall_cohort(アンインストールコホート)指定した期間にインストールしたユーザーのアンインストール数
reinstalls再インストール数
click_conversion_rate(コンバージョン率 (クリック数の割合))クリックコンバージョン率(installs/clicksの平均。clicksにより加重)
CTRクリックスルー率(clicks/impressionsimpressionsにより加重)
impression_conversion_rate(コンバージョン率 (インプレッション数の割合))インプレッションコンバージョン率(installs/impressionsの平均。impressionsにより加重)
リアトリビューションリアトリビューション数
Reattribution_reinstalls (リアトリビューション再インストール)リアトリビューションにも繋がった再インストール数
deattributionsディアトリビューション数
sessionsセッション数
revenue_events(収益イベント数)収益イベント数
revenue (収益)合計収益(アプリのレポート通貨単位)
cohort_revenue(収益コホート)選択した期間内に(リ)アトリビュートされたユーザーから発生した合計収益
daus1日あたりの平均アクティブユーザー数
waus1週間あたりの平均アクティブユーザー数
maus1か月あたりの平均アクティブユーザー数
limit_ad_tracking_installs(LATインストール)「追跡型広告を制限」が有効になっているデバイスからのインストール数
limit_ad_tracking_install_rate(LAT率)「追跡型広告を制限」が有効になっているデバイスからのインストール数の割合: limit_ad_tracking_installs/installs
limit_ad_tracking_reattributions(LATリアトリビューション)「追跡型広告を制限」が有効になっているデバイスからのリアトリビューション数
limit_ad_tracking_reattribution_rate(LATリアトリビューション率)「追跡型広告を制限」が有効になっているデバイスからのインストール数の割合: limit_ad_tracking_reattributions/reattributions
GDPR Forgets忘れられる権利を行使したユーザーの合計数。Adjustは、これらのユーザーすべての個人データの履歴を完全に削除しますが、管理画面のレポートに使用される累計データは保持します。忘れられる権利を行使後は、ユーザーのデバイスのデータはAdjustに送信されず、Adjust管理画面にも表示されません。


不正KPI

不正なKPIはAdjustのアドフラウド防止機能が有効になっているアカウントでのみ利用可能です。
 
不正なKPI説明
rejected_installs(不正インストール)拒否されたインストールの数。rejected_installs_anon_ip + rejected_installs_too_many_engagements + rejected_installs_distribution_outlier + rejected_installs_click_injectionの合計
rejected_installs_anon_ip(匿名IPにより拒否されたインストール、RI AIP)匿名IPにより拒否されたインストールの数
rejected_installs_too_many_engagements(エンゲージメント過多により拒否されたインストール、RI TME)エンゲージメント過多により拒否されたインストールの数
rejected_installs_distribution_outlier(ディストリビューション異常値により拒否されたインストール、RI DO)ディストリビューション異常値により拒否されたインストールの数
rejected_installs_click_injection(クリックインジェクションにより拒否されたインストール、RI CI)エンゲージメントインジェクションにより拒否されたインストールの数
rejected_installs_invalid_signature(SDKシグネチャーによって拒否されたインストール、RI SDK シグネチャー)SDKシグネチャーが不足または無効なために拒否されたインストールの数
rejected_reattributions(不正リアトリビューション)拒否されたリアトリビューションの数。rejected_reattributions_anon_ip + rejected_reattributions_too_many_engagements + rejected_reattributions_distribution_outlier + rejected_reattributions_click_injectionの合計
rejected_reattributions_anon_ip(匿名IPにより拒否されたリアトリビューション、RR AIP)匿名IPにより拒否されたリアトリビューションの数
rejected_reattributions_too_many_engagements(エンゲージメント過多により拒否されたリアトリビューション、RR TME)エンゲージメント過多により拒否されたリアトリビューションの数
rejected_reattributions_distribution_outlier(ディストリビューション異常値により拒否されたリアトリビューション、RR DO)ディストリビューション異常値により拒否されたリアトリビューションの数
rejected_reattributions_click_injection(クリックインジェクションにより拒否されたリアトリビューション、RR CI)エンゲージメントインジェクションにより拒否されたリアトリビューションの数
rejected_install_rate(不正インストール率)拒否されたインストールの比率:rejected_installs/(installs + rejected_installs)
rejected_install_anon_ip_rate(匿名IPにより拒否されたインストール率)匿名IPにより拒否されたインストールの比率:rejected_installs_anon_ip/(installs + rejected_installs)
rejected_install_too_many_engagements_rate(エンゲージメント過多により拒否されたインストール率)エンゲージメント過多により拒否されたインストールの比率:rejected_installs_too_many_engagements/(installs + rejected_installs)
rejected_install_distribution_outlier_rate(ディストリビューション異常値により拒否されたインストール率)ディストリビューション異常値により拒否されたインストールの比率:rejected_installs_distribution_outlier/(installs + rejected_installs)
rejected_install_click_injection_rate(クリックインジェクションにより拒否されたインストール率)エンゲージメントインジェクションにより拒否されたインストールの比率:rejected_installs_click_injection/(installs + rejected_installs)
rejected_reattribution_rate(拒否されたリアトリビューション率)拒否されたリアトリビューションの比率:rejected_reattributions/(reattributions + rejected_reattributions)
rejected_reattribution_anon_ip_rate(匿名IPにより拒否されたリアトリビューション率)匿名IPにより拒否されたリアトリビューションの比率:rejected_reattributions_anon_ip/(reattributions + rejected_reattributions)
rejected_reattribution_too_many_engagements_rate(エンゲージメント過多により拒否されたリアトリビューション率)エンゲージメント過多により拒否されたリアトリビューションの比率:rejected_reattributions_too_many_engagements/(reattributions + rejected_reattributions)
rejected_reattribution_distribution_outlier_rate(ディストリビューション異常値により拒否されたリアトリビューション率)ディストリビューション異常値により拒否されたリアトリビューションの比率:rejected_reattributions_distribution_outlier/(reattributions + rejected_reattributions)
rejected_reattribution_click_injection_rate(クリックインジェクションにより拒否されたリアトリビューション率)エンゲージメントインジェクションにより拒否されたリアトリビューションの比率:rejected_reattributions_click_injection/(reattributions + rejected_reattributions)


コストKPI

コストKPIはコストデータが有効になっているアカウントでのみ利用可能です。
 
コストKPI説明
install_cost(インストールコスト)インストールコスト
click_cost(クリックコスト)クリックコスト
impression_cost(インプレッションコスト)インプレッションコスト
costclick_cost + impression_cost + install_costの合計
paid_installs(インストール(有料))コストデータのあるインストールの数
paid_clicks(クリック(有料))コストデータのあるクリックの数
paid_impressions(インプレッション(有料))コストデータのあるインプレッションの数
eCPC有効クリック単価、例:cost / paid_clicks
eCPM広告1000回表示あたりの有効費用、例:cost / paid_impressions * 1000
eCPI有効インストール単価、例:cost / paid_installs
cohort_gross_profit(粗利益)売上総利益、例:cohort_revenue - cost
return_on_investment(投資利益率)ROIメトリックの算出、例:cohort_gross_profit / cost
revenue_to_cost収益と売上の比率の算出、例:cohort_revenue / cost
注: コストはミリセント単位で算出されます(例:5.45661ユーロの場合、コスト=545661)。
 

イベントKPI

対応のイベントKPI(概要リクエストでevent_kpisパラメータに値としてevent_token付きでパスすることのできるもの)の一覧表イベントのセクションで説明のとおり、これらのイベントKPIはEventsリクエストでも使われます。
 
イベントKPI説明
revenue_events(収益イベント数)収益イベント数
revenue (収益)アプリのレポート通貨単位での合計収益
eventsイベント数
first_events(初回イベント数)ユーザーによって初めてトリガーされたイベント数。eventsfirst_eventsとの関係はsessionsに対するinstallsの関係と同様です。
revenue_per_event(1イベントあたりの収益)イベント数で割った合計収益
revenue_per_revenue_event(1収益イベントあたりの収益)収益イベント数で割った合計収益


イベントKPIリクエストの円滑化

この項目は、event_kpiを概要リクエストでリクエストする予定の場合のみ該当します。これ以外の場合は、読み飛ばしてもかまいません。

event_kpisを個別に特定すると、非常に長いパラメータになってしまう場合があります。event_kpisの有効な値としては以下のような例があります。

event_kpis=token1_events,token2_events,token1_revenue,token2_revenue

このため、ショートカットにも対応しています。以下の文字列:

event_kpis=token1_revenue|events|revenue_per_event

は、以下に相当します。

event_kpis=token1_revenue,token1_events,token1_revenue_per_event

さらに、特別キーワードallを使ってすべての定義済みイベントに拡張することもできます。例えば、 token1token2というトークンのあるイベントが2つあったとします。その場合の値:

event_kpis=all_revenue|events|revenue_per_event

は、以下に相当します。

event_kpis=token1_revenue,token1_events,token1_revenue_per_event,token2_revenue,token2_events,token2_revenue_per_event

最後に、以下の文字列:

event_kpis=all_revenue,all_events,all_revenue_per_event

は、以下に相当します。

event_kpis=token1_revenue,token2_revenue,token1_events,token2_events,token1_revenue_per_event,token2_revenue_per_event

最後の2つのフォーマットはメトリックの順序によって違いが出ていることにご留意ください。この点については以下でさらに詳しく説明しています。


アプリKPIのみをリクエスト

リクエスト: 

GET http://api.adjust.com/kpis/v1/2eb2na2w54c3?start_date=2015-05-01&end_date=2015-05-31&kpis=sessions,installs&countries=de,gb

レスポンス:

{
  "result_parameters": {
    "kpis": ["sessions", "installs"],
    "start_date": "2015-05-01",
    "end_date": "2015-05-31",
    "sandbox": false,
    "countries": ["de", "gb"],
    "trackers": [
      {
        "token": "foobar",
        "name": "Network 1",
        "has_subtrackers": true
      },
      {
        "token": "15jvui",
        "name": "Network 2",
        "has_subtrackers": true
      }
    ],
    "grouping": ["trackers"]
  },
  "result_set": {
    "token": "2eb2na2w54c3",
    "name": "app name",
    "currency": "USD",
    "trackers": [
      {
        "token": "foobar",
        "kpi_values": [100, 299]
      },
      {
        "token": "15jvui",
        "kpi_values": [557, 880]
      }
    ]
  }
}

result_parameters内のkpis配列とresult_set内のkpi_values配列がそれぞれ対応していることに着目してください。例えば、このレスポンス内のトラッカーNetwork 1には100のsessionsと299のinstallsが確認できます。


アプリKPIとイベントKPIのリクエスト

kpisパラメータに加え、event_kpisパラメータを使ってイベントKPIをリクエストすることもできます。

リクエスト:

GET http://api.adjust.com/kpis/v1/2eb2na2w54c3?start_date=2015-05-01&end_date=2015-05-31&kpis=clicks&event_kpis=token1_events,token1_revenue&countries=de,gb

レスポンス:

{
  "result_parameters": {
    "kpis": ["clicks", "token1_events", "token1_revenue"],
    "start_date": "2015-05-01",
    "end_date": "2015-05-31",
    "sandbox": false,
    "countries": ["de", "gb"],
    "trackers": [
      {
        "token": "foobar",
        "name": "Network 1",
        "has_subtrackers": true
      },
      {
        "token": "15jvui",
        "name": "Network 2",
        "has_subtrackers": true
      }
    ],
    "events":[
      {
        "name": "YourEventName",
        "token": "token1"
      }
    ],
    "grouping": ["trackers"]
  },
  "result_set": {
    "token": "2eb2na2w54c3",
    "name": "app name",
    "currency": "USD",
    "trackers": [
      {
        "token": "foobar",
        "kpi_values": [221, 100, 299.30]
      },
      {
        "token": "15jvui",
        "kpi_values": [1005, 557, 880.75]
      }
    ]
  }
}
 

result_parameters内のkpis配列とresult_set内のkpi_values配列がそれぞれ対応していることに着目してください。このレスポンスのトラッカーNetwork 1のクリック数は221で、トークンtoken1でのイベント発生回数は100、そしてこれらのイベントからの収益は299.30となっています。


KPIの順序

kpisおよび/またはevent_kpisをリクエストする順序により、受け取るレスポンスの順序が決定します。上記後者のレスポンス例がこれをよく表しています。

KPIの順序はAPIからcsvデータをリクエストする時に特に役立ちます。この場合、レスポンスの列はKPIをリクエストした方法と完全に一致します。


イベントクエリ

この項目では、イベントKPIクエリについて説明します。これらのエンドポイントはイベント別にデータをグループ化したい場合に役立ちます。


エンドポイント

GET https://api.adjust.com/kpis/v1/:app_token/events{.csv|.json} 
GET https://api.adjust.com/kpis/v1/:app_token/trackers/:tracker_token/events{.csv|.json}


クエリパラメータ

対応クエリパラメータの一覧:予想パラメータ値に関する詳細もご覧ください。
 

パラメータ名形式説明
start_dateYYYY-MM-DD選択期間の開始日
end_dateYYYY-MM-DD選択期間の終了日
utc_offset&[+-]HH:MM、例:utc_offset=-05:00またはutc_offset=10:00タイムゾーンのUTCオフセット
KPI文字列、例:revenue_events,revenueコンマで区切られたイベントKPIのリスト。イベントKPIのどのような組み合わせでも可。
sandbox文字列 trueまたはfalseサンドボックスまたはプロダクションデータ向けにリクエストを発行することができます。デフォルトではプロダクションが想定されます。
events文字列、例:event_token1,event_token2コンマで区切られたイベントトークンのリスト。イベントのイベントトークンはAdjust管理画面で見つかります。
attribution_type文字列clickimpression、またはallクリックまたはインプレッションのいずれか、またはクリックとインプレッションの組み合わせ(これはimpression_basedパラメータを上書きします)
attribution_source文字列、firstまたはdynamicアプリ内アクティビティがユーザーのインストールソース(first)に割り当てられられるか、あるいはインストールソースとその後のリアトリビューションのソース(dynamic)の間で分割されるかを決定します。デフォルトの設定はdynamicとなっています。
countries文字列、例:de,usコンマで区切られたISO 3166 alpha-2の国名のリスト
os_names文字列、例:ios,androidコンマで区切られたOS名のリスト。有効なOS名を以下で確認してください。
device_types文字列、例:phone,tabletコンマで区切られた端末タイプのリスト。有効な端末タイプを以下で確認してください。
partner_ids整数、例:1234,789コンマで区切られたパートナーIDのリスト。これらのパートナーに属するトラッカーからのデータのみが表示されます。
grouping文字列、例:trackers,countriesパラメータをグループ化。グループ化についての詳細は下記を参照してください。


イベントKPI

イベントKPIのリストは上記と同じままです。ただし、Overviewクエリと違い、EventsのリクエストではイベントKPIの前にイベントトークンをプレフィックスとして追加する必要はありません。特定のイベントのデータが必要な場合は、イベントパラメータを使ってイベントトークンを提供します。


リクエスト:

GET http://api.adjust.com/kpis/v1/2eb2na2w54c3/events?start_date=2015-05-01&end_date=2015-05-31&kpis=revenue,events,revenue_per_event&grouping=trackers,weeks,events&countries=de,gb

レスポンス:

{
  "result_parameters": {
    "kpis": ["revenue", "events", "revenue_per_event"],
    "start_date": "2015-05-01",
    "end_date": "2015-05-31",
    "sandbox": false,
    "countries": ["de", "gb"],
    "events": [{"token": "abcdef","name": "Login"}, {"token": "badcfe","name": "Level Up"}],
    "grouping": ["trackers", "weeks", "events"],
    "trackers": [
      {
        "token": "foobar",
        "name": "Network 1",
        "has_subtrackers": true
      }
    ]
  },
  "result_set": {
    "token": "2eb2na2w54c3",
    "name": "app name",
    "currency": "USD",
    "trackers": [
      {
        "token": "foobar",
        "dates": [
          {
            "date": "2015-05-02",
            "events": [
              {
                "token": "abcdef",
                "kpi_values": [4, 5, 0.8]
              },
              {
                "token": "badcfe",
                "kpi_values": [3, 5, 7.2]
              }
            ]
          },
          {
            "date": "2015-05-09",
            "events": [
              {
                "token": "badcfe",
                "kpi_values": [4, 5, 0.8]
              }
            ]
          }
        ]
      }
    ]
  }
}

result_parameters内のkpis配列とresult_set内のkpi_values配列がそれぞれに相対していることに注意してください。このレスポンスでは、イベント「ログイン」が0.8のrevenue_per_eventで5回記録されています。


コホートクエリ

コホートクエリを使うことで、ユーザーがインストール、購入または登録した日付など、ユーザーコホートによって集計されたデータをクエリすることができます。インストール後の日別の継続率など、コホートベースのKPIを取得することが可能になります。

コホートは、コホート期間別とKPIベースで表示されます。コホート期間はデータのセグメンテーションの深さを表し、週ごとのコホート(例:特定の日、週、月にインストールしたユーザーなど)とその期間をベースにしたKPI(例:日、週、月別の継続率)を表示します。KPIベースでは、全てのユーザー、課金したユーザー(収益イベントを最低1つトリガーしたユーザー)、そして任意イベントをトリガーしたユーザーの中から、ユーザーサブセットが定義されます。

2019年5月1日現在、当社が提供するコホートクエリのサポートは120日から52週間までです。cohort_period_filterプレースホルダを使用して、特定の日や一定期間の日数にわたって(またはその両方)、あるいは特定の週や一定期間の週数にわたって、コホートクエリを行うことができます。

特定の日(インストール後30日目など)のクエリを行うには、フォーマット cohort_period_filter=30を使用します。一定期間の日数(インストール後30日間など)のクエリを行うには、フォーマット cohort_period_filter=0-30を使用します。

特定の日と一定期間の日数(インストール後30日間と120日目)のクエリを両方同時に行うには、フォーマット cohort_period_filter=0-30,120を使用します。

特定の週(インストール後10週目など)のクエリを行うには、フォーマット cohort_period_filter=10&period=weekを使用します。

一定期間の週数(インストール後最初の10週間)のクエリを行うには、フォーマットcohort_period_filter=0-10&period=weekを使用します。


エンドポイント

GET /kpis/v1/:app_token/cohorts{.csv|.json} 
GET /kpis/v1/:app_token/trackers/:tracker_token/cohorts{.csv|.json}


クエリパラメータ

対応クエリパラメータの一覧:予想パラメータ値に関する詳細もご覧ください。
 

パラメータ名形式説明
start_dateYYYY-MM-DD選択期間の開始日
end_dateYYYY-MM-DD選択期間の終了日
utc_offset[+-]HH:MM、例:utc_offset=-05:00またはutc_offset=10:00タイムゾーンのUTCオフセット
KPI文字列、例:revenue_events,revenueコンマで区切られたアプリKPIのリスト。アプリKPIのどのような組み合わせでも可。
sandbox文字列 trueまたはfalseサンドボックスまたはプロダクションデータ向けにリクエストを発行することができます。デフォルトではプロダクションが想定されます。
attribution_type文字列clickimpression、またはallクリックまたはインプレッションのいずれか、またはクリックとインプレッションの組み合わせ(これはimpression_basedパラメータを上書きします)
attribution_source文字列、 firstまたはdynamicアプリ内アクティビティがユーザーのインストールソース(first)に割り当てられられるか、あるいはインストールソースとその後のリアトリビューションのソース(dynamic)の間で分割されるかを決定します。デフォルトの設定はdynamicとなっています。
periodday/week/monthのいずれかコホート期間
reattributedtrue/false/allのいずれかコホートがリアトリビューションベースかどうか(true または false)を管理。デフォルト値のallにはリアトリビューションとインストールの両方が含まれます。利用可能なデータ:2016年10月1日以降
events文字列、例:abcdef,12345コンマで区切られたイベントトークンのリスト
countries文字列、例:de,usコンマで区切られたISO 3166 alpha-2の国名のリスト
os_names文字列、例:ios,androidコンマで区切られたOS名のリスト。有効なOS名を以下で確認してください。
device_types文字列、例:phone,tabletコンマで区切られた端末タイプのリスト。有効な端末タイプを以下で確認してください。
grouping文字列、例:trackers,install_dateパラメータをグループ化。グループ化についての詳細は下記を参照してください。

注: periodクエリパラメータに使われる期間は、暦日ではなく、インストール後の時間で測定されています。例えば、ユーザーが水曜日の12:47にインストールした場合、そのユーザーにとっての第0週は、翌週の水曜日の12:47(168時間後)に終了することになり、第0月は30日後の12:47(720時間後)に終了することになります。


コホートKPI

コホートKPI説明
retained_users(継続しているユーザー数)期間内に戻ってきたユーザー数
cohort_size(コホートサイズ)N-番目のperiod-after-installで、少なくともN期間前にインストールしたユーザー数
retention_rate(リテンション率)retained_users を cohort_sizeで割った値
リアトリビューション期間ごとのリアトリビュート済みユーザー数
deattributions期間ごとのディアトリビュート済みユーザー数(例:インストールトラッカーから離れてリアトリビュートされた場合)
sessions期間ごとの生成セッション数
sessions_per_user(ユーザー当たりのセッション数)セッション数を retained_usersで割った値
uninstalls期間ごとのアンインストール数
uninstalls_total(アンインストール合計)全期間でのアンインストール数
reinstalls期間ごとの再インストール数
reinstalls_total(再インストール合計)全期間での再インストール数
revenue (収益)期間ごとの収益額
revenue_total(収益の合計)この期間とそれまでの全期間の累計収益
revenue_per_user(ユーザー当たりの収益)revenue を cohort_sizeで割った値
revenue_per_paying_user(有料ユーザー当たりの収益)revenue を paying_user_sizeで割った値
revenue_total_in_cohort(コホートにおける収益の合計)N-番目のperiod-after-installで、0からNまでの全期間中、少なくともN期間前にインストールしたユーザーからの累計収益
lifetime_value(ユーザーのLTV)revenue_total_in_cohortを cohort_sizeで割った値
paying_user_lifetime_value(有料ユーザーのLTV)revenue_total_in_cohortを paying_user_sizeで割った値
time_spent(アプリ内の経過時間)期間内のユーザー滞在時間の合計(秒)
time_spent_per_user(ユーザー当たりのアプリ内の経過時間)time_spent を cohort_sizeで割った値
time_spent_per_session(ユーザー当たりのアプリ内の経過時間)time_spent を sessions で割った値*
paying_users(課金したユーザー数)期間内の課金したユーザー数
paying_user_size(課金したユーザーサイズ)N-番目のperiod-after-installで、少なくともN期間前にインストールし課金したユーザー数
paying_users_retention_rate(有料ユーザーのリテンション率)paying_users を retained_usersで割った値
paying_user_rate(課金ユーザー率)paying_users を cohort_sizeで割った値
revenue_events(収益イベント数)期間ごとの収益イベント数
revenue_events_total_in_cohort(コホート内における収入イベント数合計)N-番目のperiod-after-installで、0からNまでの全期間中、少なくともN期間前にインストールしたユーザーからの累計revenue_events数
revenue_events_per_user(ユーザー当たりの収入イベント数)revenue_events を cohort_sizeで割った値
revenue_events_per_active_user(アクティブユーザー当たりの収入イベント数)revenue_events を retained_usersで割った値
revenue_events_per_paying_user(有料ユーザー当たりの収入イベント数)revenue_events を paying_usersで割った値
converted_users(コンバージョンしたユーザー数)N-番目のperiod-after-installで、特定のイベント(複数可)をトリガーしたユニークユーザー数1人のユーザーが複数のdays-after-installに貢献している場合もあります。
converted_user_size(コンバージョンしたユーザーサイズ)N-番目のperiod-after-installで、少なくともN期間前にインストールしたCVのユーザー数
conversion_distribution(コンバージョンディストリビューション)converted_users を converted_user_sizeで割った値
conversion_per_user(ユーザー当たりのコンバージョン)converted_users を cohort_sizeで割った値
conversion_per_active_user(アクティブユーザー当たりのコンバージョン)converted_users を retained_usersで割った値
events期間内にトリガーされたイベント数
events_per_converted_user(コンバージョンしたユーザー当たりのイベント数)events を converted_usersで割った値
events_per_user(ユーザー当たりのイベント数)events を cohort_sizeで割った値
events_per_active_user(アクティブユーザー当たりのイベント数)events を retained_usersで割った値

*第0日、第0週、第0月のコホート計算では、インストールセッションを必ず差し引くことを忘れずに。


リクエスト:

GET http://api.adjust.com/kpis/v1/2eb2na2w54c3/cohorts?start_date=2015-05-01&end_date=2015-05-31&kpis=sessions&grouping=trackers,periods&period=week

レスポンス:

{
  "result_parameters": {
    "kpis": ["sessions"],
    "start_date": "2015-05-01",
    "end_date": "2015-05-31",
    "sandbox": false,
    "grouping": ["trackers", "periods"],
    "trackers": [
      {
        "token": "foobar",
        "name": "Network 1",
        "has_subtrackers": true
      }
    ],
    "period": "week"
  },
  "result_set": {
    "token": "{your_user_token}",
    "name": "app name",
    "currency": "USD",
    "trackers": [
      {
        "token": "foobar",
        "periods": [
          {
            "period": "0",
            "kpi_values": [4]
          },
          {
            "period": "1",
            "kpi_values": [5]
          }
        ]
      }
    ]
  }
}

ここでも kpiskpi_valuesの対応に着目してください。


クエリパラメータ

この項目では、上記の各APIリクエストパラメータの詳細が記載されています。APIでは見つかったエラーについての説明が含まれ、リクエストパラメータが解析されていることに注意してください。無効なリクエストにはHTTP 400エラー応答が返され、本文内に問題の詳細が記載されます。


期間

日付範囲をフィルタするにはstart_dateend_dateYYYY-MM-DDのフォーマットで指定します。指定がない場合は、デフォルトの日付範囲として当月が適用されます。


タイムゾーン

utc_offsetがUTCに対するタイムゾーンを決定するために使われます。例えば、太平洋標準時ゾーン(PT)の2016年2月14日に発生したインストール数を見たい場合には、 start_date=2016-02-14&end_date=2016-02-14&utc_offset=-08:00をクエリに追加します。何も指定がない場合は、UTCが適用されます。フォーマットはutc_offset=[+-]HH:MM(例:utc_offset=+04:00)ですが、+はデフォルトのオフセット方向なので省略しても構いません。ただし-は必ず含める必要があります。


リアトリビューション

reattributedクエリパラメータを使って、KPIをリアトリビューション済みユーザーのみにフィルタリングすることができます。リアトリビューションは既にアプリをインストール済みのユーザーが新しいAdjust計測のソースを通して戻ってきた場合を意味します。

注:このクエリは2017年9月1日以降開始の時間枠からのみデータを取得することができます。

このフィルタをWAUMAU KPIと組み合わせて使う場合は、以下の点にご留意ください。
  • ユーザーを同時にインストール済みユーザーとリアトリビューション済みユーザーとすることはできません
    • 例えば、ユーザーが6月1日月曜日にインストールして6月3日水曜日にリアトリビュートされた場合、6月7日日曜日まではインストール済みWAUユーザーとなりますが、6月8日月曜日と9日火曜日のみについてはリアトリビューション済みWAUユーザーとなります。
      • ユーザーが新しいアプリセッションを6月9日以降にトリガーした場合、7日間につきリアトリビューション済みQAUユーザーとして返されることになります。
  • MAUにも同じ論理が適用されますが、月別の時間枠となります。


KPI

kpisでは、各リソースで異なる(可能性のある)リクエスト済みKPIが、コンマで区切られたリスト形式で指定されます。パラメータが指定されていない場合は、デフォルトのリストが想定されます。result_setでもkpisの配列が返されますので注意してください。


countriesでは2文字のISO 3166-1 alpha-2 国コードがコンマで区切られたリスト形式で指定されます。countryフィルタが指定されていない場合は、all-countries(全ての国)が想定されます。


OS名

有効なos_name値のリスト
android
bada
blackberry
ios
linux
macos
server
symbian
unknown
webos
windows
windows-phone


デバイスタイプ

有効なdevice_types値のリスト
bot
console
ipod
mac
pc
phone
server
simulator
tablet
tv
unknown


読み取り可能なKPI

特にCSVのデータを扱う際に有用な機能として多くのクライアントにご利用いただいているのがhuman_readable_kpisです。GETパラメータhuman_readable_kpis=trueを任意のリクエストURLに追加すると、KPIや期間などのヘッドラインが適切にフォーマットされた英語に翻訳されます。例えば、lifetime_valueの代わりにLifetime Value(生涯価値)が返されます。さらに、periodの代わりに、レスポンスフィールドはWeeks after Installを読み取り、コホートクエリでの選択期間がweekであると仮定します。

これにより、列やヘッドラインの名前を変更する必要なく、CSV APIコールからの結果をレポートとして共有しやすくなります。同時に、自動APIアクセスの命名の一貫性とデータのプログラムによる解析をサポートできるようになります。


グルーピング

groupingにより、データセットのグループ化が指定されます。その結果、データは指定された通りの順序でネストされます。例:grouping=trackers,countriesではデータが国別に各トラッカーごとにネストされ、grouping=countries,trackersはその反対の順序でネストします。ぜひグルーピングパラメータを色々と試してみてください。

groupingリクエストパラメータの受け入れ可能な値すべてを以下にリストアップしています。


トラッカー関連のグルーピング

トラッカーグルーピングにより、トラッカーツリーに沿ってトラッカー別にデータを分類することができます。以下でいくつかの例を見てみましょう。
  • 親トラッカーとgrouping=trackersが指定されていない場合、データはアプリの全てのネットワークトラッカーでグループ化されます。
  • 親トラッカーとgrouping=campaignsが指定されていない場合、データはアプリの全てのキャンペーントラッカーでグループ化されます。
  • キャンペーン親トラッカーとgrouping=trackersまたはgrouping=adgroupsが指定されている場合、データは指定のキャンペーン親からの全てのアドグループトラッカーでグループ化されます。
  • キャンペーン親トラッカーとgrouping=creativesが指定されている場合、データは指定のキャンペーン親からの全てのクリエイティブトラッカーでグループ化されます。
受け入れ可能な値の全リスト:
  • trackers:オプションのtracker_tokenによってネットワーク別/キャンペーン別/アドグループ別/クリエイティブ別にグループ化。トラッカーのグルーピングについてはトラッカーツリーのセクションをご覧ください。
  • networks:オプションのtracker_tokenに関わらずネットワーク別にグループ化。結果のセットには見つかったネットワークのデータ配列を示すネットワークフィールドが含まれます。
  • campaigns:オプションのtracker_tokenに関わらずネットワーク別にグループ化。結果のセットには見つかったキャンペーンのデータ配列を示すキャンペーンフィールドが含まれます。
  • adgroups:オプションのtracker_tokenに関わらずネットワーク別にグループ化。結果のセットには見つかったアドグループのデータ配列を示すアドグループフィールドが含まれます。
  • creatives:オプションのtracker_tokenに関わらずネットワーク別にグループ化。結果のセットには見つかったクリエイティブのデータ配列を示すクリエイティブフィールドが含まれます。
 

期間のグルーピング

  • hour:時間別にグループ化します。結果セットにはその期間の適用時間のデータ配列を示すdatesフィールドが含まれます。ここでは対応する date フィールドに時間が表示されます。
  • day:日にち別にグループ化します。結果セットにはその期間の適用日のデータ配列を示すdatesフィールドが含まれます。ここでは対応するdate フィールドに日にちが表示されます。
  • week:週別にグループ化します。結果セットには適用週のデータ配列を示すdatesフィールドが含まれます。ここでは対応するdate フィールドにその週の1日目が表示されます。
  • month:月別にグループ化します。結果セットには適用月のデータ配列を示すdatesフィールドが含まれます。ここでは対応するdate フィールドにその月の1日目が表示されます。
注:より長い日付グルーピング(週や月)を使う場合は、日付選択にその全体の期間を含めることをお勧めします。最初の日付はその週または月の開始日に繰り上げられます。日付選択が週または月の途中から始まる場合のグループは、結果セットで他のグループと正しく比較できない場合があります。


その他のグルーピングオプション

  • countries:国別にグループ化します。結果セットには見つかった国のデータ配列を示すcountriesフィールドが含まれます。ここでは対応するcountry フィールドに2文字の(ISO 3166-1 alpha-2)国コードが表示されます。国コードの一覧は、以下の表をご参照ください。
  • region:ビジネス地域別にグループ化します。例:APAC、EMEA、LATAMなど。結果には見つかった地域のデータ配列を示すregionフィールドが含まれます。ここでは対応するregion フィールドに地域の頭字語が表示されます。属する国や地域の全リストを見るには、こちらをクリックしてください。
  • device_types:端末タイプ別にグループ化します。結果には見つかった地域のデータ配列を示すdevice_typesフィールドが含まれます。ここでは対応するdevice_type フィールドに端末のタイプ(上記device_typesセクションに一覧記載)が表示されます。
  • os_names:OS名別にグループ化します。結果セットには見つかったos_namesのデータ配列を示すos_namesフィールドが含まれます。ここでは対応するos_names フィールドに端末のオペレーティングシステムが表示されます。
  • partners:パートナー名別にグループ化します。結果セットには見つかったパートナーのデータ配列を示すpartnersフィールドが含まれます。ここでは対応するpartners フィールドにそのデータが属するパートナーが表示されます。


トラッカーツリー

前述のとおり、すべてのエンドポイントは、トラッカートークン指定の有無にかかわらずリクエストできます。上記の各リソースに対して2つのエンドポイントが指定され、2番目のフォームではトラッカーが指定されます。2番目のフォームを使う場合、結果セットは指定のトラッカーでフィルタされ、trackersグルーピングにより、結果セットがサブトラッカー別にセグメント化されます。

トラッカートークンが指定されないと、各ネットワークのデータが返され、trackersグルーピングにより、結果セットがネットワークレベルトラッカー別にtrackers配列のエントリーとしてセグメント化されます。

trackersグルーピングでは、結果セットに各トラッカーのメタデータが含まれます。このメタデータにはhas_subtrackersブーリアンフィールドが含まれ、ツリーをさらに詳しく探索するため指定のトークンをクエリすることもできます。

例えば、キャンペーン親トラッカーでクエリをリクエストした場合、レスポンスには各アドグループのサブトラッカー別にグループ化されたデータが含まれます。


トラッカーのフィルタリング

トラッカーのフィルタリングは複雑なトラッカーの設定を処理する上で便利です。KPIサービスクエリと共にtracker_filterのクエリパラメータを使うことで、結果セットを特定のトラッカーからのデータにフォーカスすることができます。これとAPI提供のグルーピングオプションを組み合わせることで、特定のネットワーク、キャンペーン、またはアドグループに焦点を置きながら、データをより掘り下げて調査するためのパワフルな機能を作り上げることができます。

例えばAdjustトラッカー設定に、x2yiy3vi4wwcという2つのネットワークトラッカートークンがあるとします。クエリパラメータを使うことで、結果セットをこの2つのネットワークに所属するデータ、またはこれらから発生したデータのみを含むように絞り込むことができます。
 
&tracker_filter=x2yiy3,vi4wwc&grouping=network,campaign,adgroup,creative

注:groupingパラメータは任意です。どんなgroupingでも(または一切ない場合も)リサーチ目標に応じて有意義な結果を提供してくれます。

さらに、トラッカーのフィルタリングはマルチアプリオーバービューのエンドポイントと組み合わせて使うことができます。以下がその例です。
 
GET https://api.adjust.com/kpis/v1?app_tokens=44cdcdck2syc,9xmtsnp687ek&tracker_filter=q9y2y2,xi2wxq,x2yiy3,vi4wwc&grouping=app,network,campaign,adgroup,creative

こうすることで、例えば1つのAPIコールで複数のアプリの同じネットワークでのパフォーマンスを比較することが可能になります。


マルチアプリオーバービューのエンドポイント

これまでに説明したエンドポイントは1つのアプリのデータのみをリクエストするものです。これらは個々のアプリの内訳を完全に把握するのに不可欠なエンドポイントではありますが、Adjustで計測する複数(またはすべて)のアプリの概要は提供されません。全体的な概要を得るには、この項目で説明するマルチアプリのエンドポイントが必要になります。


エンドポイントURL

コール可能な合計レポートには2つの異なるエンドポイントがあります。
GET https://api.adjust.com/kpis/v1{.csv|.json}?app_tokens=44cdcdck2syc,9xmtsnp687ek 
GET https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek{.csv|.json}?

どちらのエンドポイントも返される結果は同じです。

コホートに関しては、以下のエンドポイントを使う必要があります。
https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek/cohorts{.csv|.json}?

注:他のエンドポイントと同様に、.csv や.json の拡張子は必須ではありません。デフォルトのレスポンスフォーマットはここでもJSONですが、CSVに変更しなければならない場合、必要なのは .csv拡張子の追加だけです。
 
パラメータ名形式説明
start_dateYYYY-MM-DD選択期間の開始日
end_dateYYYY-MM-DD選択期間の終了日
utc_offset[+-]HH:MM、例:utc_offset=-05:00 または utc_offset=10:00タイムゾーンのUTCオフセット
KPI文字列、例:clicks,installs,mausコンマで区切られたアプリKPIのリスト。アプリKPIのどのような組み合わせでも可。
sandbox文字列 true または falseサンドボックスまたはプロダクションデータ向けにリクエストを発行することができます。デフォルトではプロダクションが想定されます。
impression_based文字列 true または falseリクエストは、クリックまたはインプレッションベースのビューとして発行されます。デフォルトでは、クリックベースが想定されます。
countries文字列、例: de,usコンマで区切られた ISO 3166 alpha-2の国名のリスト。
os_names文字列、例: ios,androidコンマで区切られたOS名のリスト。 OS名 のリストが適用されます。
device_types文字列、例: phone,tabletコンマで区切られた端末タイプのリスト。 端末タイプ のリストが適用されます。
grouping文字列、例:apps,countriesパラメータをグループ化。グループ化についての詳細は下記を参照してください。
human_readable_kpisブーリアンヘッドラインを英語の書式設定で印刷します(例:適切な大文字化ルールに従う)。


アプリKPI

このエンドポイントのkpisパラメータに対しては、前に説明した通り、同じアプリKPIセットを使うことができます。以下は有効なURLの例です。
https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek?kpis=installs,sessions

そしてコホートに対しては:
https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek/cohorts?kpis=converted_users,sessions

これにより、2つのリクエストされたアプリに対して、デフォルト期間中のインストールおよびセッションデータの内訳が提供されます(つまり2つのアプリトークン)。


マルチアプリグルーピング

デフォルトでは、このエンドポイントのグルーピングはアプリごととなっています。ただし、トラッカー別や期間別、あるいはその組み合わせでグルーピングすることも可能です。特にグルーピングセクションで説明された事項はここでも適用されます。

アプリごとの時系列データ
2つのアプリで、そのそれぞれについてインストールとセッションの時系列データを取得する方法の一例:
https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek?kpis=installs,sessions&grouping=apps,days

全アプリの時系列データ
グルーピング内でappsを省略し、daysのみで集計することができるようになりました。アプリプロフィール全体の概要を素早く確認するのに大変便利な方法です。
https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek?kpis=installs,sessions&grouping=days

このリクエストからのレスポンス例:
 
dateinstallssessions
2015-12-01209311703
2015-12-02112411211
2015-12-0356515687

注:これは表形式のレスポンスバージョン、すなわちCSV形式の出力です。

アプリとネットワークトラッカーの内訳
次に、2つのアプリそれぞれに対して、インストールとセッションのデータをネットワークトラッカー別に集約された形でリクエストすることができます。これはアプリプロフィール全体で異なるネットワークのパフォーマンスを比較するのに役立ちます。
https://api.adjust.com/kpis/v1/44cdcdck2syc,9xmtsnp687ek?kpis=installs,sessions&grouping=apps,networks

このリクエストからの表形式の出力例:
 
app_tokenapp_nametracker_tokennetworkinstallssessions
44cdcdck2sycFirst App5aml2fAdNetwork4080
44cdcdck2sycFirst App28kse9Email Ads192292
9xmtsnp687ekMy Other App16px8zAnotherNetwork20013001
9xmtsnp687ekMy Other App21h2o9Email Ads1737


KPIサービス用語集

当社の便利なKPIサービス用語集にてAdjust提供のKPIの全リストをご確認いただけます。ここではKPIの定義ならびに計算方法が説明されています。

このトピックについて