EVENT 엔드포인트 API 레퍼런스

SDK 구현 대신 server-to-server 연동을 통해 Singular의 REST API를 사용하여 인앱 이벤트와 매출을 추적하고, 어트리뷰션 분석 및 캠페인 최적화에 활용하세요.

개요

Server-to-Server 사용 사례

EVENT API는 인앱 이벤트 추적을 지원합니다. 앱이 사용자 상호작용 데이터를 여러분의 백엔드로 전달하면, 백엔드가 이를 Singular 서버로 전송하여 이벤트 어트리뷰션 및 매출 분석 리포팅에 사용합니다.

지원 기능:

• 이벤트 어트리뷰션: 사용자 행동을 마케팅 캠페인과 연결
• 매출 추적: 인앱 구매 및 거래를 측정하고 어트리뷰션
• 커스텀 이벤트: 회원 가입부터 레벨 완료까지 모든 사용자 상호작용 추적
• 이벤트 속성: 보다 심층적인 분석을 위해 이벤트에 맥락 데이터 첨부

데이터 흐름 아키텍처

Server-to-server 이벤트 추적은 4단계 데이터 전송 프로세스를 따릅니다.

1. 클라이언트 수집: 앱이 이벤트 데이터와 디바이스 식별자를 수집
2. 서버 전송: 앱이 이벤트 데이터를 여러분의 백엔드 서버로 전달
3. 디바이스 그래프 조회: 서버가 Singular 디바이스 그래프에서 디바이스 정보를 조회하거나 업데이트
4. Event API 호출: 서버가 이벤트를 Singular REST API 엔드포인트로 전송

필수 요구사항

이벤트 추적 가이드라인

네이밍 규칙과 데이터 구조에 대한 Singular의 모범 사례를 따라 이벤트 추적을 구현하세요.

이벤트 정의

이벤트 정의하기

S2S 연동을 구현하기 전에, 캠페인 성과 분석을 위해 여러분의 조직이 추적하려는 이벤트의 전체 목록을 정의하세요.

이벤트 계획 가이드: 인앱 이벤트 정의하기

이벤트 네이밍의 영향: Singular로 전달되는 이벤트 이름은 이벤트가 리포트, 익스포트, 포스트백에 어떻게 표시되는지를 직접적으로 결정합니다.

표준 이벤트 네이밍

문자 제한

API 엔드포인트 선택

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

Event Endpoint V1

V1 사용 사례

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

권장 대상:

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

엔드포인트 URL:

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

Event Endpoint V2

V2 사용 사례

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

권장 대상:

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

엔드포인트 URL:

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

웹(p=Web) 변형

웹 연동은 이 동일한 EVENT 엔드포인트를 p=Web 과 함께 사용합니다. 웹에는 SESSION 호출이 없습니다. conversion_event=true 가 설정된 첫 번째 __PAGE_VISIT__ 이벤트가 앱 실행을 대신하여 어트리뷰션 터치포인트를 성립시킵니다.

웹 전용 파라미터

이 파라미터들은 p=Web 일 때 적용됩니다. 공유 파라미터 ( a , i , ip , sdid , custom_user_id )는 S2S Fundamentals 에 정의되어 있습니다.

웹 클릭 ID: 파트너 클릭 ID ( ScCid , ttclid , gclid / gbraid / wbraid , dclid , fbclid , rdt_uuid )는 이벤트 e 파라미터 안에 전달합니다.

필수 디바이스 식별자

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

V1 엔드포인트 식별자

플랫폼별 식별자

Event Endpoint V1은 디바이스 운영체제 및 앱 배포 방식에 따라 플랫폼별 광고 식별자를 필요로 합니다.

이들은 S2S Fundamentals 에 한 번 정의된 공유 S2S 파라미터입니다.

V2 엔드포인트 식별자

SDID 전용 요구사항

Event Endpoint V2는 모든 플랫폼에서 Singular Device ID(SDID)만을 필요로 하여 디바이스 식별을 단순화합니다.

필수 파라미터

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

API 인증

이들은 S2S Fundamentals 에 한 번 정의된 공유 S2S 파라미터입니다.

디바이스 파라미터

이들은 S2S Fundamentals 에 한 번 정의된 공유 S2S 파라미터입니다.

애플리케이션 파라미터

이들은 S2S Fundamentals 에 한 번 정의된 공유 S2S 파라미터입니다.

이벤트 파라미터

선택 파라미터

