문서

광고 구매 추적 API 레퍼런스

SDK 구현의 대안으로 서버 간 연동을 통해 Singular의 REST API를 사용하여 어트리뷰션 분석 및 캠페인 최적화를 위한 노출 수준의 광고 구매화 구매을 추적하세요.

개요

서버 간 사용 사례

광고 구매 API를 사용하면 앱이 미디에이션 플랫폼에서 백엔드로 구매 데이터를 전달하여 광고 구매 분석 및 보고를 위해 Singular 서버로 전송하는 노출 수준 광고 구매화 추적이 가능합니다.

지원되는 기능:

광고 구매화 구매: 미디에이션 플랫폼의 노출 수준 구매 추적
플랫폼 어트리뷰션: 광고 구매을 사용자 확보 캠페인에 연결합니다.
미디에이션 연동: 모든 주요 광고 미디에이션 플랫폼 지원
통화 변환: 조직 설정에 따른 자동 통화 변환

데이터 흐름 아키텍처

서버 간 광고 구매 추적은 4단계 데이터 전송 프로세스를 따릅니다.

클라이언트 수집: 앱이 미디에이션 플랫폼 SDK에서 노출 수준 구매 데이터를 수집합니다.
서버 전송: 앱이 광고 구매 데이터를 백엔드 서버로 전달합니다.
디바이스 그래프 쿼리: 서버가 Singular 디바이스 그래프에서 디바이스 세부 정보를 검색하거나 업데이트합니다.
이벤트 API 호출: 서버가 Singular REST API 엔드포인트로 __ADMON_USER_LEVEL_REVENUE__ 이벤트를 전송합니다.

중요 요구 사항

전제 조건:

이벤트 전 세션: 광고 구매 추적 전에 세션이 설정되어야 합니다.
순차적 순서: 세션 순서가 잘못되면 데이터 불일치 및 어트리뷰션 오류가 발생합니다.
미디에이션 플랫폼 데이터: 미디에이션 SDK에서 직접 필요한 어트리뷰션을 수집 - 구현에 대한 자세한 내용은 SDK 가이드를참조하세요.

연동 제약 조건:

실시간 처리: 요청은 개별적으로 처리됨 - 일괄 지원 없음
시간순 이벤트: 이벤트는 발생한 순서대로 전송해야 함
중복 제거 없음: 데이터 중복을 방지하기 위해 서버 측 중복 제거를 구현합니다.
데이터 영구성: 장치 수준 데이터는 수집 후 삭제할 수 없음 - 전송 전에 유효성 검사 수행

API 엔드포인트 선택

Singular는 서로 다른 연동 아키텍처에 최적화된 두 가지 EVENT 엔드포인트 버전을 제공합니다.

엔드포인트 선택: 연동 아키텍처 및 기기 식별자 전략에 따라 엔드포인트를 선택하세요. 사용 사례에 따라 올바른 엔드포인트가 결정됩니다.

이벤트 엔드포인트 V1

V1 사용 사례

플랫폼별 장치 식별자(IDFA, IDFV, AIFA, ASID 등)에 의존하는 연동에는 이벤트 엔드포인트 V1을 사용하세요.

권장 대상:

순수한 서버 측: Singular SDK 구현이 없는 서버 측 연동
하이브리드(비 SDID): Singular SDK가 Singular 디바이스 ID(SDID)를 사용하지 않는 하이브리드 연동

엔드포인트 URL:

GET https://s2s.singular.net/api/v1/evt

이벤트 엔드포인트 V2

V2 사용 사례

Singular SDK가 SDID를 사용하여 세션을 추적하고 서버가 동일한 SDID를 사용하여 이벤트를 전송하는 하이브리드 연동에는 이벤트 엔드포인트 V2를 사용하세요.

권장 대상:

하이브리드(SDID 기반): Singular SDK는 SDID로 세션을 추적하고 서버 측 이벤트는 동일한 SDID를 사용합니다.
간소화된 식별자: 플랫폼별 디바이스 식별자(IDFA, AIFA 등)를 피하는 구현

엔드포인트 URL:

GET https://s2s.singular.net/api/v2/evt

계정 활성화: V2 엔드포인트는 SDID 사용을 위해 Singular 계정 구성이 필요합니다. 사용 설정은 솔루션 엔지니어 또는 CSM에게 문의하세요.

필수 장치 식별자

장치 식별자 요구 사항은 엔드포인트 버전 및 플랫폼에 따라 다릅니다. 아래에서 플랫폼별 요구 사항을 검토하세요.

