광고 수익 추적 API 참조

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

개요

서버 투 서버 사용 사례

광고 수익 API를 사용하면 노출 수준의 광고 수익화 추적이 가능합니다. 앱이 미디에이션 플랫폼에서 수익 데이터를 백엔드로 전달하면, 백엔드가 이를 Singular의 서버로 전송하여 광고 수익 분석 및 리포팅에 활용합니다.

지원 기능:

• 광고 수익화 수익: 미디에이션 플랫폼에서 발생하는 노출 수준의 수익 추적
• 플랫폼 어트리뷰션: 광고 수익을 유저 획득 캠페인과 연결
• 미디에이션 연동: 모든 주요 광고 미디에이션 플랫폼 지원
• 통화 변환: 조직 설정에 맞춘 자동 통화 변환

데이터 흐름 아키텍처

서버 투 서버 광고 수익 추적은 네 단계의 데이터 전송 프로세스를 따릅니다.

1. 클라이언트 수집: 앱이 미디에이션 플랫폼 SDK에서 노출 수준의 수익 데이터를 수집
2. 서버 전송: 앱이 광고 수익 데이터를 백엔드 서버로 전달
3. 디바이스 그래프 조회: 서버가 Singular 디바이스 그래프에서 디바이스 세부 정보를 조회하거나 업데이트
4. Event API 호출: 서버가 __ADMON_USER_LEVEL_REVENUE__ 이벤트를 Singular REST API 엔드포인트로 전송

필수 요구사항

API 엔드포인트 선택

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

Event 엔드포인트 V1

V1 사용 사례

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

권장 대상:

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

엔드포인트 URL:

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

Event 엔드포인트 V2

V2 사용 사례

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

권장 대상:

• 하이브리드 (SDID 기반): Singular SDK가 SDID로 세션을 추적하고 서버 측 이벤트가 동일한 SDID를 사용
• 단순화된 식별자: 플랫폼별 디바이스 식별자(IDFA, AIFA 등)를 사용하지 않는 구현

엔드포인트 URL:

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

필수 디바이스 식별자

디바이스 식별자 요구사항은 엔드포인트 버전과 플랫폼에 따라 다릅니다. 아래에서 플랫폼별 요구사항을 확인하세요.

V1 엔드포인트 식별자

플랫폼별 식별자

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

이는 공통 S2S 파라미터이며 S2S 기본 사항 에 한 번만 정의되어 있습니다.

V2 엔드포인트 식별자

SDID 전용 요구사항

Event 엔드포인트 V2는 모든 플랫폼에서 Singular 디바이스 ID(SDID)만 필요하므로 디바이스 식별을 단순화합니다.

필수 파라미터

모든 EVENT 요청은 디바이스 식별자 외에 다음 필수 파라미터를 포함해야 합니다.

API 인증

이는 공통 S2S 파라미터이며 S2S 기본 사항 에 한 번만 정의되어 있습니다.

디바이스 파라미터

이는 공통 S2S 파라미터이며 S2S 기본 사항 에 한 번만 정의되어 있습니다.

애플리케이션 파라미터

이는 공통 S2S 파라미터이며 S2S 기본 사항 에 한 번만 정의되어 있습니다.

이벤트 파라미터

__ADMON_USER_LEVEL_REVENUE__

{
  "ad_platform": "AdMob",
  "ad_mediation_platform": "admob.AdMobAdapter",
  "ad_unit_id": "ca-app-pub-6325336052/44923540"
}

%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

선택 파라미터

선택 파라미터는 추가 컨텍스트와 기능으로 광고 수익 추적을 향상시킵니다.

네트워크 파라미터

이는 공통 S2S 파라미터이며 S2S 기본 사항 에 한 번만 정의되어 있습니다.

데이터 개인정보 보호

이는 공통 S2S 파라미터이며 S2S 기본 사항 에 한 번만 정의되어 있습니다.

크로스 디바이스 지원

이는 공통 S2S 파라미터이며 S2S 기본 사항 에 한 번만 정의되어 있습니다.

요청 예시

샘플 코드는 여러 프로그래밍 언어에 걸쳐 광고 수익 EVENT 엔드포인트 연동을 보여줍니다.

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 -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"

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

// 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 광고 수익 연동을 검증하세요.

테스트 절차

엔드 투 엔드 검증

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

광고 수익 이벤트 테스트

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

추가 리소스

테스트 문서

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