Server-to-Server - 기본 사항

팔로우
Avatar
Jared Ornstead
Updated

Server-to-Server - 기본 사항

SDK 연동의 대안으로 Singular의 REST API를 구현하여 완전한 서버 측 트래킹을 수행하고, 데이터 수집, 전송, 어트리뷰션 워크플로를 완벽하게 제어하십시오.

연동 방식 선택: SDK 또는 S2S? 클라이언트 SDK를 임베드할 수 있다면 SDK 연동 문서 부터 시작하십시오. 서버 측 이벤트 전달이 필요하거나, SDK가 없는 플랫폼을 사용 중이거나, 데이터 수집을 완전히 제어하고자 할 때 Server-to-Server를 사용하십시오. 본 문서 세트는 S2S 경로를 다루며, Mobile, Web, PC/Console S2S 가이드의 공통 참조 자료입니다.

개요

Server-to-Server 사용 사례

Server-to-server (S2S) 연동은 클라이언트 애플리케이션에 Singular SDK를 임베드하지 않고도 백엔드 인프라에서 실행되는 완전한 어트리뷰션 및 분석 솔루션을 구축할 수 있도록 REST API 엔드포인트를 제공합니다.

연동 방식:

  • 순수 S2S: 세션과 이벤트 트래킹을 모두 처리하는 100% 서버 측 구현
  • 하이브리드: Singular SDK가 세션을 관리하고 서버 측이 이벤트 트래킹을 처리

하이브리드 연동 패턴

하이브리드 연동은 세션 관리를 위한 Singular SDK와 백엔드 이벤트 트래킹을 위한 서버 측 EVENT API를 결합하여, 구현 용이성과 서버 측 유연성의 균형을 맞춥니다.

하이브리드의 이점:

  • SDK가 복잡한 세션 로직, 딥링킹, 디바이스 데이터 수집을 자동으로 처리
  • 서버가 백엔드 시스템에서 처리된 트랜잭션에 대한 이벤트를 전송
  • 클라이언트 측 구현 복잡성 감소
  • SESSION 엔드포인트 불필요—SDK가 세션 수명 주기를 관리

하이브리드 S2S 데이터 흐름

디바이스 데이터 검색 방법:

  1. 클라이언트 관리 흐름: 클라이언트에서 필수 데이터 포인트를 캡처하고, Singular EVENT 엔드포인트와 함께 사용하기 위해 내부 API를 통해 서버로 전달
  2. Internal BI 포스트백: Singular Internal BI 포스트백을 구성하여 설치, 리인게이지먼트, 이벤트 이후 디바이스 식별자가 포함된 실시간 JSON 페이로드를 수신 ( 설정 가이드 )

디바이스 그래프 유지 관리: 두 방법 모두 디바이스 그래프를 유지 관리하기 위한 서버 측 로직이 필요합니다. SDK가 디바이스 식별자 변경을 감지하면, 정확한 트래킹을 보장하기 위해 서버를 그에 맞게 업데이트하십시오.

구현 리소스:

핵심 연동 원칙

원칙 설명
유연성 데이터 수집 및 전송 시점에 대한 완전한 제어
기능 동등성 적절한 데이터가 제공될 경우 모든 SDK 기능을 지원
연동 경로 클라이언트 → 사용자의 서버 → Singular API
실시간 처리 한 번에 하나의 요청—배치 처리 미지원
순차적 흐름 이벤트는 시간 순서대로 처리되어야 함
중복 제거 없음 Singular는 중복을 제거하지 않음—서버 측에서 중복 제거를 구현
데이터 영속성 디바이스 수준 데이터는 수집 후 삭제할 수 없음—전송 전에 검증

연동 요구사항

순수 S2S 연동은 세션 및 이벤트 트래킹을 위한 포괄적인 데이터 파이프라인 구현이 필요합니다.

  1. 데이터 수집: 클라이언트 애플리케이션에서 필수 데이터 포인트를 수집
  2. 디바이스 그래프: 데이터를 서버로 전달하고 디바이스 식별자 저장소를 유지 관리
  3. 세션 요청: 다음을 통해 세션 알림을 전송: SESSION API
  4. 응답 처리: Singular 응답을 처리하여 클라이언트 앱으로 다시 전달
  5. 이벤트 요청: 다음을 통해 이벤트를 전달: EVENT API

관련 S2S 가이드

본 문서는 S2S 문서 세트의 공통 참조 자료입니다. 플랫폼에 맞는 가이드를 사용하고, 전체 파라미터 세부 정보는 엔드포인트 참조 자료를 확인하십시오.