V1 엔드포인트 식별자

플랫폼별 식별자

이벤트 엔드포인트 V1에는 디바이스 운영 체제 및 앱 배포 방식에 따라 플랫폼별 광고 식별자가 필요합니다.

파라미터	플랫폼	설명
`idfa`	iOS	광고주용 식별자(IDFA)는 광고 추적 및 캠페인 어트리뷰션을 가능하게 합니다. ATT 요구사항: iOS 14.5 이상에서는 앱 추적 투명성을 통한 사용자 옵트인이 필요합니다. IDFA를 사용할 수 없는 경우 매개변수 생략(사용자가 ATT를 거부한 경우) NULL 또는 빈 문자열을 전달하지 마십시오. IDFA 검색 예: `DFC5A647-9043-4699-B2A5-76F03A97064B`
`idfv`	iOS	공급업체용 식별자(IDFV)는동일한 공급업체의 모든 앱에서 일관성을 유지합니다. 항상 필수입니다: ATT 상태 또는 IDFA 사용 가능 여부에 관계없이 반드시 포함해야 합니다. IDFV 검색 예: `21DB6612-09B3-4ECC-84AC-B353B0AF1334`
`aifa`	Android (구글 플레이)	Google 광고 ID(GAID)는 사용자가 재설정 가능한 광고 추적을 가능하게 합니다. Google Play 기기에서 필수 Google Play가 아닌 기기에서는 생략 NULL 또는 빈 문자열을 전달하지 마십시오. AIFA 검색 예: `8ecd7512-2864-440c-93f3-a3cabe62525b`
`asid`	Android (구글 플레이)	안드로이드 앱 세트 ID는동일한 개발자에 대해 개인정보 보호를 고려한 교차 앱 추적을 제공합니다. 항상 필수입니다: GAID 사용 가능 여부와 관계없이 Google Play 기기에 반드시 포함되어야 합니다. ASID 검색 예: `edee92a2-7b2f-45f4-a509-840f170fc6d9`
`amid`	Android (Amazon)	구글 플레이 서비스가 없는 아마존 파이어 디바이스용 아마존 광고 ID. Amazon 디바이스에 필요 AMID 검색 예: `df07c7dc-cea7-4a89-b328-810ff5acb15d`
`oaid`	Android (중국 OEM)	구글 플레이 서비스가 없는 중국 제조 기기용 OAID(오픈 광고 식별자)입니다. Google Play가 없는 화웨이, 샤오미, OPPO, Vivo 기기에 필요합니다. OAID 검색 예: `01234567-89abc-defe-dcba-987654321012`
`andi`	Android (비구글 플레이)	Android ID는 기기에서 생성된 64비트 식별자입니다. 사용 제한: Google Play 기기에서는 사용이 금지됩니다. 다른 식별자를 사용할 수 없고 Google Play를 통해 배포되지 않은 앱만 사용하세요. ANDI 검색 예시: `fc8d449516de0dfb`

V2 엔드포인트 식별자

SDID 전용 요구 사항

이벤트 엔드포인트 V2는 모든 플랫폼에 대해 Singular 디바이스 ID(SDID)만 필요하므로 디바이스 식별이 간소화됩니다.

매개변수 설명

sdid

플랫폼: iOS, Android

Singular SDK에서 얻거나 클라이언트 측에서 생성한 Singular 장치 ID.

iOS/Android: SDID 사용을 위해 계정 활성화 필요 - SDK 콜백 메서드는 초기화 후 SDID를 제공합니다.
식별자 간소화: AIFA, ASID, IDFA, IDFV 매개변수 필요 없음
SDID 검색

예: 40009df0-d618-4d81-9da1-cbb3337b8dec

필수 파라미터

모든 이벤트 요청에는 디바이스 식별자 외에 이러한 필수 파라미터가 포함되어야 합니다.

파라미터 형식: 모든 파라미터는 GET 메서드를 사용하여 URL 쿼리 파라미터로 전달해야 합니다. 매개변수를 JSON 요청 본문으로 보내지 마세요.

API 인증

파라미터 유형 설명

a

string

API 인증을 위한 Singular SDK 키입니다.

검색 위치: Singular UI → 메인 메뉴 → 개발자 도구

중요: 리포팅 API 키는 사용하지 마세요. 요청이 거부됩니다.

예시: sdkKey_afdadsf7asf56

디바이스 매개변수

