코호트 API

프리미엄

한눈에 보기: 코호트 리포팅 API는 광고주에게 코호트 데이터를 얻을 수 있는 프로그래매틱 방법을 제공합니다. API를 사용하여 코호트 데이터를 BI 및 마케팅 자동화 시스템에 통합합니다.

코호트 리포트 API

코호트 리포팅 API는 앱스플라이어 플랫폼에서 코호트 캠페인 성과 데이터를 가져오는 데 사용됩니다. 코호트 대시보드와 기능적으로 동일합니다. 

개발자를 위한 고려사항

  • 날짜: 날짜 또는 기간은 생애 가치(LTV) 날짜를 의미하며, 이는 활동 자체의 날짜가 아니라 사용자가 기여(전환)한 날짜를 의미합니다.
  • 부울 값: true 또는 false(대/소문자 구분).
  • 투명 및 불투명 에이전시 트래픽: 에이전시 기반 트래픽의 미디어 소스는 항상 원래 미디어 소스가 아닌 에이전시입니다. 현재 코호트의 UI 버전은 다르게 동작합니다. 
  • 단일 앱: 코호트 API는 단일 앱 솔루션입니다. 이는 단일 통화에서 여러 앱을 지원하는 코호트 대시보드와 대조됩니다. 
  • 데이터 최신성:  특성 및 제한 사항을 참조하십시오. 

API 지침

이 섹션에는 코호트 API를 생성하고 사용하는 데 필요한 정보가 포함되어 있습니다. 

코호트 API 정보

개요 API 호출은 경로(path), 헤더(header) 및 데이터 쿼리를 포함한 JSON 으로 구성됩니다. 기본적으로 데이터는 CSV 파일로 돌아옵니다.
경로

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

경로 파라미터(필수)
  • app_id: 앱스플라이어 대시보드에서 찾을 수 있는 앱 식별자입니다. 대시보드에 표시되는 대로 정확하게 삽입하세요.

쿼리 파라미터

(선택 사항)

결과는 CSV 또는 JSON으로 반환됩니다. CSV 파일 구조는 테이블 형식이지만 JSON 레코드 지향적입니다.

  • [기본값] csv 파일 이름은 쿼리에 따라 다릅니다.
  • json 쿼리 및 결과 섹션 포함
  • 예시: format=json
  • https://hq1.appsflyer.com/api/cohorts/v1/data/app/app_id?format=json
HTTP 메서드 POST
허용된 콘텐츠 유형 application/json
권한관리
날짜 제한
  • 지원되는 가장 최근 날짜는 현재 날짜의 730일 전입니다. 즉 2년)
  • 최대 쿼리 범위: 60일.
콜 수 제한
  • API 호출 속도 제한-분당 60개 호출 및 계정당 일일 50,000개 호출로 제한
  • 쿼리는 최대 30,000개의 행을 반환합니다.
부울 값 항상 소문자: true, false

요청 헤더

value 필수적
콘텐츠 유형 application/json 네 
Authorization 베어러 api_token_placeholder 네 
수락 application/json 네 

파라미터 필터링 및 그룹화

다음 필터 파라미터를 사용하여 필요한 데이터를 가져옵니다. 

파라미터 이름

설명 필수

cohort _type

코호트 어트리뷰션(전환) 유형은 다음 중 하나입니다. user_acquisition, , retargeting unified

  • Unified 는 사용자 확보 및 리타게팅 캠페인의 성과를 결합합니다.
  • 이벤트가 리타게팅 및 사용자 획득 캠페인 모두에 어트리뷰션된 경우 반환되는 KPI에는 리타게팅 이벤트만 포함됩니다(즉 , is_primary=true). 
  • 형식: 문자열(string)
  • 예시: "cohort_type": "user_acquisition"

min_cohort_size

