Adjust KPIサービスはAdjustへのプル型APIで、これを使ってプログラムを行い、追跡するモバイルアプリの統計情報をAdjustにリクエストすることができます。このサービスを実現するRESTful JSON APIについて以下に記述します。

APIに発行できるクエリには、概要イベントコホートの3種類があります。これらのクエリの主な働きは、ダッシュボードの所定のセクションと対応して、関連するKPI(キー パフォーマンス指標)を直接引き出すことです。

それぞれのクエリは、アプリに設定したすべてのネットワーク トラッカー、または所定の 親トラッカー.のいずれにも実行できます。したがって、各リソースにはエンドポイントが2種類あります。デフォルトのエンドポイントではトラッカー トークンを用いず、すべてのネットワーク トラッカーのデータをグループ分けし、もう一方ではトラッカー トークンを指定して、トラッカーごとに絞り込まれたデータをグループ分けできます。

APIの仕様を詳しく確認する前に、このAPIを補完するためにAdjustが構築したRクライアントに関する説明をご一読ください。もしも既にRを使っている場合は、このクライアントでAdjustのデータをRセッションに取り込む際の便利さに、きっと満足いただけます。

トラッカーの概念はAPIデータを解読する上で必要不可欠であるため、トラッカーにまつわる用語についておさらいすることもお勧めします。その中でも、 ネットワーク,、 キャンペーン,、 広告グループクリエイティブ のそれぞれのコンポーネントのトラッカーの階層構造の概念についてご確認ください。

注意 KPIサービスは、Business Pro以上のパッケージを利用しているユーザーだけが対象になります。ダッシュボードでパッケージの現在の価格設定を確認できます。

1バージョン番号の付加

APIの主なリリースにはバージョン番号が付きます。混乱を防ぐため、すべてのエンドポイントのURLパス内にAPIバージョンが記述されます。例えば、バージョン1の場合は、http://api.adjust.com/kpis/v1/..にアクセスします。

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

APIでは、CSVフォーマットとJSONフォーマットの2つに対応しています。デフォルトはJSONフォーマットです。別のフォーマットを指定するには、適切な文字列をエンドポイントの末尾に付けるか(エンドポイントのパスの末尾に.csvを付けるなど)、Accept: text/csv HTTPヘッダをリクエストと一緒に送信することができます。本書では、主にJSONを使用してリクエストと応答を例示します。

3認証

KPIサービスへのアクセス権は、Adjustユーザーアカウントにひも付けられています。それぞれのユーザーアカウントにユーザートークンが関連付けられているため、KPIへのアクセスをアカウントごとに制限できます。

ユーザートークンはダッシュボードのアカウント設定 > データから確認できます。以下で説明する認証設定には、このユーザートークンを使用します。

それぞれのユーザートークンには、各ユーザーのダッシュボードと同じ制限が設けられています。したがって、カスタムのユーザー権限を設定すると、KPIサービス経由のアクセスに対して、各ユーザーのダッシュボードでのアクセス権と同じルールが適用されます。

ユーザー トークンはいつでも更新可能です。

ユーザー トークンを使用したAPIの認証方法は2種類あり、実際の事例に応じて どちらを選択しても構いません。

  • HTTP GETパラメータとして、user_token=your_user_tokenをAPIクエリに付け足す方法。
  • HTTP認証ヘッダとして、Authorization: Token token=your_user_token形式のHTTPヘッダを
    `Authorization: Token token=your_user_token`
    

本書の例はすべてHTTPヘッダ認証を使ったものを紹介していますが、これらの例にGETパラメータと正しいトークンを簡単に付加しても、認証は有効になります。

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

有効なリクエストURLを取得するには、本書に記載されているすべてのエンドポイント内の:app_token:tracker_tokenという文字列を、実際のトークン値と入れ替る必要があります。例えば、

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

というURLは、アプリトークン2eb2na2w54c3とトラッカートークン15jvuiに対して有効です。本書の例はすべてアプリトークン2eb2na2w54c3を使用しているので、これをそのままお客様のアプリトークンと入れ替えてください。

5概要クエリ

