한눈에 보기: 코호트 API는 광고주가 프로그래밍을 통해 코호트 데이터를 얻을 수 있도록 지원합니다. API를 사용하여 코호트 데이터를 BI 및 마케팅 자동화 시스템에 연동합니다.
코호트 API
코호트 API는 앱스플라이어 플랫폼에서 코호트 캠페인 성과 데이터를 가져오는 데 사용됩니다. 코호트 대시보드와 기능적으로 동일합니다.
코호트 및 리텐션을 사용하려면, 확인하고자 하는 데이터를 정의하세요. 앱에서 사용자를 선택하고 전환 시간에 따라 세분화합니다. 수익, ROI, 이벤트 전환율과 같은 코호트 분석 지표를 사용할 수 있습니다. 캠페인이나 미디어소스 같은 기준으로 코호트를 나누어 비교합니다. 결과는 CSV 또는 JSON 파일로 반환됩니다. 이렇게 하여 사용자 또는 캠페인의 라이프 사이클에 걸친 패턴이나 성과 변화를 발견할 수 있습니다.
코호트 사용 사례를 참조하세요.
Cohort API를 사용하려면:
-
API 토큰을 받으세요. 관리자가 토큰을 가져와야 합니다.
- 인증 헤더에 사용할 API 토큰을 귀사의 개발자에게 제공하세요.
- 다음 섹션에서 설명된 대로, API 호출 시 개발자가 입력해야 할 파라미터를 제공하세요. 여기서 파라미터는 리포트의 초점, 구성 방식 및 보고 기간을 결정합니다.
- 개발자에게 개발자 허브에서 코호트 API 지침을 따르도록 안내하십시오.
코호트 API 파라미터
다음 파라미터를 사용하여 필요한 데이터를 가져옵니다.
| 파라미터 이름 | 설명 | 필수 여부 |
|---|---|---|
| bearer | API 인증 헤더에 사용되는 API 토큰. | 예 |
| cohort _type | 코호트 어트리뷰션(전환) 유형은 다음 중 하나입니다: user_acquisition, retargeting, unified
|
예 |
| min_cohort_size | 최소 코호트 사이즈는 사용자 수가 적은 코호트를 제외하여 반환되는 기록 수를 줄이는 데 사용됩니다. 이것은 “사용자(users)” KPI가 지정된 값과 같거나 그보다 크다는 것을 의미합니다.
|
아니오 |
| from | LTV 어트리뷰션 날짜 범위의 하한값을 나타냅니다. 지원되는 가장 이른 날짜는 현재 날짜 기준 720일 전입니다.
|
예 |
| to | LTV 어트리뷰션 날짜 범위의 상한값을 나타냅니다.
|
예 |
| granularity |
이전 72시간 동안의 시간별 세분화를 위해, 날짜 뿐 아니라 시간까지 포함하도록
|
아니오 |
| partial_data |
데이터 왜곡 및 오해를 방지하기 위해 코호트는 완료된 날의 데이터를 반환합니다. 그러나, 부분 날짜의 데이터가 유용할 수 있습니다. 쿼리에 대한 완료 코호트 일수는 오늘 날짜와 to 날짜 간의 차이로 계산됩니다.
예시: 5월 10일을 기준으로, 4월 1일부터 30일까지 전환한 사용자의 완료 코호트 일수는 10일입니다.
참고: 부분 데이터는 집약 유형이 누적인 경우에만 허용됩니다. |
아니오 |
| 필터 | 반환된 데이터 및 기간(일)을 필터링합니다. 필터 기준 목록에서 필터를 선택합니다.
|
아니오 |
| 그룹화 |
|
예 |
| KPI | KPIs는 앱의 동작에 대한 인사이트를 얻기 위해 사용하는 지표입니다. KPI를 선택하고 형식을 설정하는 방법에 대해 알아보세요. | 예 |
| preferred_currency | 반환되는 KPI의 형식을 설정하는 파라미터 입니다. KPI 형식을 설정하는 방법에 대해 알아보세요. | 아니오 |
| preferred_timezone | 반환되는 KPI의 형식을 설정하는 파라미터 입니다. KPI 형식을 설정하는 방법에 대해 알아보세요. | 아니오 |
| aggregation_type | 반환되는 KPI의 형식을 설정하는 파라미터 입니다. KPI 형식을 설정하는 방법에 대해 알아보세요. | 예 |
| per_user | 반환되는 KPI의 형식을 설정하는 파라미터 입니다. KPI 형식을 설정하는 방법에 대해 알아보세요. | 아니오 |
KPI 선택 및 서식 지정
- 이 표에는 사용 가능한 KPI 및 관련 기능이 나열되어 있습니다. KPI를 호출하면 모든 함수가 반환됩니다.
- 다음 KPI는 항상 반환됩니다: user, ecpi 및 cost
- 호출당 하나의 추가 KPI를 선택합니다.
- 요청된 각 KPI에 대해 모든 함수가 반환됩니다.
- 형식: Strings in an array (배열의 문자열)
- 예시 A:
"kpis": ["sessions"] - 예시 B:
"kpis": ["event_name"]
- 예시 A:
| 함수 (Functions) | ||||||
|---|---|---|---|---|---|---|
| 기본값/선택 사항 | KPI(데이터 기준 이름) | 횟수(Count) | 전환율 (CVR) | 비율 | 합계 (Sum) | 고유 사용자 |
| 숫자 | 백분율 | 백분율 | 숫자 | 숫자 | ||
| 항상 | users | 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) 합계(Sum)는 이벤트에서 발생한 총 수익을 의미합니다. 리포트에서 해당 부분은 (4) 주의! 이벤트 이름은 대소문자를 구분합니다. | ||||||
KPI 기능 형식 설정하기
다음 파라미터로 반환되는 KPI의 형식을 설정합니다.
| 파라미터 | 값 | 필수 여부 |
|---|---|---|
| preferred_currency | KPI 수익 통화
|
아니오 |
| preferred_timezone |
데이터 범위의 시간대
|
아니오 |
| aggregation_type |
|
예 |
| per_user | KPI 함수를 앱 사용자 수로 나눕니다. 관련된 KPI에만 적용됩니다.
|
아니오 |
그룹화 및 데이터 기준 필터
| 데이터 기준 이름 | 데이터 기준 API 값 | 그룹화 | 필터 |
|---|---|---|---|
| Ad | af_ad | Y | Y |
| Ad ID | af_ad_id | Y | Y |
| Campaign | c | Y | Y |
| Campaign ID | af_c_id | Y | Y |
| Channel | af_channel | Y | Y |
| Media Source | pid | Y | Y |
| Sub Param 1 | af_sub1 | Y | Y |
| Keywords | af_keywords | Y | Y |
| Agency | af_prt | Y | Y |
| Conversion Type (1) | cohort_type | Y | Y |
| 사이트 ID | site_id | Y | Y |
| 수익 유형 (2) | revenue_type | x | Y |
| Attributed Touch Type (3) | attributed_touch_type | Y | Y |
| 광고 세트 | af_adset | Y | Y |
| 광고 세트 ID | af_adset_id | Y | Y |
| 국가 | geo | Y | Y |
| 날짜(인스톨/리어트리뷰션/선택한 cohort_type 컨텍스트에서 리인게이지먼트 날짜) | date | Y | x |
| 기간 |
period
|
x | Y |
|
참고: 데이터 기준 옵션: (1) 전환 유형:
(2) 수익 유형: (3) 어트리뷰트된 터치 유형: | |||
추가 정보
기간 필터 사용
기간은 어트리뷰션 이후의 날을 의미하며, 여기서 기간 0은 어트리뷰션 일입니다. 예를 들어, 사용자가 1월 1일에 앱을 설치했습니다. 여기서 1월 1일은 어트리뷰션 일입니다. 기간 0에 구매한 경우 1월 1일에 구매했음을 의미합니다. 기간 3에 구매한 경우 1월 4일에 구매했음을 의미합니다. 같은 맥락에서, 1월 11일에 설치하는 사용자는 이 기간이 0입니다. 1월 14일에 이루어진 구매는 기간 3으로 표시됩니다.
리포트 날짜 범위가 1월 1일부터 1월 11일까지인 경우, 이 기간 동안 어트리뷰트(설치)한 사용자가 리포트에 포함됩니다. 다른 데이터는 포함되지 않습니다.
- 기간의 값은 다음 0-180 중 하나 이상일 수 있습니다. 예시: 0, 1, 2, 30, 180
- 기간을 지정하지 않으면 0, 1, 2 등의 기본값에서 30, 60, 90 및 180이 반환됩니다.
기간 필터의 예시
- 이 예시에는 JSON 쿼리 파라미터, 로데이터 및 결과 CSV 파일이 포함되어 있습니다.
- 쿼리는 0, 1 및 2 기간을 필터링하고, 여기서 선택한 KPI는 수익입니다.
- 쿼리는 집약 유형을 “누적”으로 지정합니다. 당일 데이터를 원할 경우, "on_day"로 변경하면 됩니다.
- 그 결과, 반환되는 데이터에는 다음이 포함됩니다.
- 항상 반환되는 유저, 비용 및 eCPI의 측정값
- 각 기간(즉, 기간 0, 1, 2)에 대한 합(sum)과 횟수(count)로 구성된 수익 측정값
쿼리
{
"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": "cumulative",
"per_user": false,
"groupings": [
"pid"
],
"kpis": [
"revenue"
]
}
로데이터
결과
특징 및 제약 사항
| 특징 | 비고 |
|---|---|
| 애드 네트워크 액세스 | 아니요 |
| 에이전시 액세스 | 아니오 |
| 에이전시 투명성 | 지원되지 않습니다. 에이전시 주도의 트래픽의 미디어 소스는 항상 원래의 미디어 소스가 아닌 에이전시입니다. |
| 특정 앱 시간대 | 예 |
| 앱별 통화 | 예 |
| 사이즈 제한 | 없음 |
| 속도 제한 |
|
| 오가닉 데이터 | 사용 가능 |
| 논오가닉 데이터 | 사용 가능 |
| 비용 데이터 제한 |
|
| 데이터 최신성 | 데이터 새로 고침은 다음과 같이 partial_data에 따라 달라집니다. |
| 과거 데이터 | 일일 코호트: 2년 |
| 계정 유저 액세스 | 권한 부여 토큰은 대시보드에서 관리자 유저가 사용할 수 있습니다 |
| 광고 수익 | af_ad_revenue 이벤트의 경우, 집약 유형이 다음과 같을 때 고유 사용자 지표가 제공되지 않습니다.
|
| 주간 및 월간 그룹화 | 주간 및 월간 데이터 기준 그룹화는 코호트 API에서 사용할 수 없습니다. 코호트 대시보드를 사용합니다. |
| 코호트 API 기간 |
|
| 날짜 |
|
| 재설치 |
|
| 파트너를 위한 코호트 API | 마케팅 파트너를 위한 코호트 API에 대한 접근은 2024년 9월 15일부터 사용 중단됩니다. 마케팅 파트너는 고객 데이터에 지속적으로 접근할 수 있도록 데이터 락커를 활성화하는 것을 권장합니다. |