概要： コホートAPIは、広告主がコホートデータを取得するためのプログラム的な方法を提供します。 APIを使用して、コホートデータをBI、およびマーケティングオートメーションシステムに統合できます。
コホートAPI
コホートレポートAPIは、AppsFlyerプラットフォームからコホートキャンペーンパフォーマンスデータを取得するために使用されます。これはコホート管理画面と機能的に同等です。
コホートとリテンションを使用するには、表示するデータを定義します。 アプリからユーザーを選択し、コンバージョン時間でセグメント化します。 収益、ROI、イベントコンバージョン率などのコホート指標が利用可能です。 比較分析のために、コホートをキャンペーンまたはメディアソースなどのディメンション別に分類します。結果は CSV ファイルまたは JSON ファイルとして返されます。この結果を使用して、ユーザーまたはキャンペーンのライフサイクルにおけるパフォーマンスのパターンや変化を明らかにすることができます。
コホートのユースケースをご覧ください。
コホートAPIの使用：
APIトークンを取得してください（管理者（アドミン）のみがトークンを取得できます）。
- 認証ヘッダーで使用する APIトークンを開発者に渡します。
- 次のセクションで説明するように、APIコールを行うときに入力するパラメーターを開発者へ渡してください。パラメーターは、レポートが何に焦点を当て、どのように編成されるかを決定し、レポートの時間枠を定義します。
- AppsFlyer公式デベロッパーハブの コホートAPIの手順 に従うように開発者に伝えてください。
コホートAPIのパラメーター
次のパラメーターを使用して、必要なデータを取得します。
|
項目 |
説明 | 必須 |
|---|---|---|
|
bearer |
API 認証ヘッダーで使用される APIトークン。 |
はい |
|
cohort _type |
コホートアトリビューション (コンバージョン) タイプは、次のいずれかです :
|
はい |
|
min_cohort_size |
最小コホートサイズは、小数ユーザーのみを含むコホートを除外することで、返されるレコード数を減らすために使用されます。つまり、ユーザー のKPI は、指定された値と同等かより大きい値を持つことを意味します。
|
いいえ |
|
from |
LTVアトリビューション日付期間の下限。過去データのサポート範囲は、現在から730日前までです。
|
はい |
|
to |
LTVアトリビューション日付期間の上限。
|
はい |
|
granularity |
過去72時間分の1時間ごとの粒度。
"granularity": "hour",
"from": "2021-12-01 14:00:00", "to": "2021-12-03 11:00:00",
|
いいえ |
|
partial_data |
データの歪みや誤解釈を避けるために、コホートは完全な日のデータを返します。ただし、日数未満のデータが役に立つことがあります。 クエリに対する完全なコホート日数は、今日の日付と to の日付の差として計算されます。
例：5月10日に、4月1日～30日の間にコンバージョンがあったユーザーの完全なコホート日数は、10です。
注：部分的なデータは、集計タイプが累積的な場合にのみ許可されます。 |
いいえ |
|
filters |
返されたデータと期間の日数を絞り込みます。フィルタのディメンション一覧からフィルタを選択します。
|
いいえ |
|
groupings |
|
はい |
|
KPI |
KPIはアプリの状況を確認するための指標となります。詳細：KPIの選択と書式設定の方法を確認する | はい |
| preferred_currency | 返される KPIの形式を設定するパラメーター。 詳細：KPIの書式設定方法の詳細 | いいえ |
| preferred_timezone | 返される KPIの形式を設定するパラメーター。 詳細：KPIの書式設定方法の詳細 | いいえ |
| aggregation_type | 返される KPIの形式を設定するパラメーター。 詳細：KPIの書式設定方法の詳細 | はい |
| per_user | 返される KPIの形式を設定するパラメーター。 詳細：KPIの書式設定方法の詳細 | いいえ |
KPIの選択とフォーマット
- この表では、利用できるKPIのリストとそれに関する関数を示しています。KPIを呼び出すとそのすべての関数が返されます。
- 次のKPIは常に返されます：users、ecpi、cost
- コールごとに追加KPIを1つ選択します。
- リクエストされた各KPIについて、全ての関数が返されます。
- 形式：配列内の文字列
- 例 A:
"kpis": ["sessions"] - 例B：
"kpis": ["event_name"]
- 例 A:
| 関数 | ||||||
|---|---|---|---|---|---|---|
| デフォルト/オプション | KPI (ディメンション名) | カウント | cvr (コンバージョン率) | 評価 | 合計 | ユニークユーザー |
| 数値 | 割合 | 割合 | 数値 | 数値 | ||
| 常に | ユーザー | Y | - | - | - | - |
| 常に | eCPI | - | - | Y | - | - |
| 常に | cost | - | - | - | Y | - |
| オプション | "event_name"(4) |
Y | Y | - | Y (3) | Y |
| オプション | revenue | Y | - | - | Y | - |
| オプション | ROAS（広告費回収率） | - | - | Y | - | - |
| オプション | ROI | - | - | Y | - | - |
| オプション | sessions | Y | - | Y | - | Y(1) |
| オプション | uninstalls (2) | Y | - | Y | - | - |
|
(1) aggregation_type=on_day の場合、ユニークセッションが返されます。 (2) cohort_type=unified の場合は利用できません。 (3) 合計とは、イベントで発生した収益の合計を意味します。レポートでは、これを (4) 注！イベント名は大文字小文字を区別します。 |
||||||
KPI関数の書式設定
次のパラメーターは、返される KPIの形式を設定します。
|
パラメータ名 |
値 | 必須 |
|---|---|---|
|
preferred_currency |
KPIの収益通貨
|
いいえ |
|
preferred_timezone |
データ範囲のタイムゾーン
|
いいえ |
|
aggregation_type |
|
はい |
|
per_user |
KPI関数をアプリユーザー数で割ります。関連するKPIのみに適用されます。
|
いいえ |
ディメンションのグループ化とフィルター
|
ディメンション名 |
ディメンションAPI値 |
グループ |
フィルター |
|---|---|---|---|
|
広告 |
af_ad |
Y |
Y |
|
Ad ID |
af_ad_id |
Y |
Y |
|
Campaign |
c |
Y |
Y |
|
Campaign ID |
af_c_id |
Y |
Y |
|
チャネル |
af_channel |
Y |
Y |
|
Media Source |
pid |
Y |
Y |
|
Sub Param 1 |
af_sub1 |
Y |
Y |
|
Keywords |
af_keywords |
Y |
Y |
|
代理店 |
af_prt |
Y |
Y |
|
コンバージョンタイプ (1) |
cohort _type |
Y |
Y |
|
サイトID |
site_id |
Y |
Y |
|
収益タイプ (2) |
revenue_type |
x |
Y |
|
アトリビューションタッチタイプ (3) |
attributed_touch_type |
Y |
Y |
|
Adset |
af_adset |
Y |
Y |
|
Adset ID |
af_adset_id |
Y |
Y |
|
国 |
geo |
Y |
Y |
|
日付（選択したcohort_typeのコンテキストでのインストール／リアトリビューション／リエンゲージメント日） |
date |
Y |
x |
|
期間 |
期間
|
x |
Y |
|
注意： ディメンションのオプション： (1) コンバージョンタイプ：
(2) 収益タイプ： click, impression, TV, pre-installed
|
|||
追加情報
期間フィルタの使用
期間はアトリビューション後の日を指し、期間0はアトリビューション日です。例えば、ユーザーがアプリを1月1日にインストールします。これがアトリビューション日です。期間0に購入が発生した場合、この購入は1月1日に発生しました。期間3に購入が発生した場合、この購入は1月4日に発生しました。同様に、11月11日にインストールしたユーザーは、これが期間0になります。1月14日に発生した購入は期間3となります。
レポートの期間範囲が1月1日から1月11日の場合、この期間にアトリビュート（インストール）されたユーザーがレポートに含まれます。その他のデータは含まれません。
- 期間の値は、0-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"
]
}
ローデータ
結果
特性と制限事項
| 特性 | 備考 |
|---|---|
| アドネットワークのアクセス |
いいえ。広告主が権限を付与した場合、キャンペーン運用パートナーはAPIを使用できます。 |
| 代理店のアクセス | いいえ |
| 代理店への運用詳細の開示 | いいえ： 代理店が運用するメディアソースのトラフィックは常に代理店名であり、元のメディアソースではありません。 |
| アプリ固有のタイムゾーン | はい |
| アプリ固有の通貨 | はい |
| サイズ制限 | なし |
| レート制限 |
|
| オーガニックデータ | ご利用可能 |
| 非オーガニックデータ | ご利用可能 |
| コストデータの制限 |
|
| データの更新頻度 |
データ更新頻度は、以下の partial_data により異なります：
|
| 過去データ | デイリーコホート：2年間 |
| アカウントユーザーのアクセス | 認証トークンは、管理画面でアドミンユーザーが利用できます |
| 広告収益 |
af_ad_revenueイベントの場合、2022年10月5日から 2023年2月16日までの日付の集計タイプが "on day"（日毎）の場合、ユニークユーザー指標は使用できません。 |
| 週次および月次のグループ化 |
週単位および月単位のディメンショングループは、コホートAPIでは使用できません。コホート管理画面を使用します。 |
| コホートAPIのデータ期間 |
|
| 日付 |
|