플랫폼 가이드

엔드포인트 참조 자료

기능 가이드

REST API 엔드포인트

Singular은 server-to-server 세션 및 이벤트 트래킹을 위한 두 개의 주요 REST API 엔드포인트를 제공합니다.

Session 엔드포인트

세션 트래킹 API

SESSION 엔드포인트는 앱 열기 이벤트를 Singular에 알려 어트리뷰션 및 리텐션 트래킹을 위한 사용자 세션을 초기화합니다. 

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

전체 참조 자료: SESSION 엔드포인트 API 참조 자료

Event 엔드포인트

이벤트 트래킹 API

EVENT 엔드포인트는 어트리뷰션 분석 및 캠페인 최적화를 위해 인앱 이벤트와 수익을 트래킹합니다. 

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

전체 참조 자료: EVENT 엔드포인트 API 참조 자료

공통 파라미터

이 파라미터들은 Singular S2S REST API의 SESSION 및 EVENT 엔드포인트에서 공통으로 사용됩니다. 본 섹션은 이들의 표준 정의를 담고 있으며, 다른 S2S 문서들은 이를 재정의하지 않고 여기로 링크합니다.

인증

파라미터 세부 정보
a

string

API 인증을 위한 Singular SDK Key.

검색 위치: Singular UI → 메인 메뉴 → Developer Tools .

중요: Reporting API Key를 사용하지 마십시오. 요청이 거부됩니다.

예시: sdkKey_afdadsf7asf56

디바이스 식별자

디바이스 식별자는 플랫폼과 가용성에 따라 다릅니다. 사용 중인 플랫폼에 해당하는 모든 식별자를 포함하십시오. 사용할 수 없는 식별자는 생략하십시오—NULL이나 빈 문자열을 전달하지 마십시오.

파라미터 세부 정보
idfa

플랫폼: iOS

Identifier for Advertisers (IDFA) 는 광고 트래킹 및 캠페인 어트리뷰션을 가능하게 합니다.

ATT 요구사항: iOS 14.5+에서는 App Tracking Transparency 프레임워크를 통한 사용자 옵트인이 필요합니다.

  • IDFA를 사용할 수 없는 경우(사용자가 ATT 프롬프트를 거부한 경우) 파라미터를 생략하십시오.
  • NULL이나 빈 문자열을 전달하지 마십시오.
  • IDFA 검색

예시: DFC5A647-9043-4699-B2A5-76F03A97064B

idfv

플랫폼: iOS

Identifier for Vendors (IDFV) 는 동일한 벤더의 모든 앱에서 일관되게 유지됩니다.

항상 필수: ATT 상태나 IDFA 가용성과 관계없이 반드시 포함해야 합니다.

예시: 21DB6612-09B3-4ECC-84AC-B353B0AF1334

aifa

플랫폼: Android
(Google Play)

Google Advertising ID (GAID) 는 Android에서 사용자가 재설정할 수 있는 광고 트래킹을 가능하게 합니다.

  • Google Play 디바이스에서 필수.
  • 비 Google Play 디바이스에서는 생략.
  • 사용할 수 없는 경우 생략—NULL이나 빈 문자열을 전달하지 마십시오.
  • AIFA 검색

예시: 8ecd7512-2864-440c-93f3-a3cabe62525b

asid

플랫폼: Android
(Google Play)

Android App Set ID 는 동일한 개발자의 앱 간에 프라이버시를 고려한 크로스 앱 트래킹을 제공합니다.

항상 필수: GAID 가용성과 관계없이 Google Play 디바이스에서 반드시 포함해야 합니다.

예시: edee92a2-7b2f-45f4-a509-840f170fc6d9

amid

플랫폼: Android
(Amazon)

Amazon Advertising ID 는 Google Play 서비스가 없는 Amazon 디바이스용입니다.

  • Amazon Fire 디바이스에서 필수.
  • 사용할 수 없는 경우 생략.
  • AMID 검색

예시: df07c7dc-cea7-4a89-b328-810ff5acb15d

oaid

플랫폼: Android
(중국 OEM)

Open Advertising Identifier (OAID)는 Google Play 서비스가 없는 중국 제조 디바이스(Huawei, Xiaomi, OPPO 등)용입니다.

  • Google Play가 없는 중국 OEM 디바이스에서 필수.
  • 사용할 수 없는 경우 생략.
  • OAID 검색

