광고 구매 추적 API 참조
서버 간 사용 사례
Singular는 EVENT API를 통해 광고 구매을 추적할 수 있습니다. 유료 이벤트 핸들러를 사용하여 미디에이션 플랫폼에서 서버로 노출 수준 구매 세부 정보를 전달하면, Singular는 이 데이터를 처리하여 보고서, 내보내기 로그 및 포스트백에 원활하게 연동할 수 있도록 합니다. 또한 이 플랫폼은 조직의 기본 설정에 따라 자동 통화 변환을 지원합니다.
Singular REST API는 SDK의 대안으로 서버 간 직접 연동을 가능하게 합니다. SDK는 디바이스 및 앱 데이터를 자동으로 수집하지만, S2S 방식은 사용자가 직접 수집해야 합니다:
- 앱에서 필요한 EVENT API 데이터 포인트 수집
- 관련 미디에이션 플랫폼 데이터 포인트 수집
- 이 데이터를 서버로 전달
- REST API를 통해'__ADMON_USER_LEVEL_REVENUE__' 이벤트를 Singular로 전송
주요 포인트
- 유연성: 데이터 수집 및 전송에 대한 완전한 제어
- 기능 패리티: 적절한 데이터 제공 시 모든 SDK 기능 지원
- 연동 경로: 클라이언트 → 서버 → Singular API
- 실시간 처리: 한 번에 하나의 요청만 처리, 일괄 처리 없음
- 순차적 데이터 흐름: 이벤트는 시간 순서대로 처리해야 합니다.
- 데이터 중복 제거: Singular: 수신된 데이터는 중복 제거되지 않습니다. 요청을 재생해야 하는 경우 성공적인 요청을 하나(1)만 보내고 로그를 저장하는 것이 좋습니다.
- 데이터 유효성 검사: 디바이스 수준 데이터는 영구적이며 한번 수집된 데이터는 삭제할 수 없습니다. Singular에 데이터를 전송하기 전에 철저한 데이터 유효성 검사를 구현하여 정확성을 보장하세요.
전제 조건
- 이벤트 추적을 받기 전에 세션을 설정해야 합니다.
- 세션 순서가 잘못되면 데이터 불일치가 발생할 수 있습니다.
- 미디에이션 SDK에서 직접 미디에이션 플랫폼 데이터 속성을 수집합니다. 구현 세부 사항 및 필수 데이터 포인트는 SDK 가이드 및 플랫폼별 미디에이션 설명서를 참조하세요.
시작하기
EVENT 엔드포인트 문서에서 제공합니다:
이 서버 측 접근 방식을 사용하면 모든 SDK 기능을 유지하면서 연동을 더 잘 제어할 수 있습니다.
이벤트 API 엔드포인트
HTTP 메서드 및 이벤트 엔드포인트
GET https://s2s.singular.net/api/v1/evt필수 파라미터
아래 표에는 이벤트 API를 통해 광고 구매화 구매 이벤트를 전송하는 데 필요한 파라미터가 나열되어 있습니다. 이러한 파라미터는 쿼리 파라미터로 포함되어야 합니다.
GET /api/v1/evt?param1=value1¶m2=value2- 모든 필수 파라미터는 이벤트 API 요청에 포함되어야 합니다.
- 파라미터는 지정된 형식과 데이터 유형을 따라야 합니다.
| 필수 파라미터 | |
|---|---|
| API 키 | |
| 파라미터 | 설명 |
|
a 매개변수는 Singular SDK 키를 지정합니다. 메인 메뉴의 개발자 도구 아래 Singular UI에서 SDK 키를 검색합니다. 참고: 보고 API 키는 데이터가 거부될 수 있으므로 사용하지 마세요. 예제 값: |
| 디바이스 식별자 파라미터 | |
| 파라미터 | 설명 |
지원되는 플랫폼:
|
idfa 매개변수는 광고주가 사용자 행동(예: 광고 클릭, 앱 설치)을 추적하고 특정 캠페인에 어트리뷰션하여 정확한 광고 타겟팅 및 캠페인 최적화를 가능하게 하는 광고주 식별자(IDFA) 를 지정하는 매개변수입니다. iOS 14.5부터는 앱이 IDFA에 액세스하기 전에 사용자가 ATT(앱 추적 투명성) 프레임워크를 통해 옵트인해야 합니다. 사용자가 IDFA에 옵트인하지 않으면 IDFA를 사용할 수 없게 되어 추적 기능이 제한됩니다.
예제 값: |
| 파라미터 | 설명 |
지원되는 플랫폼:
|
idfv 매개변수는 특정 공급업체 또는 개발자에게 고유한 Apple이 장치에 할당하는 고유 식별자인 공급업체 식별자(IDFV)를 지정합니다. 특정 디바이스에서 동일한 공급업체의 모든 앱에서 일관성을 유지하므로 공급업체는 사용자를 개인적으로 식별하지 않고도 앱 생태계 전반에서 사용자 행동과 상호 작용을 추적할 수 있습니다.
예제 값: |
| 파라미터 | 설명 |
지원되는 플랫폼입니다:
|
aifa 매개변수는 Google 광고 식별자(GAID)를 지정하며, Singular 또는 Android 광고 ID(AAID)로도 알려져 있습니다. 이 식별자는 Android 기기에 할당된 사용자 재설정이 가능한 고유 식별자입니다. 이를 통해 광고주와 앱 개발자는 앱 전반의 사용자 행동(예: 광고 클릭, 앱 설치)을 추적하고 특정 캠페인에 어트리뷰션하여 사용자 개인정보를 유지하면서 정확한 광고 타겟팅 및 캠페인 최적화를 수행할 수 있습니다.
예제 값: |
| 파라미터 | 설명 |
지원되는 플랫폼입니다:
|
asid 매개변수는 안드로이드 앱 세트 ID를 지정합니다. ASID는 개발자가 개인정보 보호를 고려한 방식으로 자신의 앱에서 사용자를 추적할 수 있는 방법을 제공합니다. 분석 및 사기 방지에 특히 유용하지만 개인 맞춤형 광고나 측정과 같은 광고 목적으로는 사용할 수 없습니다.
예시 값: |
| 파라미터 | 설명 |
지원되는 플랫폼입니다:
|
amid 매개변수는 사용자의 개인정보를 보호하는 데 도움이 되는 사용자 재설정이 가능한 고유 식별자인 광고 ID를 지정합니다. 관심사 기반 광고를 표시하거나 분석을 생성하기 위해 사용자의 행동에 대한 정보를 수집하는 경우 광고 ID를 사용해야 하며, 다른 식별자나 추적 방법을 사용할 수 없습니다. 사용자는 광고 ID를 재설정하거나 관심사 기반 광고를 모두 수신 거부할 수 있습니다.
예제 값: |
| 파라미터 | 설명 |
지원되는 플랫폼입니다:
|
oaid 매개변수는 OAID(오픈 광고 식별자)를 지정합니다. OAID는 Android 기기, 특히 중국에서 제조된 기기에서 광고 목적으로 사용되는 고유한 익명 식별자입니다. 중국 시장과 같이 구글 플레이 서비스를 사용할 수 없거나 지원하지 않는 기기에서 구글의 광고 ID(GAID)를 대체하기 위해 모바일 보안 연합(MSA)에서 도입했습니다. OAID는 주로 Google Play 서비스가 제한된 환경에서 광고 어트리뷰션 및 사용자 추적에 사용되며, 광고주와 개발자가 익명성을 유지하면서 사용자 행동을 추적할 수 있도록 합니다. OAID는 화웨이, 샤오미 등의 브랜드를 포함한 대부분의 중국 제조 안드로이드 기기에서 사용할 수 있습니다. MSA SDK 또는 화웨이 모바일 서비스(HMS)를 사용하여 액세스할 수 있습니다.
예제 값: |
| 파라미터 | 설명 |
지원되는 플랫폼입니다:
|
andi 매개변수는 디바이스를 처음 설정할 때 Android 운영 체제에서 생성되는 64비트 고유 식별자인 Android ID를 지정합니다. 이는 디바이스의 수명 기간 동안 지속되도록 설계되었지만 공장 초기화와 같은 특정 조건에서는 초기화될 수 있습니다. 안드로이드 ID는 각 디바이스마다 고유하며, 안드로이드 8.0(오레오)부터는 앱과 사용자별로 범위가 지정됩니다. 즉, 동일한 디바이스에 있는 여러 앱은 동일한 서명 키를 공유하지 않는 한 서로 다른 Android ID를 받게 됩니다. Android ID는 디바이스를 초기화하거나 OTA(무선) 업데이트 후 앱을 삭제했다가 다시 설치하지 않는 한 일정하게 유지됩니다.
예제 값: |
| 장치 매개변수 | |
| 파라미터 | 설명 |
|
p 매개변수는 앱의 플랫폼을 지정합니다. 다음 목록에는 허용되는 대소문자를 구분하는 매개변수 값이 포함되어 있습니다:
예제 값: |
| 매개변수 | 설명 |
|
ip 매개변수는 디바이스의 공인(IPV4) IP 주소를 지정합니다. IPV6는 지원되지 않습니다. 값 예시: |
| 매개변수 | 설명 |
|
ve 매개변수는 이벤트 시점의 디바이스의 OS 버전을 지정합니다. 값 예시: |
| 애플리케이션 매개변수 | |
| 파라미터 | 설명 |
|
i 매개변수는 앱 식별자를 지정합니다. 대소문자를 구분하는 값입니다:
예시 값입니다: |
| 매개변수 | 설명 |
지원되는 플랫폼입니다:
|
att_authorization_status 매개변수는 앱 추적 투명성(ATT) 상태 코드를 지정합니다. iOS 14.5부터는 IDFA 식별자에 액세스하기 위해 ATT(앱 추적 투명성) 프롬프트가 필요합니다. 참고: ATT 프롬프트를 구현하지 않더라도 '미결정'을 나타내는'0' 값으로 ATT 인증 상태를 전달해야 합니다. 지원되는 값은 다음과 같습니다:
예시: |
| 이벤트 매개변수 | |
| 파라미터 | 설명 |
|
n 매개변수는 추적 중인 이벤트의 이름을 지정합니다.
|
| 파라미터 | 설명 |
|
e 매개변수는 사용자 지정 이벤트 속성을 JSON 형식으로 지정합니다. 유일한 필수 속성은 'ad_platform'입니다. 다른 모든 속성은 선택 사항입니다. 가능한 속성은 다음과 같습니다:
참고: 값이 없는 속성은 생략해야 합니다. 값 예시: |
| 파라미터 | 설명 |
|
is_admon_revenue 매개변수는 이벤트가 광고 구매화 구매 이벤트인지, 광고 구매 지표에 사용해야 하는지 여부를 지정합니다.
예시 값 |
| 파라미터 | 설명 |
|
is_revenue_event 매개변수는 이벤트가 구매 이벤트인지, 구매 지표에 사용해야 하는지 여부를 지정합니다.
예제 값 |
| 파라미터 | 설명 |
|
amt 매개변수는 통화 금액을 지정합니다.
예시 값: |
| 매개변수 | 설명 |
|
cur 매개변수는 ISO 4217 대문자 3자리 통화 코드를 지정합니다.
예시 값 |
요청 본문
이 메서드를 호출할 때 요청 본문은 제공하지 마세요. 요청은 쿼리 매개변수와 함께 GET 메서드를 사용하여 전송해야 합니다.
요청 예제
다음 코드 샘플은 지원되는 모든 매개변수를 나타내지 않을 수 있습니다. 요청을 구현할 때는 위에 나열된 모든 필수 매개변수를 포함하고 프로덕션 인스턴스에서 데이터를 전송하기 전에 올바른 값이 전달되고 있는지 확인하세요. 개발 및 테스트를 위해 고유한 애플리케이션 식별자를 사용하는 것이 좋습니다.
PYTHON
import requests
params = {
'a': 'sdk_key_here',
'p': 'Android',
'i': 'com.singular.app',
'ip': '10.1.2.3',
've': '9.2',
'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
'asid': 'edee92a2-7b2f-45f4-a509-840f170fc6d9',
'n': '__ADMON_USER_LEVEL_REVENUE__',
'e': '{"ad_platform":"AdMob","ad_mediation_platform":"admob.AdMobAdapter","ad_unit_id":"ca-app-pub-6325336052/44923540"}',
'is_admon_revenue':'true',
'is_revenue_event':'true',
'amt':0.00782,
'cur':'USD'
}
response = requests.get('https://s2s.singular.net/api/v1/evt', params=params)
print(response.json())CURL
curl -G 'https://s2s.singular.net/api/v1/evt' \
--data-urlencode "a=sdk_key_here" \
--data-urlencode "p=Android" \
--data-urlencode "i=com.singular.app" \
--data-urlencode "ip=10.1.2.3" \
--data-urlencode "ve=9.2" \
--data-urlencode "aifa=8ecd7512-2864-440c-93f3-a3cabe62525b" \
--data-urlencode "asid=edee92a2-7b2f-45f4-a509-840f170fc6d9" \
--data-urlencode "n=__ADMON_USER_LEVEL_REVENUE__" \
--data-urlencode 'e={"ad_platform":"AdMob","ad_mediation_platform":"admob.AdMobAdapter","ad_unit_id":"ca-app-pub-6325336052/44923540"}' \
--data-urlencode "is_admon_revenue=true" \
--data-urlencode "is_revenue_event=true" \
--data-urlencode "amt=0.00782" \
--data-urlencode "cur=USD"HTTP
GET /api/v1/evt
?a=sdk_key_here
&p=Android
&i=com.singular.app
&ip=10.1.2.3
&ve=9.2
&aifa=8ecd7512-2864-440c-93f3-a3cabe62525b
&asid=edee92a2-7b2f-45f4-a509-840f170fc6d9
&n=__ADMON_USER_LEVEL_REVENUE__
&e=%7B%22ad_platform%22%3A%22AdMob%22%2C%22ad_mediation_platform%22%3A%22admob.AdMobAdapter%22%2C%22ad_unit_id%22%3A%22ca-app-pub-6325336052%2F44923540%22%7D
&is_admon_revenue=true
&is_revenue_event=true
&amt=0.00782
&cur=USD HTTP/1.1
Host: s2s.singular.net
Accept: application/json
JAVA 예제
// Base URL
String baseUrl = "https://s2s.singular.net/api/v1/evt";
// Parameters
Map < String, String > params = new HashMap < > ();
params.put("a", "sdk_key_here");
params.put("p", "Android");
params.put("i", "com.singular.app");
params.put("ip", "10.1.2.3");
params.put("ve", "9.2");
params.put("aifa", "8ecd7512-2864-440c-93f3-a3cabe62525b");
params.put("asid", "edee92a2-7b2f-45f4-a509-840f170fc6d9");
params.put("n", "__ADMON_USER_LEVEL_REVENUE__");
params.put("e", "{\"ad_platform\":\"AdMob\",\"ad_mediation_platform\":\"admob.AdMobAdapter\",\"ad_unit_id\":\"ca-app-pub-6325336052/44923540\"}");
params.put("is_admon_revenue", "true");
params.put("is_revenue_event", "true");
params.put("amt", "0.00782");
params.put("cur", "USD");
// Build URL with encoded parameters
StringBuilder urlBuilder = new StringBuilder(baseUrl);
urlBuilder.append('?');
for (Map.Entry < String, String > entry: params.entrySet()) {
if (urlBuilder.length() > baseUrl.length() + 1) {
urlBuilder.append('&');
}
urlBuilder.append(URLEncoder.encode(entry.getKey(), StandardCharsets.UTF_8))
.append('=')
.append(URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8));
}
// Create connection
URL url = new URL(urlBuilder.toString());
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
conn.setRequestProperty("Accept", "application/json");
// Get response
int responseCode = conn.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(conn.getInputStream())
);
String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in .readLine()) != null) {
response.append(inputLine);
} in .close();
// Check application-level status
System.out.println("HTTP Status Code: " + responseCode);
System.out.println("Response: " + response.toString());
// Disconnect
conn.disconnect();선택적 매개변수
다음 표에는 이 엔드포인트가 지원하는 선택적 매개변수가 나열되어 있습니다. 나열된 모든 매개변수는 쿼리 매개변수입니다.
| 선택적 매개변수 | |
|---|---|
| 장치 및 네트워크 매개변수 | |
| 파라미터 | 설명 |
|
use_ip 매개변수는 Singular가 'ip' 매개변수 대신 HTTP 요청에서 IP 주소를 추출하도록 지시합니다. 이 기능을 사용하려면'true'를 전달하세요.
예제 값 |
| 파라미터 | 설명 |
|
country 매개변수에는 이벤트 실행 시 사용자의 ISO 3166-1 알파-2 두 글자 국가 코드가 포함되어야 합니다. 이 파라미터는 다음과 같은 경우에만 필요합니다:
값 예시: |
| 데이터 개인정보 | |
| 파라미터 | 설명 |
|
data_sharing_options 매개변수는 정보 공유에 대한 최종 사용자의 동의를 지정합니다. 설정된 경우 이 값은 유지되며 사용자에 대한 모든 후속 '세션' 및 '이벤트' 요청에 전달되어야 합니다.
값은 URL로 인코딩된 JSON 문자열이어야 합니다. 값 예시: |
| 교차 기기 지원 | |
| 파라미터 | 설명 |
|
custom_user_id 매개변수는 내부 사용자 ID를 지정합니다. 예시 값: |
이벤트 테스트
서버 간 연동을 연동한 후에는 프로덕션 인스턴스로 라이브로 전환하기 전에 Singular가 데이터를 수신하는지 확인해야 합니다. 자세한 내용은 테스트 가이드를 참조하세요. 개략적으로 다음 단계를 따라야 합니다:
- 테스트 기기 광고 ID를 획득하고 Singular SDK 콘솔에 ID를 추가합니다.
- Singular SDK 콘솔을 열고 디바이스 식별자를 추가하여 데이터 캡처를 시작합니다.
- 앱 식별자를 개발 앱 식별자(com.singular.app.dev)로 재정의하여 테스트 데이터와 이벤트를 프로덕션 데이터와 별도로 유지합니다.
- 종료된 상태에서 앱 빌드 또는 열기
- 모든 필수 Singular 데이터 포인트가 포함된 앱 열기 유효성 검사를 서버로 전송합니다.
- 서버 유효성 검사는 모든 필수 데이터 포인트가 포함된 Singular'실행' 엔드포인트로 세션 알림을 트리거합니다.
- 몇 초 후, 세션 이벤트가 Singular SDK 콘솔에 표시되어야 합니다.
- 앱에서 이벤트 트리거를 진행합니다.
- 이벤트가 모든 필수 Singular 데이터 포인트와 함께 서버로 전송되었는지 확인합니다.
- 서버가 모든 필수 데이터 포인트가 포함된 이벤트 알림을 Singular'evt' 엔드포인트로 트리거하는지 확인합니다.
- 몇 초 후 이벤트가 Singular SDK 콘솔에 표시되어야 합니다.
- 테스트를 반복하여 모든 이벤트가 예상대로 예상 값과 함께 전송되는지 확인합니다.
중요 확인 사항
- 세션 이벤트가 앱 열기 또는 포그라운드에서 이벤트가 수신되기 전에 발생하는지 확인합니다.
- 이벤트에 필요한 데이터 포인트가 세션 데이터 포인트와 일치하는지 확인합니다.
- 이벤트 인수에 올바른 미디에이션 플랫폼 세부 정보가 전달되었는지 확인합니다.
- 올바른 구매 금액과 통화를 확인합니다.
SDK 콘솔에 이벤트가 표시되면 이벤트 처리에 대한 엔드투엔드 테스트를 완료한 것입니다!