최소 코호트 크기는 사용자가 적은 코호트를 제외하여 반환되는 레코드 수를 줄이는 데 사용됩니다. 이는 사용자 KPI의 값이 지정된 값보다 크거나 같다는 것을 의미합니다. 

  • 형식: Integer
  • 허용되는 최소값: 1. 0(영)을 보내지 않음
  • 기본값 : 1 
  • 예시: "min_cohort_size": 50
아니오

시작값 

LTV 어트리뷰션 날짜 기간의 하한입니다. 지원되는 가장 빠른 날짜는 현재 날짜 720일 전입니다. 

  • 형식: 스트링 yyyy-mm-dd
  • 예시: "from": "2020-01-02"

활용

LTV 어트리뷰션 날짜 기간의 상한입니다.

  • 기간 범위 내의 일 수: 1-31 일
  • 하루 동안: fromto 값은 동일합니다. 
  • 형식: yyyy-mm-dd
  • 예시: "from": "2020-01-01", "to": 2020-01-31는 31일입니다.

세분성

이전 72시간 동안의 시간별 세분성으로, 시간을 포함하도록 및 범위를 설정  "granularity": "hour" 및 설정합니다 from.to

  • 형식: yyyy-MM-dd hh:mm:ss
  • 예시:
"granularity": "hour", "from": "2021-12-01 14:00:00", "to": "2021-12-03 11:00:00",
아니오

partial_data

데이터 왜곡 및 오해를 피하기 위해 코호트는 전체 날짜의 데이터를 반환합니다. 그러나 부분 날짜의 데이터가 유용할 수 있습니다. 

쿼리에 대한 전체 코호트 일수는 오늘 날짜와 종료 날짜 간의 차이로 계산됩니다.

  • [기본값] false이면 전체 일 수가 반환됩니다.
  • true인 경우 불완전한 데이터가 있는 날을 포함하여 최대 180일의 코호트 일수가 반환됩니다. 
  • 형식: 부울
  • 플랫폼 UI 버전: false

예시: 5월 10일, 4월 1일부터 30일까지 전환한 사용자의 전체 코호트 일수는 10일입니다. 

  • false [기본값]인 경우 코호트 0-9일을 반환합니다. 마지막 전환 날짜와 오늘 사이의 일 수(10)입니다. 
  • true이면 코호트 1-40일이 돌아옵니다. 11-40일에는 부분 데이터가 포함되며 반환되지 않습니다. 예를 들어 4월 20일 이후 20일만 경과한 식입니다.

참고: 부분 데이터는 집계 유형이 누적인 경우에만 허용됩니다.

아니오

필터

반환된 데이터 및 기간(일)을 필터링합니다. 필터 차원 목록에서 필터를 선택합니다.

  • 형식: 중첩된 JSON의 문자열
  • 특정 지역에 대한 제한 예: "filters": {"geo": "US"} 미국에 귀속된 사용자만 포함합니다. 
  • 기간(코호트) 일 예: 필터는 period 측정값이 반환되는 일수를 설정합니다. 가능한 값은 0-180입니다.
  • 기본값: 기간 필터를 설정하지 않으면 0-30일, 60일, 90일 및 180일이 반환됩니다. 마침표가 있는 필터의 예
아니오

다음 그룹화 매개 변수를 사용하여 추가 열을 포함하고 보고서를 덜 세분화할 수 있습니다.

파라미터

필수

그룹화

  • 그룹화 차원 목록에서 1-7개의 그룹화를 선택합니다.
  • 형식: 배열의 문자열
  • Example: "groupings": ["af_ad", "c", "af_c_id", "af_prt"]

KPI 선택 및 서식 지정

  • 이 표에는 사용 가능한 KPI 및 관련 기능이 나열되어 있습니다. KPI를 호출하면 모든 함수가 반환됩니다.
  • 항상 반환되는 KPI는 사용자, ecpi 및 비용입니다 
  • 호출당 하나의 추가 KPI를 선택합니다.
    함수 (Function)
