コホート分析API

概要:コホートレポートAPIは、プログラム的にコホートデータを取得する方法を広告主に提供します。APIを使用して、コホートデータをBI、およびマーケティングオートメーションシステムに統合できます。

AppsFlyer管理画面のコホートレポートの例

CohortEg_us-en.jpg

コホートレポートAPI

コホートレポートAPIは、AppsFlyerプラットフォームからコホートキャンペーンパフォーマンスデータを取得するために使用されます。これはコホート管理画面と機能的に同等です。

開発者向けの考慮事項

  • 日付:日付または日付期間は生涯価値 (LTV) の日付であり、つまりユーザーがアトリビュートされた日(コンバージョン日)で、アクティビティが発生した日ではありません。
  • ブーリアン値:tue または falseです(大文字と小文字を区別)。
  • データの鮮度毎日更新。毎日の更新時刻の後にAPIコールを行ってください。
  • 情報開示と開示しない代理店のトラフィック:代理店が運用するメディアソースのトラフィックは常に代理店名であり、元のメディアソースではありません。現時点では、コホートのUIバージョンの動作は異なります。
  • 単一アプリ:コホートAPIは単一アプリ向けのソリューションです。これは、1つのコールで複数アプリをサポートするコホート管理画面とは対照的です。

APIの手順

このセクションには、コホートAPIを生成し使用するために必要な情報が含まれます。

コホートAPIの仕様

オーバービュー APIコールは、パス、ヘッダー、データクエリを含むJSONで構成されます。デフォルトでは、データはCSVファイルで出力されます。
パス

https://hq1.appsflyer.com/api/cohorts/v1/data/app/app_id

パスのパラメータ(必須)
  • app_id: AppsFlyer管理画面で表示されるアプリ識別子です。管理画面に表示されるとおりに正確に入力してください。

クエリパラメータ―

(オプション)

結果はCSV または JSONで取得されます。CSVファイルの構造はテーブル形式ですが、JSONの構造はレコード形式です。

  • [デフォルト] csv のファイル名はクエリにより異なります。
  • json はクエリと結果を含みます。
  • 例:format=json
  • https://hq1.appsflyer.com/api/cohorts/v1/data/app/app_id?format=json
HTTP メソッド POST
受け入れ可能なcontent types application/json
Authorization
  • ベアラトークンはリクエストヘッダーに含まれます。
  • コホートAPIを有効にするよう担当CSMまでご連絡いただき、トークンを管理画面から取得します。
    • 同じトークンがアカウント内のすべてのアプリに使用されます。
日付の制限
  • 最も古い日付 (コンバージョン) は、2019年1月1日です。
  • 最大クエリ範囲:60日間
レート制限
  • APIコールレート制限は、アカウントあたり、1分間につき60コール、1日につき50,000コールまで。
  • クエリは最大 10,000 行のデータを取得します。
ブーリアン値 常に小文字で:truefalse
コホートAPIの仕様

リクエストヘッダー

Key

value 必須
Content-Type application/json はい 
Authorization Bearer api_token_placeholder はい 
Accept application/json はい 

フィルターとグループ化のパラメーター

フィルタパラメータ―を使用して必要なデータを取得します。 

フィルタのパラメータ

項目

説明 必須 

cohort _type

コホートアトリビューション (コンバージョン) タイプは、次のいずれかです : ユーザー獲得リターゲティング全体

  • 「全体」は、ユーザー獲得とリターゲティングキャンペーンのパフォーマンスを組み合わせます。
  • リターゲティングとユーザー獲得キャンペーンの両方にイベントの成果が紐づいている場合、返されるKPIにはリターゲティングイベントのみが含まれます。つまり、is_primary=trueとなります。
  • フォーマット:文字列
  • 例:"cohort_type": "user_acquisition"
はい

min_cohort_size

最小コホートサイズは、小数ユーザーのみを含むコホートを除外することで、返されるレコード数を減らすために使用されます。 つまり、ユーザー のKPI は、指定された値と同等かより大きい値を持つことを意味します。

  • 形式:整数
  • 最小許容値:1。ゼロ (0)は送信しないでください。
  • デフォルト:1
  • 例:"min_cohort_size": 50
