에 대한 기사: 개발자

Polaris 보고 API

엔드포인트(Endpoints)

Polaris 보고 API는 다음 위치에서 확인하실 수 있습니다:

https://inc-metrics.prod.api.metric.works

엔드포인트는 다음과 같습니다:

https://inc-metrics.prod.api.metric.works/token - 인증을 위한 보안 토큰 획득
https://inc-metrics.prod.api.metric.works/query - 보고 데이터를 얻기 위해 쿼리 제출

제한(Limits)

API에는 다음과 같은 제한이 있습니다:

제한	값
요청 비율	계정당 분당 10개 요청
동시 요청	1
날짜 범위	요청당 최대 30일
앱 필터	요청당 앱 1개(Polaris의 전체 앱 이름을 필터값으로 사용)

인증(Authentication)

보고 API의 쿼리 엔드포인트에 대한 모든 요청은 토큰 엔드포인트에서 얻은 보안 토큰을 지정해야 합니다. 보안 토큰을 얻으려면 다음 JSON 본문이 다음 JSON 본문을 포함하는 요청을 게시하십시오:

{ "username": "my.email@company.com", "password": "mypassword" }

위의 사용자 이름 및 비밀번호 자리 표시자 값(my.email@company.com and mypassword)을 실제 Polaris 사용자 이름(이메일 주소) 및 비밀번호로 바꾸십시오.
성공하면 응답은 쿼리 요청에 다음과 같이 Authorization 헤더의 Bearer 토큰으로 지정되어야 하는 텍스트 보안 토큰이 됩니다:

Authorization: Bearer [security token]

위의 헤더 예제에서 [security token] 자리 표시자를 보안 토큰으로 바꿉니다. 보안 토큰은 토큰 엔드포인트에서 가져온 시점부터 1시간 동안 유효합니다. 만료된 보안 토큰을 지정하면 쿼리 엔드포인트에서 401 Unauthorized 응답이 발생합니다.

쿼링(Querying)

보고 API에서 보고 데이터를 조회 하려면 다음 속성 중 하나 이상을 포함하는 요청을 게시하십시오:

속성명	설명	예시	필수사항
startDate	희망 시작 날짜입니다. 형식: `yyyy-mm-dd`.	-01-01```	예
endDate	희망 종료 날짜입니다. 형식: `yyyy-mm-dd`.	-01-31```	예
groupBy	결과를 그룹화할 기준이 되는 수준을 나타내는 배열입니다. 그룹화 기준 Group By를 참조하세요.	["CHANNEL", "COUNTRY"]```	예
metrics	반환되어야 하는 지표를 나타내는 배열입니다. 측정항목 Metrics를 참조하세요.	예시	예
filters	결과를 필터링해야 하는 값을 나타내는 배열입니다. 필터 Filters를 참조하세요.	예시	아니오
orderBy	결과를 정렬해야 하는 디멘션을 나타내는 배열입니다. 주문 Order By를 참조하세요.	예시	아니오

그룹화(Group By)

하기 표는 groupBy 속성에서 유효한 값으로 사용할 수 있는 수준을 설명합니다. 그룹화는 반환된 결과의 세분성으로 생각할 수 있습니다.

값	설명
DATE	날짜
PLATFORM	플랫폼
APP	앱
CHANNEL	채널
CAMPAIGN_GROUP	캠페인
COUNTRY	국가
SITE	사이트

측정 항목(Metrics)

'metrics' 속성에 나열된 각 지표 개체는 다음과 같이 지정해야 합니다.

속성명	설명	예시	필수사항
type	측정항목의 유형입니다. 유효값은 아래 표를 참조하십시오.	```	예
day	측정항목의 코호트 날짜입니다. 측정항목이 코호트 지표인 경우에만 필요합니다.	```	아니오
interval	95% 신뢰 구간도 반환해야 하는지 여부입니다. 측정항목이 증분 지표인 경우에만 적용 가능합니다.	```	아니오

아래 표는 각 지표 개체의 type 속성에서 유효한 값으로 사용할 수 있는 측정항목 유형을 설명합니다. INC_

접두사가 붙은 측정항목 유형만 증분 지표입니다. 다른 지표들는 라스트 터치입니다.