기본값/선택 사항  KPI(기준 이름)  횟수(Count) 전환율 (CVR) 평점 합계 (Sum) 고유 사용자
숫자 백분율 백분율 숫자 숫자
항상 사용자 Y - - - -
항상 eCPI - - Y - -
항상 비용 - - - Y -
선택 가능 "event_name"(4)  Y Y - Y (3) Y
선택 가능 수익 Y - - Y -
선택 가능 ROAS - - Y - -
선택 가능 ROI - - Y - -
선택 가능 세션(Sessions) Y - Y - Y (1)
선택 가능 제거 (2) Y - Y - -

(1) 고유 세션 수는 aggregation_type=on_day 일 때 리턴됩니다.

(2) cohort_type=통일된 경우 사용할 수 없습니다. 

(3) 합계는 이벤트에서 발생한 총 수익을 의미합니다. 보고서에서 이는 다음과 같이 표시됩니다. sum_event_name"

(4) 주의! 이벤트 이름은 대소문자를 구분합니다

파라미터

필수 파라미터

KPI

사용 가능한 KPI에서 하나의 KPI를 선택합니다. 앞으로는 여러 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

  • 누적
  • on_day

"aggregation_type": "cumulative"

Format: String

per_user

KPI 함수를 앱 사용자 수로 나눕니다. 관련 KPI에만 적용됩니다.

  • true인 경우 KPI 값을 코호트의 사용자 수로 나눕니다.
  • false인 경우 KPI 값을 사용자 수로 나누지 않습니다.
  • 형식: 부울
  • true인 경우의 예: 총 수익은 1000달러, 앱 사용자 수는 500명, 반환되는 값은 2달러입니다. 
아니오

차원 기준 그룹화 및 필터링 기준 목록

KPI(기준 이름) 

차원 API 값

그룹화

필터

Ad

af_ad

Y

Y

광고 아이디

af_ad_id

Y

Y

캠페인

C

Y

Y

캠페인 ID

af_c_id

Y

Y

채널

af_channel

Y

Y

Media Source (미디어 소스)

pid

Y

Y

Sub Param 1

af_sub1

Y

Y

키워드

af_keywords

Y

Y

에이전시

af_prt

Y

Y

변환 유형 (1) 

cohort_type

Y

Y

사이트 ID

site_id

Y

Y

수익 유형 (2)

revenue_type

Y

어트리뷰트된 터치 유형 (3)

attributed_touch_type

Y

Y

광고세트

af_adset

Y

Y

광고세트 ID

af_adset_id

Y

 Y

국가

지역

Y

Y

날짜(선택한 cohort_type 맥락에서 설치/리어트리뷰션/리인게이지먼트 날짜) 

날짜

Y

기간

마침표 

자세한 설명

 

X

Y

일러두기: 

치수 옵션:

(1) 변환 유형:  user_acquisitionretargeting(re-engagementre-attribution), unified

  • 내보낼 때:
    • re-engagement 다음과 같이 표시됩니다. retargeting
    • re-attribution 다음과 같이 표시됩니다. reattr

(2) 수익 유형: regular, ad_monetization

(3) 속성 터치 유형: click, , , TVimpressionpre-installed

curl 예시

이 예제에는 전체 API 호출이 포함되어 있습니다.


curl -L -X POST 'https://hq1.appsflyer.com/api/cohorts/v1/data/app/<insert your app_id here>?format=<insert results 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": [
            "Meta ads",
            "googleadwords_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"))
   

사용 사례

예제 1: 보존

7일, 14일, 28일에 1월에 앱을 설치한 사용자의 미디어 원본 보존(세션) 

{
  "per_user": 거짓,
  "그룹화": [
    "파이드"
  ],
  "필터": {
    "period": [
      7, 14, 28
    ]
  },
  "partial_data": 거짓,
  "aggregation_type": "on_day",
  "min_cohort_size": 1,
  "cohort_type": "user_acquisition",
  "보낸 사람": "2021-01-01",
  "받는 사람": "2021-01-30",
  "KPIS": [
    "세션"
  ]
}

