Server-to-Server - 연동 가이드

SDK 연동의 대안으로 Singular의 REST API를 구현하여 완전한 서버 사이드 추적을 수행하고, 데이터 수집, 전송, 어트리뷰션 워크플로우를 완벽하게 제어하세요.

개요

Server-to-Server 사용 사례

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

연동 방식:

• 순수 S2S: 세션과 이벤트 추적을 모두 처리하는 100% 서버 사이드 구현
• 하이브리드: Singular SDK가 세션을 관리하고 서버 사이드가 이벤트 추적을 처리하는 방식

하이브리드 연동 패턴

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

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

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

구현 리소스:

• EVENT 엔드포인트 필수 파라미터
• 디바이스 데이터 검색 가이드 (iOS/Android 코드 샘플)

핵심 연동 원칙

연동 요구사항

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

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

REST API 엔드포인트

Singular은 server-to-server 세션 및 이벤트 추적을 위한 두 가지 주요 REST API 엔드포인트를 제공합니다.

Session 엔드포인트

Session 추적 API

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

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

전체 레퍼런스: SESSION 엔드포인트 API 레퍼런스

Event 엔드포인트

Event 추적 API

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

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

전체 레퍼런스: EVENT 엔드포인트 API 레퍼런스

구현 단계

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

1단계: 데이터 수집

필수 데이터 포인트

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

구현 리소스:

• SESSION 엔드포인트 필수 파라미터
• EVENT 엔드포인트 필수 파라미터
• 디바이스 데이터 검색 가이드 (iOS/Android 코드 샘플)
• SKAdNetwork 4 구현 가이드 (iOS 전용 데이터 포인트)

2단계: 실시간 스트리밍

중요한 타이밍 요구사항

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

모범 사례:

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

3단계: 응답 처리

양방향 통신

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

주요 응답 유형:

• 지연 딥링크: API 응답에는 사용자 라우팅과 개인화를 위해 앱으로 즉시 전달해야 하는 대기 중인 딥링크 데이터가 포함됩니다
• 전환 값: iOS SKAdNetwork 전환 값은 정확한 캠페인 측정을 위해 신속하게 앱으로 전달되어야 합니다

모범 사례:

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

4단계: 테스트 & 검증

데이터 흐름 검증

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

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

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

검증 체크리스트:

• 세션 데이터 흐름을 테스트합니다—첫 번째 및 후속 세션이 올바른 데이터 포인트와 값을 가지는지 검증합니다
• 세션이 Singular에 보고된 후에만 이벤트가 수신되는지 확인합니다 (세션 전에 발생한 이벤트는 오가닉 어트리뷰션을 생성합니다)
• 세션 응답이 처리되어 클라이언트 앱으로 전달되는지 확인합니다 (지연 딥링크에 필수)

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

고급 기능

고급 어트리뷰션 처리, 딥링킹, 크로스 디바이스 추적, 플랫폼별 기능으로 S2S 연동을 강화하세요.

Apple Search Ads 어트리뷰션

iOS Search Ads 연동

Apple Search Ads는 Self-Attributing Network(SAN)로, Apple 프레임워크를 통한 플랫폼별 어트리뷰션 구현이 필요합니다.

프레임워크 지원:

• iOS 14.2 이하: iAd 프레임워크
• iOS 14.3 이상: AdServices 프레임워크 (권장)

전체 가이드: Apple Search Ads 연동 문서

iAd 프레임워크 구현

iOS 14.2 이하의 경우 iAd 프레임워크를 통해 Apple Search Ads 어트리뷰션 데이터를 검색하여 전송합니다.

1단계: 어트리뷰션 데이터 검색

#import <iAd/iAd.h>

Class ADClientClass = NSClassFromString(@"ADClient");

if (ADClientClass) {
    id sharedClient = [ADClientClass performSelector:@selector(sharedClient)];

    if ([sharedClient respondsToSelector:@selector(requestAttributionDetailsWithBlock:)]) {
        [sharedClient requestAttributionDetailsWithBlock:^(NSDictionary *attributionDetails, NSError *error) {
            if (attributionDetails && attributionDetails.count  0) {
                // REPORT attributionDetails FROM YOUR APP TO YOUR SERVER
            }
        }];
    }
}

2단계: Singular로 전송