概要クエリを使えば、 アプリKPIイベントKPIのデータを取得できます。 一般的な用途としては、clickssessionsinstallsといった指標を知るために、一定期間内に、アプリが稼働しているすべてのネットワーク、または特定の 親トラッカー.内のトラフィックを追跡します。また、revenuefirst_eventsなどのadjusのカスタム イベントに関するKPIもリクエストできます。さらにオプションとして 国名,、 プラットフォーム 、および デバイス で絞り込むこともできます。

このリソースは、統計情報ダッシュボードの「概要」セクションと深い対応関係にあります。

5.1エンドポイント

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}

5.2クエリのパラメータ

以下は、対応するクエリのパラメータのリストです。使用が想定されるパラメーター値の詳細もあわせてご参照ください。

パラメータ名 形式 説明
start_date YYYY-MM-DD 選択した期間の開始日です。
end_date YYYY-MM-DD 選択した期間の終了日です。
utc_offset [+-]HH:MM, 例:utc_offset=-05:00 or utc_offset=10:00 タイムゾーンのUTCオフセット
kpis 文字列。例: clicks,installs,maus コンマで区切ったアプリKPIのリストです。アプリKPIであれば、自由に組み合わせられます。
event_kpis 文字列。例:token1_events,token1_revenue_per_user コンマで区切ったイベントKPIのリストです。それぞれのKPIに、イベント トークンかallを接頭辞として付け足す必要があります。以下の例を参照してください。
reattributed 文字列 truefalseallのいずれか インストールまたはリアトリビュートされたユーザーのみ、またはすべてのユーザーによるフィルタKPI(デフォルト)
sandbox 文字列。trueまたはfalse サンドボックス版または製品版のデータを指定してリクエストできます。デフォルトでは、製品版のデータの収集を想定しています。
impression_based 文字列 trueまたはfalse クリックかインプレッションのどちらかに基づくビューにてリクエストできます。デフォルトではクリックに基づく想定です。
attribution_type 文字列。clickimpression、またはall クリック、インプレッション、またはクリックとインプレッションの組み合わせ。(これはimpression_basedパラメータを上書きします)
countries 文字列。例:de,us コンマで区切ったISO 3166 alpha-2表記の国名リストです。
os_names 文字列。例:ios,android コンマで区切ったOS名のリストです。有効なOS名は以下のとおりです。
device_types 文字列。例:phone,tablet コンマで区切った有効なデバイスの種類のリストです。有効なデバイスの種類は以下のとおりです。
grouping 文字列。例:trackers,countries グループ化に用いるパラメータです。グループ化の詳細については、以下をご参照ください。

5.3アプリKPI

対応するアプリKPIは以下のとおりです。kpisパラメータの値として渡すことができます。

アプリKPI 説明
clicks クリック数
impressions インプレッション数
installs インストール数
uninstalls アンインストール数 
uninstall_cohort 選択した期間内にインストールしたユーザーがアンインストールした数
reinstalls リインストール数
attribution_type クリック、インプレッション、またはクリックとインプレッションの混合
click_conversion_rate クリックがコンバージョンに至った割合(clicksで加重したclicks/installsの平均値)
ctr クリック率 (clicks/impressions)
impression_conversion_rate インプレッションがコンバージョンに至った割合 (impressionsで加重したinstalls/impressionsの平均値)
reattributions リアトリビューション数
reattribution_reinstalls リアトリビューションにつながったリインストール数 
deattributions デアトリビューション数
sessions セッション数
revenue_events 売上イベント数
revenue 売上総額(アプリのレポート通貨表示)
cohort_revenue 設定した期間内にインストールしたユーザーからの売上合計
daus 日単位の平均アクティブユーザー数
waus 週単位の平均アクティブユーザー数
maus 月単位の平均アクティブユーザー数
gdpr_forgets EUの一般データ保護規則(GDPR)の忘れられる権利(right to be forgotten) を行使しているユーザーの総数。Adjustは彼らの過去の個人データを削除し、集計データのみダッシュボードのレポートで保持します。これにより彼らの端末データをAdjustが受信することはなくなり、Adjustのダッシュボード上に表示されることもありません。