예 2: 캠페인 구매

코호트 3일차 캠페인당 설치 후 매출

{  
  "per_user": 거짓,
  "그룹화": [
    "씨"
  ],
  "필터": {
    "period": [
      3
    ],
    "c":[
        "example_campaign_name"
    ]
  },
  "partial_data": 거짓,
  "aggregation_type": "누적",
  "min_cohort_size": 1,
  "cohort_type": "user_acquisition",
  "보낸 사람": "2021-01-01",
  "받는 사람": "2021-01-30",
  "KPIS": [
    "결제 시작"
  ]
}

예제 3: 어제 활동
특정 전환 기간 동안 전환(설치, 재참여, 재기여)한 사용자가 어제 어떤 활동을 수행했나요? 

데이터 락커용 코호트를 통해 사용할 수 있는 데이터를 사용합니다. 전환 기간은 이전 360일로 제한됩니다. 

 

추가 정보

응답 코드 및 문제 해결

응답 코드 

메시지

참고 

200 OK

유효한 데이터가 반환되었습니다.

200 OK
  • 데이터가 반환되지 않습니다.
    • 쿼리가 유효하지만 쿼리와 일치하는 데이터를 찾을 수 없습니다. 
    • 날짜 범위에 미래 날짜가 포함되어 있지 않은지 확인합니다.
    • 호출에서 토큰이 전혀 전송되지 않았습니다. 
401 Unauthorized
  • 권한 부여 토큰의 형식이 잘못되었습니다. 올바른 토큰을 사용하고 있는지 확인하고 길이가 700자 이상이어야 합니다.
404 Not found
  • 네트워크, 방화벽 등 관련 문제를 제거합니다. 
  • 가장 최근에 발급된 토큰을 사용하고 있는지 확인합니다. 대시보드에서 현재 토큰을 가져옵니다. 
  • 경로에 지정된 앱이 코호트 API를 사용할 수 있는 권한이 있는지 확인합니다. 구독 계획의 일부임을 의미합니다. 앱스플라이어 계정 관리자는 내 플랜에서 이를 확인할 수 있습니다. 
 422 처리할 수 없는 엔터티

이 오류 코드의 일반적인 원인은 다음과 같습니다.

  • 요청이 JSON에 포함되어 있고 쿼리 매개 변수로 전송되지 않았는지 확인합니다. 
  • JSON이 이 문서에 따라 형식이 지정되었는지 확인합니다.
  • 잘못된 날짜

CSV 파일 이름 구조

반환되는 CSV 파일에 할당된 이름은 API 쿼리에서 생성됩니다. 구조는 다음 표에 자세히 설명되어 있습니다.

CSV 파일 이름 예

cohort_aggregation_type__kpiper_user_보고서_app_id_fromtotimezonecurrencyhash.csv
변수 가능한 값
aggregation_type
  • on_day
  • 누적
per_user
  • per_user 
  • false: 널 
KPI 예: sessions
app_id 요청된 앱 ID
from 시작 날짜: YYYY-MM-DD형식
활용 현재 까지: YYYY-MM-DD형식
시간대 표준 시간대 기본값 UTC
currency 통화 코드 기본값 USD 
해시

영숫자 해시 문자열 길이=5

기간 필터 사용

기간은 어트리뷰션 이후의 날을 의미하며, 여기서 기간 0은 어트리뷰션 날짜입니다. 예를 들어 사용자가 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는 수익입니다.
  • 따라서 반환되는 데이터에는 다음이 포함됩니다.
    • 항상 반환되는 사용자, 비용 및 ecpi의 측정값 
    • 기간 0, 1 및 2를 의미하는 각 기간의 합계 및 개수로 구성된 수익 측정값입니다. 

쿼리