예시: 01234567-89abc-defe-dcba-987654321012

andi

플랫폼: Android
(비 Google Play)

Android ID는 디바이스에서 생성되는 64비트 식별자입니다.

사용 제한: Google Play 디바이스에서는 금지—대신 AIFA와 ASID를 사용하십시오. 다른 식별자를 사용할 수 없고 앱이 Google Play를 통해 배포되지 않는 경우에만 전송하십시오.

예시: fc8d449516de0dfb

sdid

플랫폼: iOS, Android, PC, Xbox, PlayStation, Nintendo, MetaQuest, CTV

Singular Device ID는 고유한 앱 설치를 나타내는, 클라이언트에서 생성된 익명화된 UUIDv4입니다.

기본 식별자: PC 및 콘솔 애플리케이션에 관련된 유일한 디바이스 식별자입니다.

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

디바이스 파라미터

파라미터 세부 정보
p

string

애플리케이션의 플랫폼.

허용 값(대소문자 구분):

  • Android
  • iOS
  • PC
  • Xbox
  • Playstation
  • Nintendo
  • MetaQuest
  • CTV

예시: Android

ip

string

디바이스의 공용 IPv4 주소. IPv6도 지원되지만, 광고 네트워크와의 어트리뷰션 호환성을 위해 IPv4를 권장합니다.

예시: 172.58.29.235

ve

string

세션 시점의 디바이스 OS 버전.

예시: 9.2

ma
iOS, Android

string

디바이스 제조사(제조업체 이름). 반드시 mo (모델)와 함께 사용해야 합니다.

디바이스 제조사 검색

예시: Samsung , LG , Apple

mo
iOS, Android

string

디바이스 모델. 반드시 ma (제조사)와 함께 사용해야 합니다.

디바이스 모델 검색

예시: iPhone 4S , Galaxy SIII

lc
iOS, Android

string

IETF 로케일 태그—밑줄로 구분된 두 글자 언어 및 국가 코드.

디바이스 로케일 검색

예시: en_US

bd
iOS, Android

string

URL 인코딩된 디바이스 빌드 식별자.

디바이스 빌드 검색

예시: Build%2F13D15

애플리케이션 파라미터

파라미터 세부 정보
i

string

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

  • Android: 패키지 이름(예: com.singular.app )
  • iOS: Bundle ID(예: com.singular.app )
  • PC/Console: 지정된 식별자

예시: com.singular.app

app_v

string

애플리케이션 버전.

예시: 1.2.3

att_authorization_status
iOS

integer

App Tracking Transparency (ATT) 상태 코드(iOS 14.5+).

상태 값:

  • 0 - 미결정(프롬프트 미표시)
  • 1 - 제한됨(디바이스 수준 트래킹 비활성화)
  • 2 - 거부됨(사용자가 권한 거부)
  • 3 - 승인됨(사용자가 권한 부여)

항상 필수: ATT가 구현되지 않은 경우에도 0 (미결정)을 전달하십시오.

예시: 3

네트워크 및 위치 파라미터

파라미터 세부 정보
use_ip

boolean

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

제한 사항:

  • Singular의 IP 기반 지리적 위치 확인을 방지합니다.
  • 두 글자 국가 코드를 country 파라미터를 통해 제공하십시오.
  • ip 파라미터와 상호 배타적입니다—둘 다 사용하지 마십시오.
  • 데이터 거부를 방지하려면 ip 또는 use_ip 중 하나를 반드시 제공해야 합니다.

예시: true

country

string

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

필수 조건: IP 주소를 사용할 수 없거나 use_ip=true 인 경우.

예시: US

ua

string

URL 인코딩된 User Agent 문자열.

원본: Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15...