いいえ

from 

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

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

to

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

  • 範囲内の日数:1~31日
  • 1日のみの場合:fromto の値は同一になります。
  • 形式: yyyy-mm-dd
  • 例:"from": "2020-01-01", "to": 2020-01-31 は31日間です。
はい

partial_data

データの歪みや誤解釈を避けるために、コホートは完全な日のデータを返します。ただし、日数未満のデータが役に立つことがあります。

クエリに対する完全なコホート日数は、今日の日付と to の日付の差として計算されます。

  • [デフォルト] falseの場合、完全な日数が戻ります。
  • trueの場合、不完全なデータを持つ日を含む 180日までの日付が返されます。
  • 形式:ブーリアン
  • フラットフォームUI版:false

:5月10日に、4月1日~30日の間にコンバージョンがあったユーザーの完全なコホート日数は、10です。

  • false の場合 [デフォルト]、コホート日数0~9日が戻ります。これは、最後のコンバージョン日から今日までの日数 (10) です。
  • trueの場合、コホート日数1〜40が戻ります。11~40日は一部のデータのみが含まれ、データは戻りません。例えば、4月20日以降は、20日しか経過してない、等。
いいえ

filters

返されたデータと期間の日数を絞り込みます。フィルタのディメンション一覧からフィルタを選択します。

  • 形式:JSON内の文字列
  • 特定の地域に限定する例:"filters": {"geo": "US"} は米国に紐づくユーザーのみが含まれます。
  • 期間 (コホート)日数の例:期間フィルタはどの期間の計測結果が返されるかを設定します。利用できる値は、0~90、および180です。
  • デフォルト:期間フィルタが設定されていない場合、日数は0-30、60、90、および180が返されます。 期間フィルタの例
いいえ

グループ化を使用して、列を追加したり、レポートの粒度を低くします。

グループ化パラメーター

パラメータ名

必須 

groupings

はい

KPIの選択とフォーマット

  • この表では、利用できるKPIのリストとそれに関する関数を示しています。KPIを呼び出すとそのすべての関数が返されます。
  • 次のKPIは常に返されます:users、ecpi、cost 
  • コールごとに追加KPIを1つ選択します。
利用可能なKPIと関連関数
    関数
デフォルト/オプション KPI (ディメンション名) カウント cvr (コンバージョン率) 評価 合計 ユニークユーザー
数値 割合 割合 数値 数値
常に ユーザー - - - -
常に eCPI - - - -
常に cost - - - -
オプション "event_name"   -
オプション revenue - - -
オプション ROAS(広告費回収率) - - - -
オプション ROI - - - -
オプション sessions - - ✓(1)
オプション uninstalls - - -
(1) aggregation_type=on_day の場合、ユニークセッションが返されます。

パラメータ名

必須パラメータ

KPI

使用可能なKPIからKPIを1つ選択します。 将来的に複数のKPIが選択可能になる予定です。

  • リクエストされた各KPIについて、全ての関数が返されます。
  • 形式:配列内の文字列
  • 例A:"kpis": ["sessions"]
  • 例B:"kpis": ["event_name"]
はい

KPI形式パラメーターは、返されるKPIの形式を設定します。

KPI関数のプレゼンテーション

パラメータ名

必須 

preferred_currency

KPIの収益通貨

  • true の場合、プラットフォーム上で設定されているアプリ固有の通貨を使用して収益値が戻ります。
  • [デフォルト] false の場合、結果はUSDで返されます。
  • 形式:ブーリアン
  • フラットフォームUI版:true

いいえ

preferred_timezone

データ範囲のタイムゾーン

  • trueの場合、プラットフォームで設定されたアプリ固有のタイムゾーンを使用して表示されます。
  • [デフォルト] falseの場合、UTCタイムゾーンを使用して表示されます。
  • 形式:ブーリアン
  • フラットフォームUI版:true

いいえ

aggregation_type

  • cumulative
  • on_day

"aggregation_type": "cumulative"

フォーマット:文字列(String)

はい

per_user