선택 파라미터는 추가적인 맥락과 기능으로 이벤트 추적을 강화합니다.

타임스탬프 파라미터

이벤트 속성

{
  "sng_attr_content_id": 5581,
  "sng_attr_content": "XBox",
  "sng_attr_content_type": "electronics"
}

%7B%22sng_attr_content_id%22%3A5581%2C%22sng_attr_content%22%3A%22XBox%22%2C%22sng_attr_content_type%22%3A%22electronics%22%7D

네트워크 파라미터

이들은 S2S Fundamentals 에 한 번 정의된 공유 S2S 파라미터입니다.

데이터 프라이버시

이들은 S2S Fundamentals 에 한 번 정의된 공유 S2S 파라미터입니다.

크로스 디바이스 지원

이들은 S2S Fundamentals 에 한 번 정의된 공유 S2S 파라미터입니다.

SKAdNetwork 지원

매출 추적

적절한 검증 및 통화 처리로 인앱 구매와 매출 이벤트를 추적하세요.

필수 매출 파라미터

기본 매출 추적

직접 매출 검증을 수행할 때 매출 이벤트 추적에 필요한 최소 파라미터입니다.

매출 검증 파라미터

Singular 검증 매출

Singular이 App Store와 서버 측 매출 검증을 수행하도록 하는 선택 파라미터입니다.

MIISqwYJKoZI...cNqts0jvcNvPcK7yuj0KhJ9nTTQ54kDKfReihzc6aw==

%7B%22orderId%22%3A%22GPA.1234%22%2C%22packageName%22%3A%22com.example%22%2C%22productId%22%3A%22com.example.product%22...

TyVJfHg8OAoW7W4wuJt...5agEDMnNXvhfrw==

요청 예시

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

import requests

params = {
    'a': 'sdk_key_here',
    'p': 'Android',
    'i': 'com.singular.app',
    'ip': '10.1.2.3',
    've': '9.2',
    'ma': 'samsung',
    'mo': 'SM-G935F',
    'lc': 'en_US',
    'bd': 'Build/13D15',
    'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
    'asid': 'edee92a2-7b2f-45f4-a509-840f170fc6d9',
    'n': 'sng_add_to_cart'
}

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 "ma=samsung" \
  --data-urlencode "mo=SM-G935F" \
  --data-urlencode "lc=en_US" \
  --data-urlencode "bd=Build/13D15" \
  --data-urlencode "aifa=8ecd7512-2864-440c-93f3-a3cabe62525b" \
  --data-urlencode "asid=edee92a2-7b2f-45f4-a509-840f170fc6d9" \
  --data-urlencode "n=sng_add_to_cart"

GET /api/v1/evt
    ?a=sdk_key_here
    &p=Android
    &i=com.singular.app
    &ip=10.1.2.3
    &ve=9.2
    &ma=samsung
    &mo=SM-G935F
    &lc=en_US
    &bd=Build%2F13D15
    &aifa=8ecd7512-2864-440c-93f3-a3cabe62525b
    &asid=edee92a2-7b2f-45f4-a509-840f170fc6d9
    &n=sng_add_to_cart 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("ma", "samsung");
params.put("mo", "SM-G935F");
params.put("lc", "en_US");
params.put("bd", "Build/13D15");
params.put("aifa", "8ecd7512-2864-440c-93f3-a3cabe62525b");
params.put("asid", "edee92a2-7b2f-45f4-a509-840f170fc6d9");
params.put("n", "sng_add_to_cart");

// 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 Console을 사용하여 프로덕션 배포 전에 S2S 이벤트 연동을 확인하세요.

테스트 절차

엔드투엔드 검증

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

이벤트 테스트

1. 이벤트 트리거: 앱에서 이벤트를 트리거하는 단계로 진행
2. 이벤트 데이터 검증: 이벤트가 필요한 모든 Singular 데이터 포인트와 함께 여러분의 서버로 전송되는지 확인
3. 서버 요청 확인: 여러분의 서버가 필요한 모든 파라미터와 함께 https://s2s.singular.net/api/v1/evt 로 EVENT 요청을 전송하는지 확인
4. SDK Console 확인(이벤트): 몇 초 이내에 EVENT가 SDK Console에 나타나야 함
5. 테스트 반복: 전송된 모든 이벤트가 예상 값을 갖는지 검증

추가 리소스

테스트 문서

포괄적인 테스트 가이드: S2S 연동 테스트 가이드