어트리뷰션 JSON을 e 파라미터로 전달하여 예약된 이름 __iAd_Attribution__ 의 이벤트를 EVENT 엔드포인트 를 통해 보고합니다.

AdServices 프레임워크 구현

iOS 14.3 이상의 경우 AdServices 프레임워크를 통해 어트리뷰션 토큰을 검색하여 전송합니다.

1단계: 어트리뷰션 토큰 검색

#import <AdServices/AdServices.h>

NSError *error = nil;
Class AAAttributionClass = NSClassFromString(@"AAAttribution");
if (AAAttributionClass) {
    NSString *attributionToken = [AAAttributionClass attributionTokenWithError:&error];
    if (!error && attributionToken) {
        // Handle attributionToken
    }
}

2단계: Singular로 전송

토큰을 URL 인코딩하여 모든 설치 및 재설치 이후 첫 세션에서 SESSION 엔드포인트 에 attribution_token 파라미터로 추가합니다.

Google Play Install Referrer

Android 설치 어트리뷰션

Google Play Install Referrer는 사용자가 Play Store에 도달하기 전의 출처에 대한 정보를 포함하여, 가장 정확한 Android 설치 어트리뷰션을 제공합니다.

추가 정보: Google Install Referrer 문서

구현 단계:

1. 첫 앱 실행 시 Play Install Referrer API 를 사용하여 install referrer를 검색합니다
2. 필수 속성이 포함된 install_ref JSON 파라미터를 포함하여 SESSION 엔드포인트 를 통해 세션을 보고합니다

install_ref 속성:

Meta Install Referrer

Facebook 어트리뷰션 강화

Meta Referrer는 Google Play Install Referrer와 Meta Install Referrer 기술을 결합하여, 앱 설치에 대한 세분화된 유저 레벨 어트리뷰션 데이터를 제공하는 Android 전용 측정 솔루션입니다.

자세히 알아보기: Meta Referrer FAQ

구현 단계:

1. 첫 앱 실행 시 Meta 문서 에 따라 Meta install referrer를 검색합니다
2. 필수 속성이 포함된 meta_ref JSON 파라미터를 포함하여 SESSION 엔드포인트 를 통해 세션을 보고합니다

meta_ref 속성:

Singular Links & 딥링킹

Singular 추적 링크에 딥링킹과 지연 딥링킹을 구현하여 사용자가 캠페인에서 앱의 특정 화면으로 매끄럽게 이동하도록 하세요.

딥링크는 앱 내부의 특정 콘텐츠를 여는 클릭 가능한 링크입니다. 지원해야 할 두 가지 시나리오가 있습니다:

• 딥링크 (직접): 사용자가 이미 앱을 설치한 경우입니다. 사용자가 Singular Link를 탭하면 앱이 올바른 콘텐츠로 바로 열립니다.
• 지연 딥링크 (DDL): 사용자가 아직 앱을 설치하지 않은 경우입니다. 사용자가 링크를 탭하고 스토어에서 설치한 후, 첫 실행 시에도 앱이 의도한 콘텐츠로 라우팅합니다.

SDK 연동에서는 Singular이 대부분을 자동으로 처리합니다. server-to-server(S2S) 연동에서는 디바이스에 SDK가 없으므로, 팀에서 두 가지 추가 작업을 담당해야 합니다: 앱이 수신한 딥링크를 Singular로 전달하는 것과, Singular이 반환하는 지연 딥링크를 읽고 사용자를 라우팅하는 것입니다. 두 작업 모두 SESSION 엔드포인트를 통해 흐릅니다:

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

리소스: 딥링킹 FAQ | Singular Links FAQ

세 가지 구성 한눈에 보기

1단계: 앱 수준 구성

딥링크가 작동하려면, 먼저 Singular Links가 OS에 의해 iOS Universal Links 및 Android App Links로 인식되어 링크를 탭했을 때 브라우저 대신 앱이 열려야 합니다. 기존 URI 앱 스킴은 폴백으로 지원됩니다.

자세한 플랫폼 단계는 표준 설정 가이드를 따른 다음, 아래 각 항목이 완료되었는지 확인하세요. 자세한 단계는 Singular Links 사전 요구사항 및 딥링크 구성 방법에 있습니다. 여기 체크리스트는 필요한 순서와 팀에서 가장 자주 놓치는 지점을 알려줍니다.

