내부 BI 또는 마케팅 성과 대시보드로 집계 데이터를 수집할 수 있고, 마케팅 캠페인에 대한 집계 데이터를 제공하는 Singular 리포팅 API에 오신 것을 환영합니다.

본 가이드는 Singular 리포팅 API, 이용 사례에 대한 이해 방법, 쿼리 실행 방법에 관해 설명합니다. 

Read 본 가이드를 먼저 참고한 후, 테크니컬한 세부 사항에 관해서는 리포팅 API 레퍼런스를 참고하세요.  

해당하는 이용 사례 이해하기  

Singular는 여러 곳으로부터 오는 데이터를 모아 종합합니다. (Understanding Singular 리포팅 데이터 이해하기 편을 통해 자세한 내용을 확인하세요)

리포팅 API를 사용할 때, 다음 중 보고자 하는 데이터를 선택할 수 있습니다. 

• 캠페인 지출과 같은, 파트너 매체와 에이전시로부터 가져오는 집계데이터
• BI 시스템에 수집할 수 있고 필요한 경우 매체 데이터와 종합할 수 있는, 어트리뷰션 트래커(attribution tracker/MMP)에서 가져오는 집계데이터 
• 또는, 가능한 가장 높은 세분화 값 내 ROI 분석을 위해, 매체와 트래커 데이터를 스마트하게 합친 종합 데이터 

모든 쿼리들은 동일한 엔드포인트 (비동기 리포트 생성)을 실행하는 반면, 쿼리 내 포함하는 필드들은 상이합니다. 

시작하기 전, API를 통해 얻을 수 있는 데이터에 관해 확인하세요. 

이용 사례	참고 문헌:
Singular를 통해 캠페인 데이터를 광고매체와 에이전시로부터 수집하세요.  비용과 기동률(run rates)에 관한 데이터를 얻을 수 있습니다.	네트워크 데이터 쿼리
Singular의 어트리뷰션 서비스 또는 제3의 어트리뷰션 트래커를 통해 데이터 커넥터를 설정하세요.  컨버전과 매출 같은 트래커 데이터로부터 추출하여 귀사의 BI 플랫폼 또는 분석에 사용할 수 있습니다.  만약 ROAS 계산을 위해 광고 매체 데이터(예를 들어 캠페인 비용)와 트래커 데이터를 함께 사용한다면, 귀사의 툴을 직접 사용하여 계산하세요.	트래커 데이터와 네트워크 데이터를 따로 쿼리
Singular 어트리뷰션 서비스 또는 제3의 어트리뷰션 트래커를 데이터 커넥터로 사용합니다. Singular가 미리 만든 로직을 이용하여 매체와 협업하고 가장 강력한 세분성을(granularity) 이용한 트래커 데이터를 사용하실 수 있습니다.	통합 데이터 쿼리

리포팅 API를 통해 제공되는 데이터 유형

매체 데이터 쿼리하기

매체 데이터는 Singular에 등록한 모든 매체로부터 수집된 캠페인 통계를 포함합니다. 그 데이터는 (Singular에서 설정했더라도) 어트리뷰션 트래커로부터의 데이터를 포함하지 않습니다.

예를 들어, 주어진 날짜 범위안에서 각 캠페인(adn_campaign_id)의 코스트(adn_cost)를 보기 위한 쿼리를 실행할 수 있습니다. 

매체 데이터에서 확인할 수 있는 필드

각 필드를 설명한 메트릭과 디멘션 페이지를 참고하세요.

트래커 데이터와 매체 데이터를 따로 쿼리하기

API를 사용하여 트래커 데이터를 가져올 수 있습니다 - Singular의 어트리뷰션 서비스의 통계 또는 설치하신 제3의 어트리뷰션 트래커를 사용합니다. (예를 들어 Appsflyer 또는 Google Analytics)

예를 들어, 주어진 날짜 범위 내 각 캠페인(tracker_campaign_id)에 따른 클릭(tracker_clicks)과 인스톨(tracker_installs)을 보기 위해 쿼리를 할 수 있습니다. 트래커 데이터는 또한 인스톨 후 이벤트들과 매출을 포함합니다.

트래커 데이터에 쿼리를 진행하려면, 쿼리를 매체 데이터에 연결하여 캠페인 CPI 또는 ROI를 계산할 수 있습니다.

하지만, 보통의 경우 통합된 리포트를 실행하는 것이 같은 결과를 조금 더 쉽게 얻는 방법입니다.