5.4不正防止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により却下されたインストールの数
rejected_installs_too_many_engagements エンゲージメント過多により却下されたインストールの数
rejected_installs_distribution_outlier ディストリビューション異常値により却下されたインストールの数
rejected_installs_click_injection エンゲージメントインジェクションにより却下されたインストールの数
rejected_reattributions 却下されたリアトリビューションの数で、rejected_reattributions_anon_ip + rejected_reattributions_too_many_engagements + rejected_reattributions_distribution_outlier + rejected_reattributions_click_injectionの合計
rejected_reattributions_anon_ip 匿名IPにより却下されたリアトリビューションの数
rejected_reattributions_too_many_engagements エンゲージメント過多により却下されたリアトリビューションの数
rejected_reattributions_distribution_outlier ディストリビューション異常値により却下されたリアトリビューションの数
rejected_reattributions_click_injection エンゲージメントインジェクションにより却下されたリアトリビューションの数
rejected_install_rate インストール却下率: rejected_installs/(installs + rejected_installs).
rejected_install_anon_ip_rate 匿名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によるリアトリビューション却下率: 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)

5.5費用KPIs

費用KPIは、費用データを有効化しているAdjustアカウントでのみご利用いただけます。

費用 KPI 説明
install_cost インストール費用
click_cost クリック費用
impression_cost インプレッション費用
cost click_costimpression_costinstall_costの総計
paid_installs 費用データがあるインストールの数
paid_clicks 費用データがあるクリックの数
paid_impressions 費用データがあるインプレッションの数
ecpc クリックごとの有効な費用 例:cost / paid_clicks
ecpm CPMの有効なコスト(1000回のインプレッション、 例: cost / paid_impressions * 1000
ecpi インストールごとの有効な費用 例:cost / paid_installs
cohort_gross_profit 粗利益 例: cohort_revenue - cost
return_on_investment cohort_gross_profit / costによって得られたROI指標
revenue_to_cost cohort_revenue/costによって得られた収益に対するコスト比率

注意: コストはミリオン単位になります。つまり5.45661ユーロは費用=545661になります。

5.6イベントKPI

対応するイベントKPIは以下のとおりです。event_tokenを接頭辞として付け足して、 Overviewリクエストのevent_kpisパラメータに渡すことができます。イベントのセクションで説明するとおり、 このイベントKPI を、Eventsリクエストに使用することもできます。

イベントKPI 説明
revenue_events 売上イベント数です。
revenue 売上総額(アプリのレポート通貨表示)です。
events イベント数です。
first_events ユーザーが初めて最初に発生させたイベント数です。first_eventseventsの関係は、installssessionsの関係と同様に考えることができます。
revenue_per_event 総売上高をイベント数で割った値です。
revenue_per_revenue_event 総売上高を売上イベント数で割った値です。

5.7イベントKPIリクエストの簡略化

このセクションは、概要リクエストでevent_kpisを要求しようと検討している場合にお読みください。それ以外の場合は、 読み飛ばしても構いません。

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つのフォーマットの違いは、指標の順序の決定方法であることを留意してください。これについては、以下に詳しく説明します。

5.8

アプリ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_parameterskpis配列がresult_setkpi_values配列と一対一で対応しています。 例えば、この応答のトラッカーNetwork 1には、sessions100件とinstalls299件が含まれています。

アプリ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", "token2_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_parameterskpis配列がresult_setkpi_values配列と一対一で対応しています。 したがって、この応答のトラッカーNetwork 1には、クリック数221件、トークンtoken1の付いたイベント発生件数100件と、 発生したイベントによる売上額299.30(ドル)が含まれます。

5.9KPIの順番決め

kpisevent_kpisのリクエスト順序によって、応答の受信順序が決まります。 直前のセクションの最後の例は、これに関するものです。

このKPIの順序決めは、APIからcsvデータをリクエストする際に特に便利です。この場合、csvの列の項目は、 リクエストしたKPIと全く同じ順番で表示されます。

6イベント クエリ

このセクションでは、イベントKPIのクエリについて説明します。ここで紹介するエンドポイントは、イベントごとにデータをグループ化したい場合に特に便利です。このリソースは、 このリソースは、統計情報ダッシュボードの「イベント」セクションと深い対応関係にあります。

6.1エンドポイント

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}