파라미터 설명

p

애플리케이션의 플랫폼(대소문자 구분).

허용되는 값: Android, iOS

예시: Android

ip

디바이스의 공인 IPv4 IP 주소. IPv6도 지원되지만 어트리뷰션 호환성을 위해 IPv4를 권장합니다.

예시: 172.58.29.235

ve

이벤트 시점의 디바이스 OS 버전.

예시: 9.2

애플리케이션 매개변수

파라미터 설명

i

앱 식별자(대소문자 구분).

Android: 패키지 이름(예: com.singular.app)
iOS: 번들 ID(예: com.singular.app)

예시: com.singular.app

att_authorization_status
iOS

ATT(앱 추적 투명성) 상태 코드(iOS 14.5 이상).

상태 값:

0 - 미정(프롬프트가 표시되지 않음)
1 - 제한됨(디바이스 수준 추적 비활성화)
2 - 거부됨(사용자가 권한 부여를 거부함)
3 - 승인됨(사용자에게 권한 부여됨)

항상 필요: ATT가 구현되지 않은 경우에도 0 (미정)을 전달합니다.

예시: 3

이벤트 매개변수

파라미터	설명
`n`	추적 중인 이벤트의 이름입니다. 광고 구매에 대한 필수 이벤트 이름입니다: `__ADMON_USER_LEVEL_REVENUE__` 이벤트 이름은 모두 대문자(밑줄 포함)여야 합니다. 최대 32개의 ASCII 문자
`e`	미디에이션 플랫폼의 사용자 지정 이벤트 속성을 지정하는 JSON URL 인코딩 문자열입니다. 필수 속성: `ad_platform` - (필수) 광고 네트워크 이름 선택적 속성: `ad_mediation_platform` `ad_type` `ad_group_type` `ad_impression_id` `ad_placement_name` `ad_unit_id` `ad_unit_name` `ad_group_id` `ad_group_name` `ad_group_priority` `ad_placement_id` JSON 구조: `{ "ad_platform": "AdMob", "ad_mediation_platform": "admob.AdMobAdapter", "ad_unit_id": "ca-app-pub-6325336052/44923540" }` URL 인코딩된 예시: `%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%5C%2F44923540%22%7D` 참고: 값이 없는 속성은 생략합니다.
`is_admon_revenue`	이벤트가 광고 구매 지표에 대한 광고 구매화 구매 이벤트인지 여부를 지정합니다. 이 이벤트에 대해 `true` 을 전달합니다. 예시: `true`
`is_revenue_event`	이벤트가 구매 지표에 대한 구매 이벤트인지 여부를 지정합니다. 이 이벤트에 `true` 전달 예시: `true`
`amt`	노출 구매의 통화 금액. `cur` 파라미터와 함께 사용 예시: `0.00782`
`cur`	ISO 4217세 글자의 대문자 통화 코드입니다. `amt` 파라미터와 함께 사용 예: `USD`

선택적 파라미터

선택적 매개변수는 추가적인 컨텍스트와 기능으로 광고 구매 추적을 향상시킵니다.

네트워크 파라미터

파라미터 설명

use_ip

Singular가 ip 파라미터 대신 HTTP 요청에서 IP 주소를 추출하도록 지시합니다.

제한사항:

Singular에 의한 IP 기반 지리적 위치를 방지합니다.
country 파라미터를 통해 두 글자 국가 코드 제공
ip 파라미터와 상호 배타적
ip 또는 use_ip중 하나를 제공해야 합니다.

예시: true

country

ISO 3166-1 알파-2두 글자 국가 코드.

필요한 경우: IP 주소를 사용할 수 없거나 use_ip=true

예: US

데이터 개인정보

파라미터 설명

data_sharing_options

데이터 공유에 대한 최종 사용자의 JSON URL 인코딩 동의. 이후의 모든 이벤트 요청에 대해 유지되고 전달되어야 합니다.

사용자 동의(옵트인):

{"limit_data_sharing":false}

사용자 거부(옵트아웃):

{"limit_data_sharing":true}

URL 인코딩 예: %7B%22limit_data_sharing%22%3Atrue%7D

교차 디바이스 지원

파라미터 설명

custom_user_id

교차 기기 추적을 위한 내부 사용자 ID입니다.

예시: 123456789abcd

요청 예시

샘플 코드는 여러 프로그래밍 언어에서 광고 구매 이벤트 엔드포인트 연동을 보여줍니다.