구성 체크리스트:

1. 링크 서브도메인 추가 — Attribution > Manage Links > Manage Link Domains에서 추가합니다(예: yourbrand.sng.link). 이는 Singular Links가 사용하는 호스트입니다.
2. iOS — Universal Links: applinks:yourbrand.sng.link에 대한 Associated Domains 기능을 활성화한 다음, Apple Developer Portal에서 App Prefix / Team ID를 복사하여 Settings > Apps > [iOS 앱] > Show Advanced Settings에 입력합니다. 선택적으로 Xcode에서 URL Type으로 앱 스킴 폴백을 등록합니다.
3. Android — App Links: SHA-256 서명 지문을 생성하고(프로덕션은 Play Console, 디버그는 keytool), Singular 도메인에 대한 autoVerify intent filter를 AndroidManifest.xml에 추가한 다음, 지문을 Settings > Apps > [Android 앱] > Show Advanced Settings > App Links SHA256 fingerprints에 붙여넣습니다.
4. 딥링크 정의 — Attribution > Manage Links > Create Link에서 정의합니다(아래 필드 매핑 참조).

Manage Links 리디렉션 필드 매핑

링크를 생성할 때, 세 개의 리디렉션 필드는 나중에 API에서 사용되는 세 가지 딥링크 개념에 직접 매핑됩니다:

개발자 인계: 엔지니어링은 플랫폼별 딥링크 스킴과 대상 URL 목록을 제공해야 합니다(예: myapp://autumnfashion).

2단계: SESSION (인바운드) — 딥링크를 Singular로 전송

앱이 Singular Link에서 열리면, 전체 열린 URL을 캡처하여 SESSION 요청의 openuri 파라미터(URL 인코딩)로 Singular에 전송합니다. 이것이 Singular이 세션을 링크에 어트리뷰션하고 딥링크 결과를 보고하는 방식입니다. Singular Links를 사용할 때 필수입니다.

URL에 포함된 Singular Link 파라미터

앱에서 열린 URL 캡처

앱에는 열린 URL을 수신하여 SESSION 요청에 포함하도록 서버로 전달하는 핸들러 코드가 필요합니다.

iOS (Swift):

// Custom scheme / direct opens
func scene(_ scene: UIScene,
           openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else { return }
    SessionReporter.report(openURL: url.absoluteString)
}

// Universal Links arrive via:
func scene(_ scene: UIScene,
           continue userActivity: NSUserActivity) {
    if let url = userActivity.webpageURL {
        SessionReporter.report(openURL: url.absoluteString)
    }
}

Android (Kotlin):

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    intent?.data?.let { uri ->
        SessionReporter.report(uri.toString())
    }
}

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    intent?.data?.let { SessionReporter.report(it.toString()) }
}

openuri와 함께 SESSION 요청 전송

서버에서 캡처한 URL(URL 인코딩)을 openuri로 포함합니다:

curl -G https://s2s.singular.net/api/v1/launch \
  --data-urlencode "a=<SDK key>" \
  --data-urlencode "p=Android" \
  --data-urlencode "i=com.yourcompany.app" \
  --data-urlencode "aifa=<GAID>" \
  --data-urlencode "n=YourAppName" \
  --data-urlencode "openuri=myapp://home/page?queryparam1=value1"

단축 링크 확인

사용자가 단축된 Singular Link를 열었다면, singular_link_resolve_required=true도 함께 전송하세요. Singular이 확장된 긴 링크를 반환하므로 딥링크와 패스스루 값을 파싱할 수 있습니다.

샘플 응답:

{
  "status": "ok",
  "resolved_singular_link": "https://myapp.sng.link/A59c0/nha7?_dl=myapp%3A%2F%2Fdeeplink&_ddl=myapp%3A%2F%2Fdeferred-deeplink&_p=passthroughvalue"
}

동적 패스스루 파라미터

조직에서 링크에 동적 패스스루를 구성한 경우, 딥링크 URL에는 콘텐츠 라우팅을 위한 URL 인코딩된 JSON 문자열 또는 비구조화된 문자열이 포함된 _p 파라미터가 포함됩니다. 동적 패스스루 파라미터를 참조하세요.

레퍼런스: SESSION 엔드포인트 API 레퍼런스 (딥링킹 파라미터).