6.2クエリのパラメータ

以下は、対応するクエリのパラメータのリストです。使用が想定されるパラメーター値の詳細もあわせて参照してください。

パラメータ名 形式 説明
start_date YYYY-MM-DD 選択した期間の開始日です。
end_date YYYY-MM-DD 選択した期間の終了日です。
kpis 文字列。例:revenue_events,revenue コンマで区切られたイベントKPIのリストです。イベントKPIであれば、自由に組み合わせられます。
sandbox 文字列。 true または false サンドボックス版または製品版のデータを指定してリクエストできます。デフォルトでは、製品版のデータの収集を想定しています。
events 文字列。例:event_token1,event_token2 コンマで区切られたイベント トークンのリストです。イベント トークンは、Adjustダッシュボードにあります。
attribution_type 文字列。clickimpression、またはall クリック、インプレッション、またはクリックとインプレッションの組み合わせ。(これはimpression_basedパラメータを上書きします)
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 グループ化に用いるパラメータです。グループ化の詳細については、以下をご参照ください。

6.3イベントKPI

イベントKPIのリストについては、前のセクションに説明するとおりですが、概要クエリと違い、イベントリクエストでは、 イベントKPIにイベント トークンを接頭辞として付け足しません。特定のイベントのデータが必要な場合は、eventsパラメータを使用して、 イベント トークンを補います。

6.4

リクエスト:

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_parameterskpis配列がresult_setkpi_values配列と一対一で対応しています。 この応答では、0.8のrevenue_per_event(イベント当たり売上高)で「ログイン」イベントが5回記録されました。

7コホートクエリ

コホートクエリを使用して、ユーザーのインストール日、購入日、登録日などの、 ユーザー コホート毎に集計されたデータを照会できます。これにより、インストール後一定日数が経過した時点での継続利用率といったコホート ベースのKPIを 取得できます。 コホート分析ガイドをご参照ください。

コホートを表示する際は、コホート期間とKPI ベースを選ぶ必要があります。選択した期間により、週単位のコホート(指定した日/週/月にインストールしたユーザー数など)、 またはこの指定期間に基づくKPI(インストール後の利用日数/週数/月数による継続利用率など)を示すデータがどこまで細分化されるかが決まります。 KPI ベースは、全ユーザー、(少なくとも売上イベントを1つ発生させた)課金ユーザー、 任意設定イベントを発生させたユーザーの中からユーザー分類を定義します。

7.1エンドポイント

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

7.2クエリのパラメータ:

以下は、対応するクエリのパラメータのリストです。使用が想定されるパラメーター値の詳細もあわせて参照してください。

パラメータ名 形式 説明
start_date YYYY-MM-DD 選択した期間の開始日です。
end_date YYYY-MM-DD 選択した期間の終了日です。
kpis 文字列。例:revenue_events,revenue コンマで区切られたアプリKPIのリストです。アプリKPIであれば、自由に組み合わせられます。
sandbox 文字列。 true または false サンドボックス版または製品版のデータを指定してリクエストできます。デフォルトでは、製品版のデータの収集を想定しています。
period day/week/monthのいずれか コホート期間です。
events 文字列。例:abcdef,12345 コンマで区切られたイベント トークンのリストです。
countries 文字列。例:de,us コンマで区切ったISO 3166 alpha-2表記の国名リストです。
os_names 文字列。例:ios,android コンマで区切ったOS名のリストです。有効なOS名は以下のとおりです。
device_types 文字列。例:phone,tablet コンマで区切った有効なデバイスの種類のリストです。有効なデバイスの種類は以下のとおりです。
grouping 文字列。例:trackers,install_date グループ化に用いるパラメータです。グループ化の詳細については、以下をご参照ください。

7.3コホートKPI