트래커 데이터에서 확인할 수 있는 필드 

각 필드에 관하여 더 많은 설명을 보려면 메트릭과 디멘션 페이지를 참고하세요.

통합 데이터 쿼리하기

API를 사용하여 매체와 트래커 데이터를 통합한 쿼리를 실행할 수 있고, 이는 캠페인 코스트와 캠페인 매출 또는 다른 캠페인 퍼포먼스 KPI를 보여줍니다. 

이런 종류의 쿼리는 트래커와 매체 데이터에 기반한 특별한 디멘션과 메트릭을 활용하고, 이는 트래커와 네트워크 데이터에 기반하지만, 내부에서는 하기와 같은 추가적인 로직을 활용합니다.

통합 쿼리가 하는 일이란?

1. 통합 쿼리는 같은 쿼리 안에 매체 통계(코스트와 같은) 또는 트래커 통계(인스톨과 매출과 같은)를 모두 포함합니다.

2. 스마트 디멘션은 언제든 매체와 트래커 데이터를 하나의 열에 통합하는 데 도움이 됩니다. 

   Singular의 "combined" 또는 "unified" 디멘션들은 모두 매체와 트래커 데이터에 기반하며 이는 공통된 데이터 중 잘못 매칭된 데이터를 바로잡고 가능한 높은 세분성(granularity)에 기반한 통합 데이터를 볼 수 있게 합니다. 

   예를 들어, 트래커의 특정 캠페인의 이름이 매체에서 가져온 캠페인 이름과 약간의 차이가 있을 수 있습니다. 그래서 만약 트래커 리포트와 매체 리포트의 결과들을 같이 조회하면, 동일한 캠페인에 관해 네트워크 데이터와 트래커 데이터가 별개의 행에 나뉘어 조회됩니다. 하지만, 만약 통합 리포트를 실행하면 (unified_campaign_name 디멘션을 사용), Singular는 캠페인에 대한 매체 통계와 트래커 데이터를 같은 열에 볼 수 있게 합니다.  

3. 커스텀 가능한 스마트 메트릭이 각각 케이스별로 올바른 소스로부터 데이터들을 가져옵니다.

   예를 들어 같은 날짜 범위에 대한 각 캠페인에 대한 인스톨 수와 같이 매체와 트래커로부터 제공된 동일한 통계자료를 제공하는 경우, 통합된 메트릭이 일반적인 산업의 사용량에 기반하여 트래커 통계 또는 매체 통계 중 지능적으로 선택한 후 한 소스에 대한 정확한 정보를 제공합니다.  

   예를 들어, custom_installs 메트릭은 Facebook 또는 Twitter와 같이 매체의 통계가 더 중요하다 판단되는 자가 기여 네트워크(SANs)가 아닌 이상 트래커의 인스톨 수를 포함하며, 매체 메트릭을 포함합니다.  

   만약 Singular의 기본 선택지가 특정한 케이스에 부합하지 않는 경우, 특정 메트릭을 재설정하도록 Singular에 요청할 수 있습니다.  

   주의: 커스텀 메트릭은 크리에이티브 세부 내역에는 사용할 수 없습니다. 매체 메트릭 또는 트래커 메트릭 중에서 선택하세요. 

메트릭의 소스를 알아야 하는 경우라면?

각 캠페인에 대하여 각 메트릭의 정확한 소스를 알고 싶은 경우가 있을 수 있습니다 - 예를 들어, 매체와 트래커 사이의 중요한 불일치를 찾거나 트러블슈팅하는 경우가 해당합니다. 

이 경우, 매체 메트릭과(네트워크 데이터에서 사용할 수 있는 필드들을 참고) 트래커 메트릭(트래커 데이터에서 사용할 수 있는 필드들을 참고)을 추가하여 통합 리포트를 만들 수 있습니다. 예를 들어, custom_installs, adn_installs, tracker_installs 이 세 개의 인스톨 메트릭을 풀링하세요. 

이 방법으로, custom_installs를 KPI처럼 사용할 수 있지만 adn_installs와 tracker_installs 사이에 상당한 불일치가 있는지 확인하는 것이 좋습니다.  

통합 데이터에 사용할 수 있는 필드

메트릭과 디멘션 페이지에서 각 필드에 대한 설명을 참고하세요.