값	설명	코호트 여부
SPEND	spend	아니오
NEW_USERS	Installs or registrations	아니오
INC_NEW_USERS	Incrementality installs or registrations	아니오
COHORT_SIZE	Cohort size	예
INC_COHORT_SIZE	Incrementality cohort size	예
RETAINED_USERS	Retained users	예
INC_RETAINED_USERS	Incrementality retained users	예
COHORT_REVENUE	Cohorted revenue	예
INC_COHORT_REVENUE	Incrementality cohorted revenue	예
COHORT_AD_REVENUE	Ad revenue	예
INC_COHORT_AD_REVENUE	Incrementality ad revenue	예
COHORT_IAP_REVENUE	Purchase revenue	예
INC_COHORT_IAP_REVENUE	Incrementality purchase revenue	예
RETENTION_RATE	Retention rate	예
INC_RETENTION_RATE	Incrementality retention rate	예
COST_PER_NEW_USER	CPI or cost per acquisition	아니오
INC_COST_PER_NEW_USER	Incrementality CPI or cost per acquisition	아니오
ROAS	Return on ad spend	예
INC_ROAS	Incrementality return on ad spend	예
LTV	Lifetime value or average revenue per user (ARPU)	예
INC_LTV	Incrementality lifetime value or average revenue per user (ARPU)	예
COHORT_PURCHASES	Number of purchases or subscriptions	예
INC_COHORT_PURCHASES	Incrementality number of purchases or subscriptions	예
COHORT_SESSIONS	Cohorted sessions	예
INC_COHORT_SESSIONS	Incrementality cohorted sessions	예
COHORT_PAYING_USERS	Cohorted number of unique users with at least one purchase	예
INC_COHORT_PAYING_USERS	Incrementality cohorted number of unique users with at least one purchase	예
COHORT_PAYING_RATE	Cohorted % of users that made at least 1 purchase	예
INC_COHORT_PAYING_RATE	Incrementality cohorted % of users that made at least 1 purchase	예

Metrics 예시

[
  {
    "type": "INC_NEW_USERS",
    "interval": true
  },
  {
    "type": "NEW_USERS"
  },
  {
    "type": "INC_ROAS",
    "day": 3,
    "interval": false
  },
  {
    "type": "ROAS",
    "day": 3
  }
]

필터(Filters)

'filters' 속성에 나열된 각 필터 개체는 다음 속성을 지정해야 합니다.

속성명	설명	예시	필수사항
type	그룹으로 유효한 값을 사용하는 필터의 디멘션입니다.	```	예
values	디멘션을 필터링할 값을 나타내는 배열입니다.	["Facebook"]```	예
not	필터를 무효화해야 하는지 여부입니다.	```	아니오

Filters 예시

[
  {
    "type": "CHANNEL",
    "values": ["Facebook"],
    "not": false
  }
]

주문(Order By)

'orderBy' 속성에 나열된 각 개체별 주문은 다음 속성을 지정해야 합니다.

속성명	설명	예시	필수사항
type	그룹으로 유효한 값을 사용하여 주문의 디멘션입니다.	```	예
descending	기본 오름차순이 아닌 내림차순으로 정렬할지 여부입니다.	```	아니오

Order By 예시

[
  {
    "type": "CHANNEL",
    "descending": false
  }
]

코드(Code) 예시

다음은 Python으로 작성된 코드 샘플입니다. 내결함성, 오류 처리 또는 조절(throttling)을 구현하지 않지만 기본 사항에 대한 아이디어를 제공해야 합니다.

import requests

token_endpoint = "https://inc-metrics.prod.api.metric.works/token"
query_endpoint = "https://inc-metrics.prod.api.metric.works/query"

username = "username"
password = "password"

credentials = {
    "username": username,
    "password": password
}

query = {
    "groupBy": [
        "CHANNEL"
    ],
    "metrics": [
        {
            "type": "INC_NEW_USERS",
            "interval": True
        }
    ],
    "filters": [
        {
            "type": "APP",
            "values": ["App Name (iOS)"]
        }
    ],
    "order": [],
    "startDate": "2022-06-01",
    "endDate": "2022-06-01"
}

token_response = requests.request("POST", token_endpoint, json=credentials)

headers = {'Authorization': 'Bearer ' + token_response.text}

query_response = requests.request("POST", query_endpoint, headers=headers, json=query)

print(query_response.text)

업데이트 날짜: 22/09/2022

도움이 되셨나요??

감사합니다!