KPI関数をアプリユーザー数で割ります。関連するKPIのみに適用されます。

  • trueの場合、KPI値はコホートのユーザー数で除算されます。
  • falseの場合、KPI値はユーザー数で除算されません。
  • 形式:ブーリアン
  • tureの場合の例:総収益が$1000で、アプリユーザー数が500の場合、値は$2で返されます。
いいえ

グループ化とフィルタのディメンション一覧

利用できるグループ化とフィルタのディメンション

ディメンション名

ディメンションAPI値

グループ

フィルター

広告

af_ad

Ad ID

af_ad_id

Campaign

c

Campaign ID

af_c_id

チャネル

af_channel

Media Source

pid

Sub Param 1

af_sub1

Keywords

af_keywords

代理店

af_prt

コンバージョンタイプ

conversion_type

サイトID

site_id

収益タイプ

revenue_type

Attributed Touch Type

attributed_touch_type

Adset

af_adset

Adset ID

af_adset_id

 

geo

日付(選択したcohort_typeのコンテキストでのインストール/リアトリビューション/リエンゲージメント日)

date

期間

period 

詳細な説明

 

x

Curl の例

この例には、完全なAPIコールが含まれています。


Curl -L -X POST 'https://hq1.appsflyer.com/api/cohorts/v1/data/app/<insertyour app_id here>?format=<insertresults format here>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <cohort_api_token_placeholder.Note the token has more than 700 characters.>'\
-H 'Accept: application/json' \
--data-raw '{
    "cohort_type": "user_acquisition",
    "min_cohort_size": 1,
    "preferred_timezone": false,
    "from": "2020-01-01",
    "to": "2020-01-31",
    "filters": {
        "period": [
            0,
            1,
            2,
            10,
            30,
            60
        ],
        "geo": [
            "US",
            "CN"
        ],
        "pid": [
            "Facebook Ads",
            "gooleadwords_int"
        ]
    },
    "preferred_currency": true,
    "aggregation_type": "on_day",
    "per_user": false,    
    "groupings": [
        "pid",
        "date"
    ],
    "kpis": [
        "sessions"
    ]
}'
返されるファイルの例:CSVJSON

Python の例