요약: 어떤 종류의 데이터를 사용할 수 있을까요?

	Singular에서 사용 목적은...
	애널리틱스 + Singular 어트리뷰션	애널리틱스만 사용하나, 제3의 트래커로부터 Singular로 데이터를 풀링	애드 네트워크로부터 데이터 풀링
매체 데이터	사용 가능	사용 가능	사용 가능
트래커 데이터	사용 가능	사용 가능	-
통합 필드	사용 가능	자기 기여 네트워크에서만 사용 가능 (크리에이티브 세부 내역 외)	-

리포팅 API를 쿼리하는 방법

쿼리하고 싶은 데이터 유형을 결정하고 특정 메트릭과 디멘션 리스트를 작성 후, 다음 리포팅 API 사용 방법을 확인하세요. 

기본 쿼리 작동하기

1	원하는 메트릭과 디멘션을 지정하여, 비동기 리포트 생성 엔드포인트 쿼리하기 (엔드포인트 레퍼런스 참고)  이를 통해 비동기 리포트 쿼리를 생성하고 리포트 ID를 반환합니다.
2	리포트 ID를 사용하여, Get Report Status의 API 엔드포인트(endpoint reference 참고)를 쿼리하여 리포트 실행이 언제 완료되었는지 확인하세요.  리포트 실행이 완료되면, Get Report Status 엔드포인트는 리포트 URL을 반환합니다.
3	해당 리포트 URL로부터 리포트를 다운로드하세요.

일별 리포트 실행하기

Data in Singular에서 데이터는 매일 업데이트됩니다. 특히, Singular에서 매일 데이터를 가져오고 싶다면, 다음을 포함하세요.  

• 하루전 데이터 
• 매체에 의해 업데이트되었을 가능성이 있는 과거 데이터  

일반 일별 리포트에서, 과거 데이터를 가져오기 위해 하단의 윈도우 시간을 사용하는 것을 권장합니다. 

쿼리 유형	권장 윈도우 시간
매체 데이터(Network Data)	과거 7일.
트래커 데이터 또는 통합 데이터(Tracker Data or Combined Data)	가장 긴 코호트 기간만큼의 긴 기간이면 괜찮습니다. 예를 들어, 30일 코호트의 경우, 과거 30일을 쿼리하세요. 만약 매출과 같은 코호트 데이터를 가져오는 경우가 아니면, 과거 7일의 데이터를 가져오는 것만으로도 충분합니다.

데이터 제공이 가능한지 확인하기

각 데이터 커넥터에 대한 데이터 제공 가능 상태(Data Availability Status) 엔드포인트를 사용하여 Singular가 해당 커넥터로부터 특정 날짜에 대한 데이터를 보유하고 있는지, 데이터가 업데이트된 마지막 시간이 언제인지 확인하기 위해 사용할 수 있습니다.  

해당 엔드포인트는 주로 각 데이터 커넥터에 관해 어제의 데이터를 확인하기 위해 사용합니다. 이 방법을 통해, 만약 모든 데이터 커넥터가 준비된 상태인 경우, 모든 데이터에 대한 리포트를 실행할 수 있습니다. 하지만 만약 데이터 커넥터가 부분적으로만 준비된 상태라면, 준비되지 않은 데이터 커넥터를 기다리거나, 데이터 제공이 가능한 각 데이터 소스에 관해서만 리포트를 실행하는 방법 중 선택하세요. (비동기 리포트 생성에서 특정 데이터 커넥터에 대한 리포트를 실행하려면, 리포트를 data_connector_id로 필터하세요) 

주의할 점은 Singular는 동일한 쿼리에서 하나 이상의 데이터 커넥터/소스에 대한 리포트 실행을 권장하지 않습니다. 

데이터 업데이트 주기 확인하기

Singular에서 네트워크 데이터가 최신 데이터인지 확인하는 방법에 관해서는, 리포트 쿼리에 data_connector_timestamp_utc 디멘션을 포함하세요. 

이 디멘션은 데이터를 수집하기 시작하는 데 걸린 시간이나 과정 Singular 데이터베이스에 저장 여부와 상관없이 Singular가 데이터 커넥터로부터 데이터를 가져오기 시작한 날짜와 시간을 포함합니다.   

데이터 타임스템프에 대한 사용 사례는 다음을 포함합니다.

• Singular 리포트와 네트워크 대시보드 사이의 불일치을 겪고 있는 경우 
• Singular에 신규 데이터가 있을 때, 데이터 데스티네이션(ETL)을 사용하여 Singular에서 내부 BI 플랫폼으로 데이터를 가져오는 경우