예시 면책 조항: 코드 샘플에는 필수 파라미터가 모두 포함되어 있지 않을 수 있습니다. 프로덕션 구현 전에 전체 파라미터 목록을 검증하세요. 개발/테스트에는 고유한 i (앱 식별자)를 사용하세요.

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 status
System.out.println("HTTP Status Code: " + responseCode);
System.out.println("Response: " + response.toString());

// Disconnect
conn.disconnect();

응답 코드 및 오류

EVENT 엔드포인트는 요청 성공 또는 실패를 나타내는 HTTP 상태 코드와 JSON 응답을 반환합니다.

전체 오류 문서: S2S 응답 코드 및 오류 처리

테스트 및 검증

실시간 데이터 검증을 위해 Singular SDK 콘솔을 사용하여 프로덕션 배포 전에 S2S 광고 구매 연동을 검증하세요.

테스트 절차

엔드 투 엔드 검증

테스트 기기를 등록합니다: 디바이스 광고 ID를 획득하고 Singular SDK 콘솔에추가합니다.
콘솔 로깅을 활성화합니다: SDK 콘솔에 디바이스 식별자를 추가하여 테스트 데이터를 캡처합니다.
개발 앱 ID 사용: 앱 식별자를 개발 버전(예: com.singular.app.dev)으로 재정의하여 테스트와 프로덕션 데이터를 분리합니다.
빌드 및 실행: 종료된 상태에서 앱 빌드 또는 열기
클라이언트 데이터 유효성 검사: 앱이 필요한 모든 Singular 데이터 포인트를 서버로 전송하는지 확인합니다.
세션 확인: 서버가 모든 필수 파라미터와 함께 https://s2s.singular.net/api/v1/launch 로 세션 요청을 보내는지 확인합니다.
SDK 콘솔(세션)을 확인합니다: 몇 초 내에 SDK 콘솔에 세션 이벤트가 표시되어야 합니다.

SDK Console Session Event

광고 구매 이벤트 테스트

광고 노출을 트리거합니다: 앱에서 광고 노출을 생성하여 미디에이션 플랫폼 콜백을 실행합니다.
미디에이션 데이터 검증: 모든 필수 미디에이션 플랫폼 속성과 함께 서버로 전송된 노출 데이터를 확인합니다.
서버 요청 확인: 서버가 모든 필수 파라미터와 함께 https://s2s.singular.net/api/v1/evt 로 이벤트 요청을 전송했는지 확인합니다.
SDK 콘솔(이벤트)을 확인합니다: 몇 초 내에 SDK 콘솔에 __ADMON_USER_LEVEL_REVENUE__ 이벤트가 표시되어야 합니다.
테스트를 반복합니다: 예상 값과 정확한 구매 금액으로 전송된 모든 광고 노출을 검증합니다.

SDK Console Ad Revenue Event

중요 검증:

이벤트 수신 전 앱 오픈/포그라운드에서 세션 이벤트 발생 확인
이벤트 필수 데이터 포인트가 세션 데이터 포인트와 일치하는지 확인합니다.
이벤트 인수에 전달된 미디에이션 플랫폼 세부 정보가 올바른지 확인합니다.
올바른 구매 금액 및 통화 확인

성공 표시기: 광고 구매 이벤트가 SDK 콘솔에 표시되면 엔드투엔드 광고 구매 연동 테스트가 성공적으로 완료된 것입니다!

추가 리소스

테스트 문서

종합 테스트 가이드: S2S 연동 테스트 가이드

서버 간 - 광고 구매 추적 API 레퍼런스

광고 구매 추적 API 레퍼런스

개요

서버 간 사용 사례

데이터 흐름 아키텍처

중요 요구 사항

API 엔드포인트 선택

이벤트 엔드포인트 V1

V1 사용 사례

이벤트 엔드포인트 V2

V2 사용 사례

필수 장치 식별자

V1 엔드포인트 식별자

플랫폼별 식별자

V2 엔드포인트 식별자

SDID 전용 요구 사항

필수 파라미터

API 인증

디바이스 매개변수

애플리케이션 매개변수

이벤트 매개변수

선택적 파라미터

네트워크 파라미터

데이터 개인정보

교차 디바이스 지원

요청 예시

Python 예제

cURL 예제

HTTP 예제

Java 예제

응답 코드 및 오류

테스트 및 검증

테스트 절차

엔드 투 엔드 검증

광고 구매 이벤트 테스트

추가 리소스

테스트 문서