{
    "cohort_type": "user_acquisition",
    "min_cohort_size": 1,
    "preferred_timezone": 거짓,
    "보낸 사람": "2019-12-01",
    "받는 사람": "2020-01-01",
    "필터": {
        "period": [
            0,
            1,
            2
        ]
    },
    "aggregation_type": "on_day",
    "per_user": 거짓,
    "그룹화": [
        "파이드"
    ],
    "KPIS": [
        "수익"
    ]
}

로데이터

mceclip1.png

결과

mceclip0.png

API 매개변수에 대한 사용자 인터페이스 맵핑

다음 그림은 코호트 분석 사용자 인터페이스를 API 매개변수에 매핑합니다. API와 사용자 인터페이스의 두 솔루션은 비슷하지만 동일하지는 않습니다. 

API 버전에는 다음과 같은 추가 옵션이 있습니다.

  • 통화 선택
  • 시간대 선택
  • 기간별 필터링
코호트 매핑(CohortMapping).jpg 코호트매핑2.jpg

집계 형식 간의 차이점

CohortRevnueCumulative.jpg

특성과 제한 사항

항목 참고 
애드 네트워크 액세스

아니요. 캠페인 관리 파트너 는 광고주가 권한을 부여하는 경우 API를 사용할 수 있습니다. 

에이전시 액세스 아니오
에이전시 투명성 지원 안 됨.
앱 별 시간대
앱별 통화 
사이즈 제한 없음
콜 수 제한

API 호출 속도 제한: 계정당 분당 60개 호출 

오가닉 데이터 사용 가능
논오가닉 데이터 사용 가능
비용 데이터 제한
  • 비용 데이터는 최소 1회 이상의 인스톨이 기록된 캠페인에만 적용됩니다.
  • 앱스플라이어는 코호트 리포트나 코호트 API에 있는 대문자를 포함한 검색어에 대한 비용 데이터를 제공하지 않습니다.
  • 일부 그룹화 조합은 비용과 결합할 수 없습니다. 예를 들어 Meta 광고에는 지역 그룹이나 채널 그룹 중 하나만 포함될 수 있습니다. 그룹화의 정확한 조합은 광고 네트워크에 따라 다릅니다.
데이터 최신성

데이터 새로 고침은 다음과 같이 partial_data 따라 달라집니다. 

  • [기본값] false인 경우 매일
  • true이면 연속(실시간)
  • 비용 및 제거 지표는 모든 인스턴스에서 매일 업데이트됩니다.
과거 데이터 일일 코호트: 2년
계정 사용자 액세스 권한 부여 토큰은 대시보드에서 관리 사용자가 사용할 수 있습니다
광고 수익

af_ad_revenue 이벤트의 경우 2022년 10월 5일에서 2023년 2월 16일 사이의 날짜에 대해 집계 유형이 "당일"인 경우 고유 사용자 메트릭을 사용할 수 없습니다.

주간 및 월간 그룹화

주간 및 월간 차원 그룹화는 코호트 API에서 사용할 수 없습니다. 코호트 대시보드를 사용합니다.

코호트 API
  • 변환 기간을 0(시간 0 또는 일 0)이라고 합니다. 변환 후 다음 기간을 1(1시간 또는 1일) 등으로 지칭합니다.
  • 앱스플라이어에서 코호트 기간은 특정 인스톨 타임스탬프를 고려하지 않습니다. 오히려 코호트 시간은 가장 가까운 시간으로 반올림되고 코호트 일수는 달력 날짜를 기준으로 합니다. 이로 인해 앱스플라이어 코호트 데이터를 다른 네트워크의 코호트 데이터와 비교할 때 불일치가 발생할 수 있으며, 여기서 모든 코호트 기간은 특정 설치 타임스탬프에 의해 결정됩니다(즉, 한 시간은 설치 타임스탬프 후 60분, 하루는 설치 타임스탬프 후 24시간 설치 후 기간입니다).