서버 대 서버 - 연동 가이드

SDK 연동의 대안으로 완전한 서버 측 추적을 위한 Singular의 REST API를 구현하여 데이터 수집, 전송 및 어트리뷰션 워크플로우를 완벽하게 제어할 수 있습니다.

개요

서버 간 사용 사례

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

연동 접근 방식:

• 순수 S2S: 세션과 이벤트 추적을 모두 처리하는 100% 서버 측 구현
• 하이브리드: 서버 측에서 이벤트 추적을 처리하는 동안 Singular SDK가 세션을 관리합니다.

하이브리드 연동 패턴

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

디바이스 데이터 검색 방법

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

구현 리소스:

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

주요 연동 원칙

연동 요구 사항

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

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

REST API 엔드포인트

Singular는 서버 간 세션 및 이벤트 추적을 위한 두 가지 기본 REST API 엔드포인트를 제공합니다.

세션 엔드포인트

세션 추적 API

세션 엔드포인트는 어트리뷰션 및 리텐션 추적을 위해 사용자 세션을 초기화하기 위해 앱 오픈 이벤트를 Singular에 알립니다.

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

전체 참조: 세션 엔드포인트 API 레퍼런스

이벤트 엔드포인트

이벤트 추적 API

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

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

전체 참조: 이벤트 엔드포인트 API 참조

구현 단계

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

1단계: 데이터 수집

필수 데이터 포인트

Singular 플랫폼 기능에 필요한 모든 필수 파라미터를 캡처하는 강력한 데이터 수집 전략을 수립합니다.

구현 리소스:

• 세션 엔드포인트 필수 파라미터
• 이벤트 엔드포인트 필수 파라미터
• 디바이스 데이터 검색 가이드(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 검색 광고 어트리뷰션

iOS 검색 광고 연동

Apple 검색 광고는 Apple 프레임워크를 통해 플랫폼별 어트리뷰션을 구현해야 하는 SAN(셀프 어트리뷰션 네트워크)입니다.

프레임워크 지원:

• iOS 14.2 이하: iAd 프레임워크
• iOS 14.3 이상: 애드서비스 프레임워크(권장)

전체 가이드: Apple 검색 광고 연동 문서

iAd 프레임워크 구현

iOS 14.2 이하용 iAd 프레임워크를 통해 Apple 검색 광고 어트리뷰션 데이터를 검색하고 전송합니다.

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로 보내기

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

애드서비스 프레임워크 구현

iOS 14.3 이상용 애드서비스 프레임워크를 통해 어트리뷰션 토큰을 검색하고 전송합니다.

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- 토큰을 인코딩하고 설치 및 재설치 후 첫 번째 세션에서 attribution_token 파라미터로 SESSION 엔드포인트에추가합니다.

구글 플레이 인스톨 리퍼러

안드로이드 인스톨 어트리뷰션

구글 플레이 인스톨 리퍼러는 가장 정확한 안드로이드 인스톨 어트리뷰션을 제공하며, 플레이 스토어 도착 전 사용자 출처에 대한 정보를 포함합니다.

추가 정보: 구글 인스톨 리퍼러 문서

구현 단계:

1. Play 인스톨 리퍼러 API를사용하여 앱을 처음 열 때 인스톨 리퍼러를 검색합니다.
2. 필수 속성이 포함된 install_ref JSON 파라미터를 포함한 SESSION 엔드포인트를통해 세션을 보고합니다.

install_ref 속성:

메타 인스톨 리퍼러

페이스북 어트리뷰션 개선

메타 리퍼러는 구글 플레이 인스톨 리퍼러와 메타 인스톨 리퍼러 기술을 결합하여 앱 설치에 대한 세분화된 사용자 수준의 어트리뷰션 데이터를 제공하는 안드로이드 전용 측정 솔루션입니다.

자세히 알아보기: 메타 리퍼러 FAQ

구현 단계:

1. 메타의 설명서에따라 앱을 처음 열 때 메타 인스톨 리퍼러를 검색합니다.
2. 필수 속성이 포함된 meta_ref JSON 파라미터를 포함한 SESSION 엔드포인트를통해 세션을 보고합니다.

meta_ref 속성:

Singular 링크 및 딥링킹

Singular 추적 링크에 대한 딥링킹 및 디퍼드 딥링킹 지원을 구현하여 캠페인에서 특정 인앱 콘텐츠까지 원활한 사용자 경험을 제공할 수 있습니다.

딥링크는 사용자를 앱 내의 특정 콘텐츠로 연결하는 클릭 가능한 링크입니다. 사용자가 앱이 설치된 기기에서 딥링크를 클릭하면 앱이 열리고 특정 제품이나 경험이 표시됩니다.

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

전제 조건

플랫폼 구성

클라이언트 앱은 Singular 링크를 iOS 유니버설 링크 또는 안드로이드 앱 링크로 인식해야 합니다.

구성 가이드: Singular 링크 전제 조건

딥링크 구현

딥링크 캡처

앱이 딥링크를 통해 열리면 openuri 파라미터에 URL 값을 추가하여 openURL 을 캡처하여 세션 요청에 추가합니다. Singular 링크를 사용할 때 필요합니다.

Singular 링크 파라미터:

• _ios_dl 및 _android_dl: 플랫폼마다 다른 딥링크 값으로 링크가 생성된 경우 표시합니다.
• _dl iOS와 안드로이드의 딥링크 값이 동일할 때 표시합니다.
• _p 패스스루 파라미터가 포함된 경우 제시합니다.

딥링크 핸들러 코드

앱에 openURL 을 파싱하고 Singular 링크 파라미터를 적절히 처리하는 핸들러 코드가 있어야 합니다.

class DeepLinkHandler {
    func handleURL(_ url: URL) {
        guard let components = URLComponents(url: url, resolvingAgainstBaseURL: true) else {
            return
        }

        var params: [String: String] = [:]

        // Parse query parameters
        if let queryItems = components.queryItems {
            for item in queryItems {
                switch item.name {
                case "_dl":
                    params["deeplink"] = item.value
                case "_ios_dl":
                    params["ios_deeplink"] = item.value
                case "_p":
                    params["passthrough"] = item.value
                default:
                    break
                }
            }
        }

        // Handle the parsed parameters
        processDeepLinkParameters(params)
    }

    private func processDeepLinkParameters(_ params: [String: String]) {
        // Process the parameters as needed
        print("Processed parameters: \(params)")
    }
}

// In SceneDelegate or AppDelegate
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else { return }
    let handler = DeepLinkHandler()
    handler.handleURL(url)
}