コホートKPI 説明
retained_users 期間内に戻ってきたユーザー数
cohort_size 期間内に利用する可能性のあるユーザー数
retention_rate 期間内の継続利用ユーザー数をユーザー総数で割った値
reattributions 期間内のリアトリビュートされたユーザー数
deattributions 期間内のデアトリビュートされたユーザー数 (例えば、最初のインストールトラッカーとは別のソースにリアトリビュートされた場合)
sessions 1期間あたりに発生したセッション数を示します。
sessions_per_user セッション数をretained_usersで割った値を示します。
uninstalls 期間内のアンインストール数
uninstalls_total 全期間でのアンインストール数
reinstalls 期間内のリインストール数
reinstalls_total 全期間でのリインストール数
revenue 1期間あたりの売上高を示します。
revenue_total 指定期間内と過去のすべての期間に発生した売上高を示します。
revenue_per_user revenuecohort_sizeで割った値を示します。
revenue_per_paying_user revenuepaying_user_sizeで割った値を示します。
revenue_total_in_cohort インストールから設定した期間後、設定した期間前にインストールしたユーザのOからNの総売上
lifetime value revenue_total_in_cohortcohort_sizeで割った値を示します。
paying_user_lifetime_value revenue_totalpaying_users_sizeで割った値を示します。
time_spent 期間内にユーザーがアプリを使用した合計時間(秒単位)を示します。
time_spent_per_user time_spentcohort_sizeで割った値を示します。
time_spent_per_session time_spentsessionsで割った値を示します。
paying_users 期間内の課金ユーザー数を示します。
paying_user_size 課金ユーザー総数を示します。
paying_users_retention_rate paying_usersretained_usersで割った値を示します。
paying_user_rate paying_userscohort_sizeで割った値を示します。
revenue_events 1期間あたりの売上数を示します。
revenue_events_total_in_cohort 指定の期間内と過去の全ての期間に発生した収益の累計額を示します。
revenue_events_per_user revenue_eventscohort_sizeで割った値を示します。
revenue_events_per_active_user revenue_eventsretained_usersで割った値を示します。
revenue_events_per_paying_user revenue_eventspaying_users 割った値を示します。
converted_users 期間内にイベントを発生させたユニークユーザー数を示します。
converted_user_size コンバージョンしたユーザー総数を示します。
conversion_distribution converted_usersconverted_user_sizeで割った値を示します。
conversion_per_user converted_userscohort_sizeで割った値を示します。
conversion_per_active_user converted_usersretained_usersで割った値を示します。
events 期間内に発生したイベント数を示します。
events_per_converted_user eventsconverted_usersで割った値を示します。
events_per_user eventscohort_sizeで割った値を示します。
events_per_active_user eventsretention_rateで割った値を示します。

7.4

リクエスト:

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と一対一で対応しています。

8クエリのパラメータ

このセクションでは、これまでに説明したAPIリクエストの各パラメータについてより詳しく説明します。APIは リクエスト パラメータを解析して、検出されたエラーの発生状況を説明します。無効なリクエストへの応答はHTTP 400エラーとともに返されます。 リクエスト本文に問題の詳細が記述されます。

8.1期間

start_dateend_dateにより、日付範囲フィルタがYYYY-MM-DD形式で指定されます。範囲指定がない場合は、現在の月が デフォルトの日付範囲となります。

8.2KPI

kpisパラメータにより、リソースごとに違う場合がある、コンマ区切りで列挙される、リクエストされたKPI値が定まります。パラメータの 指定がない場合は、デフォルトのリストが対象となります。応答result_setkpis配列を返す点に留意してください。

8.3国名

countriesパラメータにより、コンマで区切られ列挙される、ISO 3166-1準拠の、ラテン文字2文字の国名コード が定まります。countryフィルタの指定がない場合は、 すべての国が対象となります。

8.4OS名

有効なos_names値のリストは以下のとおりです。

android
bada
blackberry
ios
linux
macos
server
symbian
unknown
webos
windows
windows-phone

8.5デバイスの種類

有効なdevice_types値のリストは以下のとおりです。

bot
console
ipod
mac
pc
phone
resolver
server
simulator
tablet
unknown

