TUNE Aggregate Exports & API

Overview

📘

ex-TUNE 클라이언트 전용

해당 기능은 현재 ex-TUNE 클라이언트에서만 사용할 수 있으며 https://api.mobileapptracking.com/v2/advertiser/stats/actuals/export를 통해 사용할 수 있는 TUNE 엔드 포인트를 복제합니다.

Branch Aggregate Exports는 내보내기 검색 기준과 매치하는 합산 데이터를 찾아 큐에 넣습니다. 모바일 앱과 관련된 각 어트리뷰션에 대한 개별 로그가 포함된 커스텀 Export와 달리 Aggregate Exports에서는 관심 있는 데이터를 사용자 지정하여 가시화할 수 있습니다.

🚧

iOS 14.5 이후 데이터 변경

Apple requires users to opt into sharing their device data through Apple's AppTrackingTransparency framework. When an install is attributed to paid ads, a 2nd install event will fire post user opt-in

Opt-ins will affect your final install count. Our recommendation is to delay pulling aggregate data for as long as you are allowing opt-ins.

For additional information on changes post iOS 14.5, visit our FAQ Pages

권한인증

Aggregate Export API의 호출은 각 요청과 함께 api_key 쿼리 string 파라미터를 전달해야 합니다. API 키는 유저 별로 생성되며 영구적입니다.

Learn how to retrieve your API key (a.k.a. Access Token)

🚧

Organization Level 액세스 필요

API 키/액세스 토큰을 검색하거나 재설정하려면 계정의 Organization Level에 대한 액세스 권한이 있어야 합니다. 해당 기능은 앱 레벨에 없습니다.

호출빈도 및 데이터에 대한 제한

사용량 제한

사용량 제한은 호출하는 엔드 포인트에 따라 다릅니다.

추출 상태를 만들고 확인하기 위한 비율 제한은 다음과 같습니다.

  • 초당 요청 2개
  • 분당 요청 10개
  • 시간당 1000

데이터 제한

  • 동기식 엔드포인트에서 최대 5천행으로 제한됨
  • 비동기 엔드포인트에서 최대 1만행으로 제한됨
  • 추출일로부터 180 일 전까지 쿼리할 수 있습니다.
    • 더 많은 레코드가 필요한 경우 요청당 조회기간을 더 짧게 설정하여 여러번으로 나누어 추출할 것을 권장합니다.
  • 단일 dimension(예 : 캠페인, 광고 소재명 등)에 대해 최대 40,000 개의 고유한 값만 검색할 수 있습니다.

Date range limits

  • For data older than 7 days, all data is rolled up by day, according to your app's timezone. For the most recent 7 days, it is possible to query intra-day data.

Custom Exports 액세스

Aggregate Exports에 액세스하려면 유저에게 Aggregate DataExport 액세스 권한이 모두 있어야 합니다.

12481248

For more details on how to give a user the required access, please read Default Access Levels, Users Roles & Permissions.

써드파티 액세스

계정의 API 키에 접근할 수 있는 모든 사용자는 Branch의 Custom Exports API (및 필터링을 거치지 않은 로그 레벨 데이터)에 접근할 수 있습니다. 따라서 써드파티를 Branch대시보드의 사용자로 초대할 때 API키를 열람할 수 있는 권한을 제공하지 않는 것이 좋습니다.

에이전시/파트너 API 액세스 제공

광고 캠페인을 운영하는 에이전시와 협력하며 후속 데이터를 내보낼 수 있는 액세스 권한을 부여하려는 경우 커스텀 Export API에 대한 액세스 권한을 제공할 수 있습니다. 대행사와 협력하여 광고 캠페인을 운영하고 이를 통해 발생한 데이터에 대한 추출할 수 있게 한다면 Custom Exports API에 대한 접근권한을 제공할 수 있습니다.

대행사에게 Custom Exports API에 대한 접근권한을 제공하려면 다음과 같이 진행할 수 있습니다.

  1. 왼쪽 메뉴의 Setup & Testing에서 Account Settings을 클릭합니다.
  2. Account Settings 페이지에서 Agencies 탭을 클릭합니다.
  3. 해당 대행사의 맴버 리스트를 펼친후 접근권한을 부여할 대행사 맴버를 찾은 다음 Actions 컬럼의 아이콘으로 마우스를 옮긴 다음 Edit을 클릭합니다.
  4. Edit Agency Team Member 선택창에서 다음을 실행합니다.
    1. Access Level에서 Export 박스를 체크합니다.
    2. Permissions에서 Aggregate Data 박스를 체크합니다.
  5. 선택 사항: 데이터 필터 추가
    1. Data Filters 아래의 각 항목에서 토글을 푸른색으로 전환하는 것을 통해 해당 대행사 맴버가 필요한 데이터만 추출할 수 있도록 필터링할 수 있습니다.
  6. Save를 클릭합니다.