class DeepLinkHandler {
    fun handleDeepLink(intent: Intent) {
        val data: Uri? = intent.data

        data?.let { uri ->
            val params = mutableMapOf<String, String>()

            // Parse query parameters
            uri.queryParameterNames?.forEach { name ->
                when (name) {
                    "_dl" -> params["deeplink"] = uri.getQueryParameter(name) ?: ""
                    "_android_dl" -> params["android_deeplink"] = uri.getQueryParameter(name) ?: ""
                    "_p" -> params["passthrough"] = uri.getQueryParameter(name) ?: ""
                }
            }

            processDeepLinkParameters(params)
        }
    }

    private fun processDeepLinkParameters(params: Map<String, String>) {
        // Process the parameters as needed
        println("Processed parameters: $params")
    }
}

// In your Activity
class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Handle deep link if activity was launched from a deep link
        intent?.let { DeepLinkHandler().handleDeepLink(it) }
    }

    override fun onNewIntent(intent: Intent?) {
        super.onNewIntent(intent)
        // Handle deep link if app was already running
        intent?.let { DeepLinkHandler().handleDeepLink(it) }
    }
}

디퍼드 딥링킹

최초 설치 딥링크

앱 설치 후 처음 앱을 열 때 세션을 Singular에 보고할 때 파라미터를 추가하여 디퍼드 딥링킹을 활성화합니다.

필수 파라미터:

• install=true
• ddl_enabled=true

Singular는 디퍼드 딥링크가 포함된 트래킹 링크를 통해 앱이 설치되었는지 확인합니다. 그렇다면 세션 요청을 반환합니다:

• deferred_deeplink 사용자에게 올바른 제품/경험을 보여주기 위한 딥링크 주소 분석
• deferred_passthrough 딥링크에 패스스루 파라미터 추가

샘플 응답:

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

동적 패스스루 파라미터

Singular 추적 링크에는 맞춤형 사용자 경험을 위한 동적 패스스루 매개변수가 포함될 수 있습니다.

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

자세한 정보: 동적 패스스루 매개변수

짧은 링크 해상도

단축된 Singular 링크에서 앱이 열리면 세션 요청에 파라미터를 포함시켜 짧은 링크를 긴 링크로 해결합니다.

필수 파라미터: 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"
}

추가 기능

종합적인 분석을 위해 교차 기기 추적, 구매 추적, 제거 모니터링, 데이터 개인정보 보호 규정 준수를 구현하세요.

크로스 디바이스 추적

사용자 지정 사용자 ID 구현

custom_user_id 매개변수를 활용하여 사용자를 디바이스 수준 세션과 연결하여 교차 디바이스 보고 및 사용자 수준 분석을 수행할 수 있습니다.

사용자 개인정보를 유지하면서 포괄적인 교차 장치 보고, 사용자 수준 데이터 내보내기 및 내부 BI 포스트백을 사용할 수 있습니다.

자세한 정보: 사용자 지정 사용자 ID 매개변수

구매 추적

인앱 구매 리포팅

인앱 구매의 구매을 추적하여 ROI 분석, 캠페인 성과 측정, 내보내기/포스트백 강화에 활용할 수 있습니다.

구매 파라미터와 함께 이벤트 엔드포인트를사용합니다:

• is_revenue_event 이벤트를 구매 이벤트로 표시합니다(이벤트 이름이 __iap__ 또는 금액이 0 이상인 경우 건너뛰기).
• purchase_receipt Android/iOS 인앱 구매 개체 - 거래 세부 정보 및 보고서 보강에 적극 권장됨
• receipt_signature (안드로이드): 거래 검증 및 사기 방지를 위해 적극 권장됨
• amt: 구매 금액을 두 배로 표시(예: "amt=1.99")
• cur ISO 4217 통화 코드(예: "cur=USD")

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

추적 제거

무음 푸시 알림 설정

모든 세션 알림과 함께 푸시 토큰을 전송하여 기기 무음 푸시 알림을 사용하여 제거를 추적하세요.

설정 요구 사항:

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

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 을 사용하며 규정 준수가 필요한 파트너에게 정보를 전달합니다.

자세한 정보: 사용자 개인정보 보호 및 데이터 공유 제한