8.6可読形式なKPI

human_readable_kpisのGETパラメータをリクエストURLに追加すると、そのGETにあるKPIデータ(KPI,期間など)が人間が読める英語のデータが出力されます。たとえばlifetime_valueの代わりにLifetime Valueが出てきます。また、periodのがWeeks after Installになります。(weekの期間の場合) KPIサービスから頂いたCSVを変更せずにレポートとして利用することができます。

9グループ化

groupingパラメータにより、データセットのグループ化の仕方が定まります。得られるデータは、指定したとおり正確な順序で入れ子になって記述されます。 例:grouping=trackers,countries はトラッカーを国名コードごとに入れ子内に記述し、grouping=countries,trackersはその反対に国名コード をトラッカーごとに入れ子内に記述します。グループ化パラメータを色々試して順番付けの感覚をつかむことをお勧めします。

groupingリクエスト パラメータが取ることのできるすべての値の一覧を以下に示します。

9.1トラッカー関連のグループ化

トラッカーによるグループ化を行って、トラッカー ツリーの構造に合わせてトラッカーごとにデータを細分化できます。いくつかの例を以下に説明します。

  • 親トラッカーとgrouping=trackersを指定しない場合、アプリのすべてのネットワーク トラッカーでデータがグループ化されます。

  • 親トラッカーとgrouping=campaignsを指定しない場合、アプリのすべてのキャンペーントラッカーでデータが グループ化されます。

  • キャンペーンの親トラッカーとgrouping=trackersまたはgrouping=adgroupsを指定した場合、指定したキャンペーンの親トラッカーの下位にあたるすべての 広告グループ トラッカーでデータがグループ化されます。

  • キャンペーンの親トラッカーとgrouping=creativesを指定した場合、指定したキャンペーンの親トラッカーの下位にあたるすべての クリエイティブ トラッカーでデータがグループ化されます。

パラメータが取ることのできるすべての値の一覧は以下のとおりです。

  • trackers:オプションとして指定したtracker_tokenに応じて、ネットワーク / キャンペーン / 広告グループ / クリエイティブごとにグループ化します。 トラッカーによるグループ化の詳細については、トラッカー ツリーのセクションをご参照ください。

  • networks:オプションとして指定したtracker_tokenに関係なくネットワークごとにグループ化します。後に得られるデータセットには、 検出されたネットワークの配列を含むnetworksフィールドが含まれます。

  • campaigns:オプションとして指定したtracker_tokenに関係なくネットワークごとにグループ化します。後に得られるデータセットには、 検出されたキャンペーンの配列を含むcampaignsフィールドが含まれます。

  • adgroups:オプションとして指定したtracker_tokenに関係なく広告グループごとにグループ化します。後に得られるデータセットには、 検出された広告グループの配列を含むadgroupsフィールドが含まれます。

  • creatives:オプションとして指定したtracker_tokenに関係なくネットワークごとにグループ化します。後に得られるデータセットには、 検出されたクリエイティブの配列を含むcreativesフィールドが含まれます。

9.2カレンダー期間によるグループ化

  • day:日ごとにグループ化します。後に得られるデータセットには、該当する期間内の適用可能な日付の配列を含むdatesフィールドが含まれます。 ここで、対応するdateフィールドによって日付に名前が付けられます。

  • week:週ごとにグループ化します。後に得られるデータセットには、該当する期間内の適用可能な週の配列を含むdatesフィールドが含まれます。 ここで、対応するdateフィールドによって週の開始日に名前が付けられます。

  • month:月ごとにグループ化します。後に得られるデータセットには、該当する期間内の適用可能な月の配列を含むdatesフィールドが含まれます。 ここで、対応するdateフィールドによって月の開始日に名前が付けられます。

注意:長期間の日付範囲(週または月)のグループ分けを使用する場合は、期間全体が含まれるよう日付を選ぶことをお勧めします。 初日に指定したdateが週または月の開始日とみなされ、それ以前の日は切り捨てられます。週や月の途中の日付を開始日に選択した場合は、 このグループと、後に得られるデータセットの他のグループとの適正な比較が行えない場合があります。