12421242

🚧

대행사 태그 데이터

Only show agency-tagged data 데이터 필터를 활성화하지 않은 경우 에이전시 팀원은 캠페인의 관련 여부에 관계없이 모든 캠페인과 관련된 합산 데이터를 내보낼 수 있습니다.

추출가능한 토픽

Aggregate Export API를 통해 다음 로그 토픽을 사용할 수 있습니다.

  • Clicks
  • Events
  • Impressions
  • Installs
  • Opens
  • Revenue USD

📘

정보

Branch는 자주 사용하지 않는 토픽인 update 및 postbacks TUNE 토픽의 추출을 지원하지 않습니다.

🚧

IP와 위치정보의 불일치

IP로 위치를 분석할 수 없는 매우 적은 비율의 이벤트에 대해서는 국가 및 도시와 같은 지리 데이터를 사용하지 못할 수 있습니다.

추출가능한 필드

Tune 필드TUNE 인간 판독형
ad_network_idAd Network ID
ad_network.nameAd Network Name
advertiser_idAdvertiser ID
advertiser.nameAdvertiser Name
advertiser_sub_ad.nameMy Ad Name
advertiser_sub_ad.refMy Ad Ref
advertiser_sub_adgroup.nameMy AdGroup Name
advertiser_sub_adgroup.refMy AdGroup Ref
advertiser_sub_campaign.nameMy Campaign Name
advertiser_sub_campaign.refMy Campaign Ref
advertiser_sub_keyword.nameMy Keyword Name
advertiser_sub_keyword.refMy Keyword Ref
advertiser_sub_placement.nameMy Placement Name
advertiser_sub_placement.refMy Placement Ref
advertiser_sub_publisher.nameMy Publisher Name
advertiser_sub_publisher.refMy Publisher Ref
advertiser_sub_site.nameMy Site Name
advertiser_sub_site.refMy Site Ref
country.codeCountry Code
device_typeDevice Type
publisher_sub_ad.namePublisher Sub Ad Name
publisher_sub_ad.refPublisher Sub Ad Ref
publisher_sub_adgroup.namePublisher Sub AdGroup Name
publisher_sub_adgroup.refPublisher Sub AdGroup Ref
publisher_sub_campaign.namePublisher Sub Campaign Name
publisher_sub_campaign.refPublisher Sub Campaign Ref
publisher_sub_keyword.namePublisher Sub Keyword Name
publisher_sub_placement.namePublisher Sub Placement Name
publisher_sub_publisher.namePublisher Sub Publisher Name
publisher_sub_site.namePublisher Sub Site Name
site_idSite ID
timestampTimestamp
wurfl_device_osDevice OS
wurfl_model_nameModel Name
attributedAttributed

🚧

중단된 필드

일부 필드는 고객에게 제공할 수 있는 가치가 상당히 제한되어 있어 사용이 중단되었습니다. 중단된 필드는 Custom Exports API를 통해 사용할 수 없습니다. 문의 사항이 있으면 CSM 또는 서포트팀에 연락하시기 바랍니다.

데이터 객체에 필드가 포함되는 경우

관련 객체는 더 이상 마침표 ( . )를 사용하여 객체의 프로퍼티에 액세스하지 않습니다. 대신 필드 이름은 밑줄 ( _ ) 만 사용합니다.

예를 들어 site_event.id은 이제 site_event_id로 추출하게 됩니다.

추출작업 Request 빌드

추출조건에 맞는 로그를 찾을 수 있도록 request를 빌드합니다. response로 작업상태를 확인하고 완료시 로그를 다운로드할 수 있는 status url 을 받게 됩니다.

추출작업 Request 빌드

api_key | String

API 키. 필수

start_date | Date

The beginning datetime for the requested results, provided in ISO-8601 format. ; REQUIRED

오프셋이 없는 날짜(즉, 시간대)의 기본값은 시간대 파라미터에 대해 제공된 값으로 설정됩니다. 시간대 파라미터가 지정되지 않았다면 날짜 시간대의 기본값은 UTC로 설정됩니다. 날짜는 반드시 지난 120일 이내여야 합니다. 예: 2016-01-01T00:00:00Z

end_date | Date

The end datetime for the requested results, provided in ISO-8601 format. ; REQUIRED

오프셋이 없는 날짜(즉, 시간대)의 기본값은 시간대 파라미터에 대해 제공된 값으로 설정됩니다. 시간대 파라미터가 지정되지 않았다면 날짜 시간대의 기본값은 UTC로 설정됩니다. 예: 2016-01-01T23:59:59Z

filter | Filter