3단계: SESSION (아웃바운드) — 지연 딥링크를 앱으로 전달

링크를 탭한 후 앱을 설치하는 사용자의 경우, 지연 딥링크는 설치 후 첫 세션에서 Singular이 SESSION 응답으로 반환합니다. 서버는 사용자를 라우팅할 수 있도록 그 값을 앱으로 다시 전달해야 합니다.

첫 세션에서 DDL 요청

설치 후 첫 SESSION 요청에서 다음 두 파라미터를 추가합니다:

샘플 SESSION 요청 (install + DDL 활성화):

curl -G https://s2s.singular.net/api/v1/launch \
  --data-urlencode "a=<SDK key>" \
  --data-urlencode "p=Android" \
  --data-urlencode "i=com.yourcompany.app" \
  --data-urlencode "aifa=<GAID>" \
  --data-urlencode "n=YourAppName" \
  --data-urlencode "install=true" \
  --data-urlencode "ddl_enabled=true"

응답을 읽고 앱으로 전달

설치가 지연 딥링크를 포함한 추적 링크에서 발생한 경우, Singular은 다음을 반환합니다:

샘플 SESSION 응답:

{
  "deferred_deeplink": "myapp://deferred-deeplink",
  "status": "ok",
  "deferred_passthrough": "passthroughvalue"
}

테스트 & 검증

• 지연 딥링크: 앱이 없는 디바이스에서 링크를 탭하고 스토어로 이동하는지 확인합니다. 설치하고 실행하면 앱이 의도한 콘텐츠를 표시해야 합니다.
• 직접 딥링크: 앱이 설치된 상태에서 링크를 탭하고 앱이 의도한 콘텐츠로 바로 열리는지 확인합니다.
• SESSION 순서: Singular SESSION이 모든 이벤트보다 먼저 수신되고, SESSION 응답이 파싱되어 클라이언트로 전달되는지 확인합니다(지연 딥링크에 필수).
• openuri 채움: 딥링크 실행이 타임아웃 윈도우와 관계없이 openuri가 설정된 SESSION을 전송하는지 확인합니다.

테스트 가이드: 연동 테스트하기 | 추적 링크 테스트하기

추가 기능

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

크로스 디바이스 추적

Custom User ID 구현

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

사용자 프라이버시를 유지하면서 포괄적인 크로스 디바이스 리포팅, 유저 레벨 데이터 내보내기, 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")

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

앱 삭제 추적

Silent Push 알림 설정

모든 세션 알림과 함께 푸시 토큰을 전송하여 디바이스 silent push 알림을 사용해 앱 삭제를 추적하세요.

설정 요구사항:

1. 플랫폼별 앱 삭제 추적 설정을 따르세요:
   • iOS 앱 삭제 추적 설정
   • Android 앱 삭제 추적 설정
2. SESSION 요청에 플랫폼별 토큰을 추가하세요:
   • iOS: apns_token (APNs 디바이스 토큰)
   • Android: fcm (FCM 디바이스 토큰)

iOS 설치 영수증

영수증 검증

iOS 세션을 보고할 때 iOS 설치 영수증을 install_receipt 파라미터로 전달하세요.

import Foundation
import StoreKit

class ReceiptManager {
    static func getInstallReceipt() - String? {
        if #available(iOS 18.0, *) {
            let semaphore = DispatchSemaphore(value: 0)
            var result: String?

            Task {
                do {
                    let transaction = try await AppTransaction.shared
                    result = transaction.jwsRepresentation
                    semaphore.signal()
                } catch {
                    debugPrint("Failed to get app transaction: \(error.localizedDescription)")
                    semaphore.signal()
                }
            }

            semaphore.wait()
            return result

        } else {
            guard let receiptURL = Bundle.main.appStoreReceiptURL else {
                debugPrint("Receipt URL not found")
                return nil
            }

            do {
                let receiptData = try Data(contentsOf: receiptURL, options: .uncached)
                return receiptData.base64EncodedString(options: [])
            } catch {
                debugPrint("Failed to read receipt: \(error.localizedDescription)")
                return nil
            }
        }
    }
}

데이터 프라이버시 준수

사용자 동의 처리

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

data_sharing_options 파라미터를 사용하여 사용자 선택을 전달하세요:

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

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

추가 정보: 사용자 프라이버시 및 Limit Data Sharing