9.3その他のグループ化オプション

  • countries:国名コードごとにグループ化します。後に得られるデータセットには、検出された国名コードの配列を含むcountriesフィールドが含まれます。 ここで、対応するcountryフィールドによってISO 3166-1準拠の、ラテン文字2文字の国名コードが定められます。

  • device_types:デバイスの種類ごとにグループ化します。後に得られるデータセットには、検出されたdevice_typesの配列を含むdevice_typesフィールドが含まれます。 ここで、対応するdevice_typeフィールドによって上記ののdevice_typesセクションのリストで示したデバイスの種類 が定められます。

  • os_names:OS名ごとにグループ化します。後に得られるデータセットには、検出されたos_namesの配列を含むos_namesフィールドが含まれます。 ここで、対応するos_nameフィールドによってデバイスのオペレーティング システムが定められます。

  • partners: パートナー名ごとにクリープ化します。後に得られるデータセットには、検出されたパートナーの配列を含むpartner フィールドが含まれます。 ここで、対応するpartnerフィールドによってデータが属するパートナーが名付けられます。

10トラッカー ツリー

前のセクションで説明したとおり、トラッカー トークンの指定の有無に関わらず、すべてのエンドポイントをリクエストすることができます。前述したそれぞれのリソースでは、 2つのエンドポイントが指定されており、その2番目の形式でトラッカーが指定されています。2番目の形式を使用すると、生成されるデータセットが 指定されたトラッカーでフィルタリングされ、得られたデータセットが、trackersパラメータのグループ化によってサブトラッカーで分類されます。

トラッカー トークンが指定されていない場合、すべてのネットワークのデータが返され、得られたデータセットが trackersパラメータのグループ化によって、 ネットワーク レベルのトラッカーでtrackers配列のエントリとして分類されます。

trackersパラメータでグループ化を行うと、得られるデータセットにはそれぞれのトラッカーのメタデータが含まれます。このメタデータには、 has_subtrackersブール値フィールドが含まれいます。これは、クエリに特定のトークンを含めて照会すれば、より深い階層のトラッカー情報が得られるということです。

例えば、キャンペーンの親トラッカーを含むクエリをリクエストする場合、応答には、広告グループを表すそれぞれのサブトラッカーで グループ化されたデータが含まれます。

11複数のアプリ

デフォルトとして、KPIサービスのエンドポイントが1つのアプリようとなりますが、トラッカー、期間などでもグループ化することができます。グループ化がこちらでも当てはまります。

11.1複数のアプリの期間KPIデータ

下記のリクエストにて2つのアプリの期間KPIを出力することができます:

https://api.adjust.com/kpis/v1?app_tokens=44cdcdck2syc,9xmtsnp687ek&kpis=installs,sessions&grouping=apps,days

11.2すべてのアプリの期間KPIデータ

appsを削除しdaysのみでデータを集計すると、すべてのアプリのKPIをすぐ出力することができます。

https://api.adjust.com/kpis/v1.csv?app_tokens=44cdcdck2syc,9xmtsnp687ek&kpis=installs,sessions&grouping=days

すると、下記のようなレスポンスが出てきます:

date installs sessions
2015-12-01 2093 11703
2015-12-02 1124 11211
2015-12-03 5651 5687

こちらは表形式のバーション(CSVフォーマット)のレスポンスとなります。

11.3アプリのネットワークトラッカーのまとめ

ネットワークを比較するため、下記のリクエストでネットワークトラッカーで集計した両方のアプリのインストールとセッションを出力します。

https://api.adjust.com/kpis/v1.csv?app_tokens=44cdcdck2syc,9xmtsnp687ek&kpis=installs,sessions&grouping=apps,networks

出力が下記のようになります:

app_token app_name tracker_token network installs sessions
44cdcdck2syc First App 5aml2f AdNetwork 40 80
44cdcdck2syc First App 28kse9 Email Ads 192 292
9xmtsnp687ek My Other App 16px8z AnotherNetwork 2001 3001
9xmtsnp687ek My Other App 21h2o9 Email Ads 17 37