TUNE Aggregate Exports & API

Overview

📘

ex-TUNE 클라이언트 전용

This feature is currently only available for ex-TUNE clients and replicates the TUNE endpoints available via https://api.mobileapptracking.com/v2/advertiser/stats/actuals/export.

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 액세스

In order to access Aggregate Exports, a user will need to have both Aggregate Data andExport access.

1248

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. In the left-hand navigation, under Setup & Testing, click on Account Settings.
  2. On the Account Settings page, click on the Agencies tab.
  3. Expand the agency in question, find the agency team member you want to give access to, hover on the button in the Actions column and click Edit.
  4. In the Edit Agency Team Member modal:
    1. Under Access Level, check the Export box.
    2. Under Permissions, check the Aggregate Data box.
  5. 선택 사항: 데이터 필터 추가
    1. Under Data Filters, toggle any necessary data filters on/blue. Exported data will be filtered accordingly.
  6. Save를 클릭합니다.
1242

🚧

대행사 태그 데이터

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

추출가능한 토픽

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

  • Click
  • Events
  • Impressions
  • Install
  • Open
  • Revenue USD

📘

정보

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

🚧

IP와 위치정보의 불일치

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

추출가능한 필드

Tune Field

TUNE 인간 판독형

ad_network_id

Ad Network ID

ad_network.name

Ad Network Name

advertiser_id

Advertiser ID

advertiser.name

Advertiser Name

advertiser_sub_ad.name

My Ad Name

advertiser_sub_ad.ref

My Ad Ref

advertiser_sub_adgroup.name

My AdGroup Name

advertiser_sub_adgroup.ref

My AdGroup Ref

advertiser_sub_campaign.name

My Campaign Name

advertiser_sub_campaign.ref

My Campaign Ref

advertiser_sub_keyword.name

My Keyword Name

advertiser_sub_keyword.ref

My Keyword Ref

advertiser_sub_placement.name

My Placement Name

advertiser_sub_placement.ref

My Placement Ref

advertiser_sub_publisher.name

My Publisher Name

advertiser_sub_publisher.ref

My Publisher Ref

advertiser_sub_site.name

My Site Name

advertiser_sub_site.ref

My Site Ref

country.code

Country Code

device_type

Device Type

publisher_sub_ad.name

Publisher Sub Ad Name

publisher_sub_ad.ref

Publisher Sub Ad Ref

publisher_sub_adgroup.name`

Publisher Sub AdGroup Name

publisher_sub_adgroup.ref

Publisher Sub AdGroup Ref

publisher_sub_campaign.name`

Publisher Sub Campaign Name

publisher_sub_campaign.ref

Publisher Sub Campaign Ref

publisher_sub_keyword.name

Publisher Sub Keyword Name

publisher_sub_placement.name

Publisher Sub Placement Name

publisher_sub_publisher.name

Publisher Sub Publisher Name

publisher_sub_site.name

Publisher Sub Site Name

site_id

Site ID

timestamp

Timestamp

wurfl_device_os

Device OS

wurfl_model_name

Model Name

attributed

Attributed

🚧

중단된 필드

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

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

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

예시 site_event.id will now be exported as site_event_id.

추출작업 Request 빌드

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

추출작업 Request 빌드

유형

필수

설명

api_key

String

Y

Your API Key

start_date

날짜

Y

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

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

end_date

날짜

Y

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

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

filter

필터

N

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

fields

쉼표로 구분된 목록

Y

List of comma-separated fields from the LogInstalls model desired in results. Defaults to display all fields

limit | 정수

Y

Limit the number of items returned per request. Maximum allowed value is 2 million. If more than 2 million records are required, please make multiple requests with smaller time intervals to pull the data needed in “batches”;

sort

정렬

N

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

선택 파라미터

group

배열

N

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

timestamp

String

N

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

선택 파라미터.

format

널(Null) 가능 string

N

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

response_timezone

시간대

N

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

샘플 내보내기 요청

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

Y

Your TUNE Advertiser ID

api_key

String

Y

Your API Key

handle

String

Y

The ID returned by the log export queue.

샘플 리포트 상태 요청

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
  }
]