예시: Mozilla%2F5.0%20(iPhone%3B%20CPU%20iPhone%20OS%2014_0...

c
iOS, Android

string

네트워크 연결 유형.

허용 값: wifi , carrier

예시: wifi

cn
iOS, Android

string

인터넷 제공업체의 통신사 이름.

예시: Comcast

데이터 프라이버시 파라미터

파라미터 세부 정보
data_sharing_options

JSON

데이터 공유에 대한 최종 사용자 동의를 담은 JSON URL 인코딩 값. 반드시 유지되어야 하며 이후 모든 SESSION 및 EVENT 요청에서 전달되어야 합니다.

사용자 동의(옵트인): 

{"limit_data_sharing":false}

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

{"limit_data_sharing":true}

예시: %7B%22limit_data_sharing%22%3Atrue%7D

dnt
iOS, Android

integer

Do Not Track 상태.

  • 1 - Do Not Track 활성화
  • 0 - Do Not Track 비활성화

예시: 0

dntoff
iOS, Android

integer

Do Not Track가 OFF인지 여부를 나타냅니다.

  • 0 - Do Not Track 활성화(OFF=false)
  • 1 - Do Not Track 비활성화(OFF=true)

예시: 1

크로스 디바이스 지원

파라미터 세부 정보
custom_user_id

string

크로스 디바이스 트래킹을 위한 내부 사용자 ID.

PII 금지: 개인 식별 정보를 전달하지 마십시오. 원본 이메일 주소, 전화번호, 이름 대신 해시 처리되거나 익명화된 내부 식별자를 사용하십시오.

예시: 123456789abcd

구현 단계

성공적인 S2S 연동을 위해서는 최적의 데이터 품질과 어트리뷰션 정확도를 위해 네 가지 핵심 구현 단계를 순차적으로 실행해야 합니다.

1단계: 데이터 수집

필수 데이터 포인트

Singular 플랫폼 기능에 필요한 모든 필수 파라미터를 캡처하는 견고한 데이터 수집 전략을 수립하십시오.

모든 필수 파라미터는 필수: 필수 파라미터를 생략하면 데이터 불일치와 어트리뷰션 오류가 발생합니다. 선택적 파라미터는 없습니다.

비동기 함수 처리: 서버 전송을 위해 클라이언트 측 데이터를 수집할 때, 비동기 함수가 완료될 때까지 기다리고 엣지 케이스를 처리하십시오. 데이터 누락 및 부분 어트리뷰션을 유발하는 흔한 문제입니다.

구현 리소스:

2단계: 실시간 스트리밍

중요 타이밍 요구사항

실시간 데이터 스트리밍은 어트리뷰션 정확도를 유지하고 SKAdNetwork 전환 값 업데이트와 같은 시간에 민감한 기능을 가능하게 합니다.

어트리뷰션 영향:

  • 지연된 세션: 어트리뷰션 정확도에 심각한 영향을 미침—시스템은 캠페인 연관을 위해 정밀한 시간 데이터를 필요로 함
  • SKAdNetwork 타이머: 전환 값에 대한 엄격한 온디바이스 타이머 윈도우로 인해 실시간 스트리밍이 매우 중요합니다. 지연은 전환 값 업데이트 누락 및 불완전한 캠페인 데이터를 초래합니다

모범 사례:

  • 앱 세션 시작에 대한 서버 측 이벤트 리스너를 구현
  • 모든 필수 파라미터와 함께 세션 데이터 를 즉시 전달
  • 인앱 이벤트에 대한 서버 측 이벤트 리스너를 구현
  • 모든 필수 파라미터와 함께 이벤트 데이터 를 즉시 전달
  • 안정적인 데이터 전송을 위해 웹훅 아키텍처를 사용
  • 실패한 요청에 대한 재시도 메커니즘을 구현
  • 품질 보증을 위해 데이터 흐름을 모니터링

3단계: 응답 처리

양방향 통신

응답 처리는 서버 측 API 상호작용과 클라이언트 측 기능을 연결하여 디퍼드 딥링킹 및 전환 값 업데이트를 가능하게 합니다.

주요 응답 유형:

  • 디퍼드 딥링크: API 응답에 대기 중인 딥링크 데이터가 포함되며, 사용자 라우팅 및 개인화를 위해 즉시 앱으로 전달해야 함
  • 전환 값: iOS SKAdNetwork 전환 값은 정확한 캠페인 측정을 위해 즉시 앱으로 전달해야 함

모범 사례:

  • 서버 인프라에서 응답 처리를 구현
  • Singular API 응답을 파싱하고 검증
  • 관련 응답 데이터를 클라이언트 앱으로 전달(iOS SKAdNetwork에 필수)
  • 클라이언트 측 응답 처리를 구현
  • 적절한 HTTP 상태 코드로 오류를 우아하게 처리
  • 재시도 메커니즘을 위해 실패한 응답을 로깅

4단계: 테스트 & 검증

데이터 흐름 검증

테스트 단계는 프로덕션 배포 전에 완전한 데이터 파이프라인 기능과 어트리뷰션 정확도를 검증합니다.

세션 어트리뷰션 프로세스:

  • 첫 세션(신규 설치): Singular이 신규 설치를 인식하고 설치 어트리뷰션 프로세스를 트리거
  • 리인게이지먼트 자격 충족: Singular이 리인게이지먼트 어트리뷰션 프로세스를 트리거 ( 리인게이지먼트 FAQ )
  • 표준 세션: Singular이 사용자 활동 및 리텐션 지표를 위해 세션을 기록

중요 타이밍 요구사항:

  1. 이벤트 이전 세션: 어떤 이벤트보다 먼저 단일 SESSION이 수신되어야 합니다. SDK는 앱 열기 시 세션을 트리거한 후 인앱 이벤트를 전송합니다. 1분 이상 백그라운드 상태가 지속되면 세션이 타임아웃됩니다. 앱이 포그라운드로 복귀하면 새 세션이 전송됩니다. 세션 관리를 위해 앱 수명 주기 이벤트와 타이머를 사용하십시오
  2. 실시간 이벤트: 앱에서 발생하는 이벤트는 해당 세션 이후 실시간으로 전송되어야 합니다

검증 체크리스트:

  • 세션 데이터 흐름 테스트—첫 세션과 이후 세션이 올바른 데이터 포인트와 값을 갖는지 검증
  • 이벤트가 세션이 Singular에 보고된 이후에만 수신되는지 확인(세션 이전의 이벤트는 오가닉 어트리뷰션을 생성함)
  • 세션 응답이 처리되어 클라이언트 앱으로 전달되는지 확인(디퍼드 딥링크에 필수)

연동 완료:

  • ✓ 데이터 수집 및 저장 검증 완료
  • ✓ Singular로의 실시간 스트리밍 검증 완료
  • ✓ 응답 처리 및 로깅 검증 완료
  • ✓ 모든 테스트 데이터 흐름 검증 완료

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

추가 기능

포괄적인 분석을 위해 크로스 디바이스 트래킹, 수익 트래킹, 앱 삭제 모니터링, 데이터 프라이버시 준수를 구현하십시오.

크로스 디바이스 트래킹

Custom User ID 구현

custom_user_id 파라미터를 활용하여 사용자를 디바이스 수준 세션과 연결함으로써 크로스 디바이스 리포팅 및 사용자 수준 분석을 수행하십시오.

프라이버시 준수: custom_user_id 에 개인 식별 정보(PII)를 사용하지 않음으로써 데이터 프라이버시 정책을 준수하십시오. 고유한 사용자 식별자로 해시 처리된 사용자 이름, 이메일, 또는 무작위로 생성된 문자열을 사용하십시오.

사용자 프라이버시를 유지하면서 포괄적인 크로스 디바이스 리포팅, 사용자 수준 데이터 내보내기, Internal BI 포스트백을 가능하게 합니다.

자세한 정보: Custom User ID 파라미터

수익 트래킹

인앱 구매 리포팅

ROI 분석, 캠페인 성과 측정, 내보내기/포스트백 강화를 위해 인앱 구매로 인한 수익을 트래킹하십시오.

EVENT 엔드포인트 를 수익 파라미터 와 함께 사용하십시오:

  • is_revenue_event : 이벤트를 수익 이벤트로 표시(이벤트 이름이 __iap__ 이거나 금액 > 0인 경우 생략)
  • purchase_receipt : Android/iOS 인앱 구매 객체—트랜잭션 세부 정보 및 리포트 강화를 위해 적극 권장
  • receipt_signature (Android): 트랜잭션 검증 및 사기 방지를 위해 적극 권장
  • amt : Double 형식의 수익 금액(예: "amt=1.99")
  • cur : ISO 4217 통화 코드(예: "cur=USD")

구현 가이드: 구독 상태 관리

데이터 프라이버시 준수

사용자 동의 처리

GDPR, CCPA 및 기타 프라이버시 규정을 준수하기 위해 데이터 공유에 대한 최종 사용자 동의를 Singular에 알리십시오.

data_sharing_options 파라미터를 사용하여 사용자 선택을 전달하십시오:

  • {"limit_data_sharing":false} : 사용자가 정보 공유에 동의(옵트인)
  • {"limit_data_sharing":true} : 사용자가 정보 공유를 거부

Singular은 limit_data_sharing 을 User Privacy 포스트백 에서 사용하며, 준수가 필요한 파트너에게 정보를 전달합니다.

선택 사항이지만 권장: 파라미터는 선택 사항이지만, 일부 어트리뷰션 정보는 사용자가 명시적으로 옵트인한 경우에만 파트너가 공유합니다.

자세한 정보: User Privacy 및 Limit Data Sharing