Actuals 엔드 포인트의 필드에 대해 필드 및 불 연산자(boolean operator)로 필터링합니다. 예: &filter=(mat_id="3bc15517-92d5-4b7f-9837-e9a30d6fb9b8")+AND+("site_event_id"=1844998705)

fields | Comma Separated List

결과에서 LogInstalls 모델의 쉼표로 구분된 원하는 필드 목록. 기본값일 때 모든 필드를 표시합니다. 필수

limit | Integer

추출작업 요청당 반환되는 로그의 행수제한을 설정합니다. 최대 허용값은 2백만행입니다. 만약 필요한 로그가 200만행을 초과하면 요청당 조회기간을 더 짧게 설정하여 여러번으로 나누어 추출할 것을 권장합니다. 필수

sort | Sort

필드 뒤에 방향(asc 또는 desc)이 옵니다. 결과는 여러 필드와 방향으로 정렬될 수 있습니다.

선택 파라미터

group | Array

선택한 필드에서 반환된 그룹 항목.

timestamp | String

타임 스탬프로 통계 분석 설정. 선택 옵션: 시간, 날짜/시간, 날짜, 주, 월.

선택 파라미터.

format | Nullable String

응답 형식은 JSON 또는 CSV 일 수 있습니다. 선택하지 않으면 기본값은 CSV입니다.

response_timezone | Timezone

결과 날짜가 전달되는 시간대로 기본값은 계정에 설정된 시간대입니다.

샘플 내보내기 요청

https://api.mobileapptracking.com/v2/advertiser/stats/actuals/export.json?api_key=4c5b6461026cb0caff3c66bef881b4af&start_date=2018-08-01+00%3A00%3A00&end_date=2018-08-18+00%3A00%3A00&fields[]=opens&fields[]=installs&fields[]=events&fields[]=publisher_sub_adgroup_id&fields[]=publisher_sub_campaign_id&timestamp=date&format=json

추출작업 요청에 대한 응답 샘플

{
  "status_code": 200,
  "response_size": "334",
  "throttle": {
    "decision": "Permit",
    "decision_authority": "Endpoint",
    "decision_state": "Always Permit",
    "object_key": "/advertiser/stats/actuals/export",
    "virtual_record": false,
    "next_reset": "N/A",
    "count_remaining": 0,
    "limit": 0,
    "interval": 0
  },
  "data": {
    "job_id": "5a494d8b-e5f9-4561-b71d-5c5ee4ed087d"
  }
}

작업상태 확인 및 결과 다운로드 요청

작업상태를 확인하고 완료시 로그 다운로드 파일의 링크를 제공받을 수 있습니다. (추출작업 요청시 응답받은 handle 값으로 어떤 추출작업인지 식별가능)

advertiser_id | String

TUNE 광고주 ID. 필수

api_key | String

API 키. 필수

handle | String

추출작업 요청시 응답받은 handle 파라미터 값 필수

샘플 리포트 상태 요청

https://api.mobileapptracking.com/v2/export/download.json?api_key=REMOVED&job_id=5a494d8b-e5f9-4561-b71d-5c5ee4ed087d

샘플 리포트 상태 응답

{"status_code":200,"response_size":"437","data":{"status":"complete","percent_complete":100,"data":{"format":"json","url":"https:\/\/s3.amazonaws.com\/hasdevfiles\/9da89700-ee8e-42f1-932f-7b9459a614dd.json?response-content-disposition=attachment%3B%20filename%3D%229da89700-ee8e-42f1-932f-7b9459a614dd.json%22&AWSAccessKeyId=AKIAIHT2RGXNQAIUT7ZA&Expires=1547654522&Signature=mfXJ7fGZeZZ%2FYPnEHssGopvdpxk%3D"},"report_schedule_id":null}}

샘플 다운로드 리포트

curl 'https://s3.amazonaws.com/hasdevfiles/3bce2890-97c8-44e0-985b-9c5505b7ec4a.json?response-content-disposition=attachment%3B%20filename%3D%223bce2890-97c8-44e0-985b-9c5505b7ec4a.json%22&AWSAccessKeyId=AKIAIHT2RGXNQAIUT7ZA&Expires=1535997897&Signature=v9WhAulFDVmfaR%2FzAg3uvh8DVAc%3D'

샘플 리포트

[
  {
    "publisher_sub_campaign_id": "975222707",
    "publisher_sub_adgroup_id": "666119300",
    "installs": 0,
    "opens": 0,
    "events": 0
  },
  ...
  {
    "publisher_sub_campaign_id": "0",
    "publisher_sub_adgroup_id": "0",
    "installs": 12,
    "opens": 13,
    "events": 31
  }
]

이 페이지가 도움이 되었습니까?