EVENT 엔드포인트 API 참조
서버 간 사용 사례
EVENT API는 애플리케이션에서 이벤트 추적을 가능하게 합니다. 앱이 디바이스별 데이터를 서버로 전달하고, 서버가 이를 Singular의 서버로 전송하면, 플랫폼은 이 정보를 처리합니다: 이벤트 어트리뷰션 및 앱 구매 지표. 이렇게 처리된 데이터는 보고서, 내보내기 로그, 구성된 포스트백을 자동으로 채우고 마케팅 캠페인에 대한 종합적인 분석을 제공합니다.
Singular 레스트 API는 SDK의 대안으로 서버 간 직접 연동을 가능하게 합니다. SDK는 디바이스 및 앱 데이터를 자동으로 수집하지만, S2S 접근 방식은 사용자가 직접 수집해야 합니다:
- 앱에서 필요한 데이터 포인트 수집
- 이 데이터를 서버로 전달
- 디바이스 그래프에서 디바이스 세부 정보 업데이트/조회
- REST API를 통해 이벤트를 Singular로 전달하기
핵심 포인트
- 유연성: 데이터 수집 및 전송에 대한 완전한 제어
- 기능 패리티: 적절한 데이터 제공 시 모든 SDK 기능 지원
- 연동 경로: 클라이언트 → 서버 → Singular API
- 실시간 처리: 한 번에 하나의 요청만 처리, 일괄 처리 없음
- 순차적 데이터 흐름: 이벤트는 시간 순서대로 처리해야 합니다.
- 데이터 중복 제거: Singular: 수신된 데이터는 중복 제거되지 않습니다. 요청을 재생해야 하는 경우 성공적인 요청을 하나(1)만 보내고 로그를 저장하는 것이 좋습니다.
- 데이터 유효성 검사: 디바이스 수준 데이터는 영구적이며 한번 수집된 데이터는 삭제할 수 없습니다. Singular에 데이터를 전송하기 전에 철저한 데이터 유효성 검사를 구현하여 정확성을 보장하세요.
전제 조건
- 이벤트 추적을 받기 전에 세션을 설정해야 합니다.
- 세션 순서가 잘못되면 데이터 불일치가 발생할 수 있습니다.
시작하기
이벤트 엔드포인트 설명서를 참조하세요:
이 서버 측 접근 방식을 사용하면 모든 SDK 기능을 유지하면서 연동을 더 잘 제어할 수 있습니다.
이벤트 보고
Singular는 인앱 이벤트에 대한 데이터를 수집하여 마케팅 캠페인의 성과를 분석할 수 있습니다. 이벤트에는 로그인 및 등록부터 게임 앱의 레벨업까지 모든 사용자 상호 작용이 포함될 수 있습니다.
Singular와 SDK/S2S 연동을 구현하기 전에, 조직에서 추적하려는 이벤트 목록이 있어야 합니다( 인앱 이벤트 정의하기 참조).
호출에 포함하는 이벤트 이름은 Singular 보고서, 내보내기 및 포스트백에서 이벤트가 식별되는 방식입니다.
참고:
- Singular는 Singular의 표준 이벤트 및 어트리뷰트 명명 규칙을 사용하여 이벤트를 전달할 것을 권장합니다. 표준 이벤트를 사용하면 연동에서 파트너 표준 이벤트와의 매핑 및 호환성을 간소화할 수 있습니다.
- 사용하려는 타사 파트너 및 분석 솔루션과의 호환성을 위해 이벤트 이름 및 기타 속성을 영어로 전달할 것을 적극 권장합니다.
중요:
- 이벤트 이름은 32개의 ASCII 문자로 제한됩니다. ASCII가 아닌 문자의 경우 UTF-8로 변환하면 32바이트로 제한됩니다.
- 이벤트 속성 및 값은 500자로 제한됩니다.
이벤트 API 엔드포인트
HTTP 메서드 및 이벤트 엔드포인트
GET https://s2s.singular.net/api/v1/evt필수 파라미터
다음 표에는 이 엔드포인트가 지원하는 필수 파라미터가 나열되어 있습니다. 나열된 모든 매개변수는 쿼리 매개변수입니다.
GET /api/v1/evt?param1=value1¶m2=value2- 모든 필수 매개변수는 EVENT 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(무선) 업데이트 후 앱을 삭제했다가 다시 설치하지 않는 한 일정하게 유지됩니다.
예제 값: |
| 매개변수 | 설명 |
지원되는 플랫폼:
|
sdid 파라미터는 Singular 디바이스 ID를 지정합니다.
예시 값: |
| 매개변수 | 설명 |
지원되는 플랫폼:
|
sing 매개변수는 기업 고객으로 제한되며 고객 정의 식별자를 지정합니다. 다른 모든 식별자를 사용할 수 없는 특수한 용도로만 사용됩니다. 이 식별자는 앱별 솔루션 엔지니어가 앱 단위로 활성화해야 합니다. 예제 값: |
| 디바이스 파라미터 | |
| 파라미터 | 설명 |
|
p 매개변수는 앱의 플랫폼을 지정합니다. 다음 목록에는 허용되는 대소문자를 구분하는 매개변수 값이 포함되어 있습니다:
예제 값입니다: |
| 매개변수 | 설명 |
|
ip 매개변수는 디바이스의 공인(IPV4) IP 주소를 지정합니다. IPV6는 지원되지 않습니다. 값 예시: |
| 매개변수 | 설명 |
|
ve 매개변수는 이벤트 시점의 디바이스의 OS 버전을 지정합니다. 예제 값입니다: |
| 파라미터 | 설명 |
지원되는 플랫폼입니다:
|
ma 매개변수는 디바이스 하드웨어의 제조사(일반적으로 소비자 대상 이름)를 지정합니다. 이 파라미터는 model 파라미터와 함께 사용해야 합니다. 예시: |
| 파라미터 | 설명 |
지원되는 플랫폼:
|
mo 매개변수는 디바이스 하드웨어의 모델을 지정합니다. 이 매개 변수는 make 매개 변수와 함께 사용해야 합니다. 예시: |
| 파라미터 | 설명 |
지원되는 플랫폼:
|
lc 매개변수는 밑줄로 구분된 두 글자의 언어와 국가 코드를 사용하여 디바이스에 대한 IETF 로캘 태그를 지정합니다. 예제 값: |
| 파라미터 | 설명 |
지원되는 플랫폼입니다:
|
bd 매개변수는 URL로 인코딩된 디바이스의 빌드를 지정합니다. 예제 값입니다: |
| 애플리케이션 파라미터 | |
| 파라미터 | 설명 |
|
i 매개변수는 앱 식별자를 지정합니다. Android의 경우 패키지 이름, iOS의 경우 번들 ID 또는 애플리케이션의 대소문자를 구분하는 매개변수 값입니다:
예시 값입니다: |
| 파라미터 | 설명 |
지원되는 플랫폼:
|
att_authorization_status 매개변수는 앱 추적 투명성(ATT) 상태 코드를 지정합니다. iOS 14.5부터는 IDFA 식별자에 액세스하기 위해 ATT(앱 추적 투명성) 프롬프트가 필요합니다. 참고: ATT 프롬프트를 구현하지 않더라도 "미결정"을 나타내는'0' 값으로 ATT 인증 상태를 전달해야 합니다. 지원되는 값은 다음과 같습니다:
예시: |
| 이벤트 매개변수 | |
| 파라미터 | 설명 |
|
n 매개변수는 추적 중인 이벤트의 이름을 지정합니다.
예제 값: |
요청 본문
이 메서드를 호출할 때 요청 본문을 제공하지 마세요. 요청은 쿼리 매개변수와 함께 GET 메서드를 사용하여 전송해야 합니다.
요청 예제
다음 코드 샘플은 지원되는 모든 매개변수를 나타내지 않을 수 있습니다. 요청을 구현할 때는 위에 나열된 모든 필수 매개변수를 포함하고 프로덕션 인스턴스에서 데이터를 전송하기 전에 올바른 값이 전달되고 있는지 확인하세요. 개발 및 테스트를 위해 고유한 `i` 매개변수(애플리케이션 식별자)를 사용하는 것이 좋습니다.
PYTHON
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
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"HTTP
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
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("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 application-level status
System.out.println("HTTP Status Code: " + responseCode);
System.out.println("Response: " + response.toString());
// Disconnect
conn.disconnect();
선택적 매개변수
다음 표에는 이 엔드포인트가 지원하는 선택적 매개변수가 나열되어 있습니다. 나열된 모든 매개변수는 쿼리 매개변수입니다.
| 선택적 매개변수 | |
|---|---|
| 타임스탬프 매개변수 | |
| 파라미터 | 설명 |
|
utime 매개변수는 이벤트 시간을 10자리 UNIX 시간으로 지정합니다.
예제 값입니다: |
| 매개변수 | 설명 |
|
umilisec 매개 변수는 이벤트의 시간을 13자리 UNIX 시간(밀리초)으로 지정합니다.
예제 값: |
| 장치 및 네트워크 매개변수 | |
| 파라미터 | 설명 |
|
global_properties 매개변수는 최대 5개의 키-값 쌍을 포함하는 URL 인코딩된 JSON 개체를 허용합니다. 각 키와 값의 길이는 최대 200자까지 가능합니다. JSON 객체는 반드시
예제 값입니다: |
| 매개변수 | 설명 |
|
use_ip 매개변수는 Singular가 'ip' 매개변수 대신 HTTP 요청에서 IP 주소를 추출하도록 지시합니다. 이 기능을 사용하려면'true'를 전달합니다.
예제 값 |
| 파라미터 | 설명 |
|
country 매개변수에는 이벤트 실행 시 사용자의 ISO 3166-1 알파-2 두 글자 국가 코드가 포함되어야 합니다. 이 파라미터는 다음과 같은 경우에만 필요합니다:
값 예시: |
| 이벤트 매개변수 | |
| 파라미터 | 설명 |
|
e 매개변수는 사용자 지정 이벤트 속성을 JSON 형식으로 지정합니다.
예시 값 |
| 구매 매개변수 | |
| 파라미터 | 설명 |
|
is_revenue_event 매개변수는 이벤트가 구매 이벤트인지 여부를 지정합니다.
값 예시: |
| 파라미터 | 설명 |
|
amt 매개변수는 통화 금액을 지정합니다.
예시 값: |
| 매개변수 | 설명 |
|
cur 매개변수는 ISO 4217 대문자 3자리 통화 코드를 지정합니다.
예시 값 |
| 매개변수 | 설명 |
지원되는 플랫폼:
|
구매_영수증 매개변수는 구매 시 받은 영수증을 지정합니다. Android, iOS에서 영수증을 검색하는 방법은 아래 지침을 참조하세요.
예(iOS): 예(Android) |
| 매개변수 | 설명 |
지원되는 플랫폼:
|
receipt_signature 매개변수는 구매 영수증에 서명하는 데 사용되는 서명을 지정합니다.
예시 값입니다: |
| 파라미터 | 설명 |
|
purchase_product_id 매개변수는 제품 SKU 식별자를 지정합니다.
예제 값 |
| 파라미터 | 설명 |
|
purchase_transaction_id 매개변수는 거래 식별자를 지정합니다.
예(iOS) 예 (안드로이드): |
| 데이터 개인정보 | |
| 파라미터 | 설명 |
|
data_sharing_options 매개변수는 정보 공유에 대한 최종 사용자의 동의를 지정합니다. 설정된 경우 이 값은 유지되며 사용자에 대한 모든 후속 '세션' 및 '이벤트' 요청에 전달되어야 합니다.
값은 URL로 인코딩된 JSON 문자열이어야 합니다.
값 예시: |
| 교차 기기 지원 | |
| 파라미터 | 설명 |
|
custom_user_id 매개변수는 내부 사용자 ID를 지정합니다.
예시 값: |
| iOS SkAdNetwork 지원 | |
| 파라미터 | 설명 |
지원 플랫폼:
|
skan_conversion_value 파라미터는 이 이벤트 알림 시점의 최신 SKAdNetwork 전환 값을 지정합니다(SKAdNetwork 구현에 대해 자세히 알아보기).
값 예시: |
| 파라미터 | 설명 |
지원 플랫폼:
|
skan_first_call_timestamp 파라미터는 기본 SkAdNetwork API에 대한 첫 번째 호출의 유닉스 타임스탬프를 지정합니다(SKAdNetwork 구현에 대해 자세히 알아보기).
예시 값: |
| 파라미터 | 설명 |
지원 플랫폼:
|
skan_last_call_timestamp 매개변수는 이 이벤트 알림 시점에 기본 SkAdNetwork API에 대한 최신 호출의 유닉스 타임스탬프를 지정합니다(SKAdNetwork 구현에 대해 자세히 알아보기).
예시 값: |
이벤트 테스트
서버 간 연동을 연동한 후에는 프로덕션 인스턴스로 라이브로 전환하기 전에 Singular가 데이터를 수신하는지 확인해야 합니다. 자세한 내용은 테스트 가이드를 참조하세요. 개략적으로 다음 단계를 따라야 합니다:
- 테스트 기기 광고 ID를 획득하고 Singular SDK 콘솔에 ID를 추가합니다.
- Singular SDK 콘솔을 열고 디바이스 식별자를 추가하여 데이터 캡처를 시작합니다.
- 앱 식별자를 개발 앱 식별자(com.singular.app.dev)로 재정의하여 테스트 데이터와 이벤트를 프로덕션 데이터와 별도로 유지합니다.
- 종료된 상태에서 앱 빌드 또는 열기
- 모든 필수 Singular 데이터 포인트가 포함된 앱 열기 유효성 검사를 서버로 전송합니다.
- 서버 유효성 검사는 모든 필수 데이터 포인트와 함께 Singular'실행' 엔드포인트에 세션 알림을 트리거합니다.
- 몇 초 후, 세션 이벤트가 Singular SDK 콘솔에 표시됩니다.
- 앱에서 이벤트 트리거를 진행합니다.
- 이벤트가 모든 필수 Singular 데이터 포인트와 함께 서버로 전송되었는지 확인합니다.
- 서버가 모든 필수 데이터 포인트가 포함된 이벤트 알림을 Singular'evt' 엔드포인트로 트리거하는지 확인합니다.
- 몇 초 후 이벤트가 Singular SDK 콘솔에 표시되어야 합니다.
- 테스트를 반복하여 모든 이벤트가 예상대로 예상 값과 함께 전송되는지 확인합니다.
- 세션 이벤트가 앱 열기 또는 포그라운드에서 이벤트가 수신되기 전에 발생하는지 확인합니다.
- 이벤트에 필요한 데이터 포인트가 세션 데이터 포인트와 일치하는지 확인합니다.
SDK 콘솔에 이벤트가 표시되면 이벤트 처리에 대한 엔드투엔드 테스트를 완료한 것입니다!