import http.client
import mimetypes
conn = http.client.HTTPSConnection("hq1.appsflyer.com")
payload = "{\r\n    \"cohort_type\": \"user_acquisition\",\r\n    \"min_cohort_size\": 1,\r\n    \"preferred_timezone\": false,\r\n    \"from\": \"2020-05-01\",\r\n    \"to\": \"2020-05-10\",\r\n    \"preferred_currency\": true,\r\n    \"aggregation_type\": \"cumulative\",\r\n    \"per_user\": false,   \r\n     \"groupings\": [\r\n               \"pid\",\r\n         \"date\"\r\n        ],\r\n    \"kpis\": [\r\n        \"roas\"\r\n    ]\r\n}"
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer [Enter token here]',
  'Accept': 'application/json',
  'Content-Type': 'application/json'
}
conn.request("POST","/api/cohorts/v1/data/app/[My App ID here]?format=csv", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
   

追加情報

レスポンスコードとトラブルシューティング

レスポンスステイタスコード

レスポンスコード

メッセージ

備考

200 OK

有効なデータが返されました

200 OK
  • データが返されませんでした
    • クエリは有効ですが クエリに一致するデータが見つかりません。
    • 日付範囲に将来の日付が含まれていないことを確認します。
    • コールでトークンが全く送信されませんでした。
401 Unauthorized
  • 認証トークンの形式が正しくありません。正しいトークンを使用していることを確認してください。700文字以上である必要があります。
404 Not found
  • ネットワーク、ファイアウォールなどに関連する問題を排除します。
  • 最後に発行されたトークンを使用していることを確認してください。現在のトークンは管理画面から取得できます。
  • パスで指定したアプリがコホートAPIの使用が許可されていることを確認してください。これは、サブスクリプションプランの一部です。AppsFlyerアカウントの管理者は [ご契約プラン] ぺージで確認できます。
 422 Unprocessable entity (処理不能)

このエラーコードの一般的な原因は次のとおりです:

  • リクエストがJSONに含まれ、クエリパラメータ―として送信されていないことを確認します。
  • JSONがこのドキュメントに従ってフォーマットされていることを確認します。
  • 不正な日付

CSVファイル名の構成

返されるCSVファイルに割り当てられる名前はAPIクエリから生成されます。その構成は、次の表で詳しく説明されています。

CSVファイル名の例

cohort_aggregation_type_per_user_kpi_report_app_id_from_to_timezone_currency_hash.csv
CSVファイル名の構造は、APIクエリによって異なります。
変数 可能な値
aggregation_type
  • on_day
  • cumulative
per_user
  • per_user 
  • false: Null 
KPI 例:セッション数
app_id リクエストされたアプリID
from from 日付:形式 yyyy-mm-dd
to to 日付:形式 yyyy-mm-dd
timezone ダイムゾーンのデフォルトはUTCです
currency 通貨コードのデフォルトはUSDです
hash

英数字のハッシュ文字列の長さ=5

期間フィルタの使用

期間はアトリビューション後の日を指し、期間0はアトリビューション日です。例えば、ユーザーがアプリを1月1日にインストールします。これがアトリビューション日です。期間0に購入が発生した場合、この購入は1月1日に発生しました。期間3に購入が発生した場合、この購入は1月4日に発生しました。同様に、11月11日にインストールしたユーザーは、これが期間0になります。1月14日に発生した購入は期間3となります。

レポートの期間範囲が1月1日から1月11日の場合、この期間にアトリビュート (インストール)されたユーザーがレポートに含まれます。その他のデータは含まれません。

  • 期間の値は、次の0~90、および180のうち、1つまたは複数を設定できます。例:0, 1, 2, 30, 180
  • 期間が指定されていない場合、デフォルトの値は次のとおりです:0、1、2…30まで、および60、90、180 

 期間フィルタの例

  • この例には、JSONクエリパラメータ、ローデータ、および結果のCSVファイルが含まれています。
  • クエリのフィルタ期間は、0、1、2で、選択されたKPIは収益です。
  • その結果、返されるデータには以下が含まれます。
    • ユーザー、コスト、eCPIの測定は常に返されます。
    • 収益の測定は、各期間、つまり期間 0、1、2の合計とカウントで構成されます。

クエリ

{
    "cohort_type": "user_acquisition",
    "min_cohort_size": 1,
    "preferred_timezone": false,
    "from": "2019-12-01",
    "to": "2020-01-01",
    "filters": {
        "period": [
            0,
            1,
            2
        ]
    },
    "aggregation_type": "on_day",
    "per_user": false,
    "groupings": [
        "pid"
    ],
    "kpis": [
        "revenue"
    ]
}

ローデータ

mceclip1.png

結果

mceclip0.png

ユーザーインターフェイスとAPIパラメータのマッピング

次の図は、コホート分析のユーザーインターフェイスとAPIパラメータをマッピングを示しています。APIとユーザーインターフェイスの2つのソリューションは、似ていますが同一ではありません。

このAPIバージョンには、次の追加オプションがあります。

  • 通貨の選択
  • タイムゾーンの選択
  • 期間で絞り込み
CohortMapping.jpg Cohortmapping2.jpg

集計タイプの違い

CohortRevnueCumulative.jpg

特性と制限事項

特性
特性 備考
アドネットワークのアクセス いいえ
代理店のアクセス いいえ
代理店への運用詳細の開示 サポートされていません
アプリ固有のタイムゾーン はい
アプリ固有の通貨 はい
サイズ制限 なし
レート制限

 APIコールレート制限:1アカウントあたり、1分につき60コールまで  

オーガニックデータ ご利用可能
非オーガニックデータ ご利用可能
コストデータの制限

AppsFlyerは、コホートレポートまたはコホートAPIに大文字を含むキーワードのコストデータを報告しません。

データの更新頻度 リアルタイム。コストとアンインストールの指標は毎日更新されます。
過去データ サポートされている最も早いコンバージョンデータ(インストールまたはリターゲティング):2019年1月1日
チームメンバーのアクセス 認証トークンは、アカウント管理者が管理画面から取得できます。
この記事は役に立ちましたか?