SESSION 엔드포인트 API 레퍼런스

SDK 구현 대신 서버 간(server-to-server) 연동을 사용하여 Singular의 REST API를 통해 사용자 세션을 추적하고 앱 설치, 리인게이지먼트, 리텐션 지표에 대한 어트리뷰션을 활성화합니다.

개요

서버 간(Server-to-Server) 사용 사례

Singular REST API를 사용하면 앱이 기기별 데이터를 백엔드로 전달하고, 백엔드가 이를 Singular 서버로 전송하여 어트리뷰션 처리 및 분석 리포팅을 수행하는 직접적인 서버 간 연동이 가능합니다.

지원되는 기능:

설치 어트리뷰션: 마케팅 캠페인에 대한 퍼스트 터치 어트리뷰션
리인게이지먼트 어트리뷰션: 복귀 사용자에 대한 멀티 터치 어트리뷰션
리텐션 지표: 세션 기반 인게이지먼트 추적
이벤트 추적: 커스텀 인앱 이벤트 측정

데이터 흐름 아키텍처

서버 간 연동은 4단계의 데이터 전송 프로세스를 따릅니다.

클라이언트 수집: 앱이 필요한 기기 및 애플리케이션 데이터를 수집합니다
서버 전송: 앱이 수집한 데이터를 백엔드 서버로 전달합니다
Singular API 호출: 서버가 데이터를 Singular REST API 엔드포인트로 전송합니다
응답 처리: 서버가 Singular의 응답을 수신하고 처리합니다

세션 데이터 흐름 다이어그램

주요 고려 사항

필수 요구사항:

실시간 처리: 요청은 개별적으로 처리되며 배치 처리는 지원되지 않습니다
순차적 순서: 이벤트는 시간순으로 전송되어야 합니다
중복 제거 없음: Singular는 데이터를 중복 제거하지 않으므로 서버 측에서 중복 제거를 구현해야 합니다
데이터 영구성: 기기 수준 데이터는 수집된 후 삭제할 수 없으므로 전송하기 전에 검증하십시오
세션 우선: 이벤트 추적 전에 세션이 먼저 설정되어야 합니다

연동의 이점:

유연성: 데이터 수집 및 전송 타이밍에 대한 완전한 제어
기능 동등성: 적절한 데이터가 제공될 경우 모든 SDK 기능 지원
커스텀 구현: 특정 백엔드 아키텍처에 맞게 연동 조정

세션 관리

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

세션을 전송하는 시점

세션 트리거

다음과 같은 앱 라이프사이클 이벤트에 대해 SESSION 요청을 전송하십시오:

신규 설치: 설치 후 최초 앱 실행
종료 상태에서의 실행: 완전히 닫힌 상태에서 앱이 열림
백그라운드에서 포그라운드로 전환: 타임아웃 기간(권장: 60초) 이후 앱이 포그라운드로 복귀

세션 타임아웃 로직

짧은 앱 백그라운드 전환 중에 과도한 SESSION 요청이 발생하는 것을 방지하기 위해 세션 타임아웃을 구현하십시오.

권장 구현:

타임아웃 기간: 60초(1분)
포그라운드 < 타임아웃: 앱이 타임아웃 기간 내에 포그라운드로 복귀하면 SESSION을 전송하지 마십시오
포그라운드 > 타임아웃: 앱이 타임아웃 기간을 초과하여 백그라운드에 유지되면 SESSION을 전송하십시오
앱 라이프사이클 추적: 앱 라이프사이클 이벤트와 타이머를 사용하여 세션 상태를 관리하십시오

딥링크 지원: 딥링크, Universal Link 또는 App Link를 통한 앱 열림의 경우 타임아웃 상태와 관계없이 항상 openuri 파라미터를 채워서 SESSION을 전송하십시오.

어트리뷰션 처리

세션 기반 어트리뷰션

Singular는 SESSION 요청을 처리하여 어트리뷰션 유형을 판단하고 적절한 워크플로우를 트리거합니다.

세션 유형	Singular 처리	어트리뷰션 결과
첫 번째 세션(신규 설치)	설치 어트리뷰션 프로세스가 트리거됨	설치를 마케팅 캠페인에 어트리뷰션함
리인게이지먼트 조건 충족	리인게이지먼트 어트리뷰션 프로세스가 트리거됨	사용자 복귀를 캠페인 또는 딥링크에 어트리뷰션함
표준 세션	리텐션 추적을 위해 세션이 기록됨	사용자 활동 및 인게이지먼트 지표에 반영됨

자세히 알아보기: 리인게이지먼트 어트리뷰션 FAQ

이벤트 순서 요구사항

세션 및 이벤트 타이밍은 어트리뷰션 정확도와 데이터 품질에 직접적인 영향을 미칩니다.

필수 순서 규칙:

이벤트 이전의 세션: 해당 세션에 대한 이벤트가 발생하기 전에 하나의 SESSION이 수신되어야 합니다
실시간 이벤트 전송: 인앱 이벤트는 해당 세션 이후 실시간으로 전송되어야 합니다
순차적 처리: 잘못된 세션 순서는 데이터 불일치 및 어트리뷰션 오류를 초래합니다

고급 옵션

확장 기능

Singular S2S 연동은 추가 SESSION 파라미터가 필요한 고급 기능을 지원합니다.

고급 기능: 딥링킹, SKAdNetwork 및 크로스 디바이스 추적 요구사항에 대해서는 고급 S2S 옵션 을 참조하십시오.

API 엔드포인트 사양

SESSION 엔드포인트는 기기, 애플리케이션 및 어트리뷰션 데이터를 포함하는 쿼리 파라미터가 있는 GET 요청을 허용합니다.

엔드포인트 URL

기본 URL 및 메서드

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

요청 형식:

GET /api/v1/launch?param1=value1&param2=value2

요청 본문: 요청 본문을 제공하지 마십시오. 모든 파라미터는 GET 메서드를 사용하여 URL 쿼리 파라미터로 전송되어야 합니다.

필수 파라미터

모든 SESSION 요청에는 올바른 값과 형식을 갖춘 이러한 필수 파라미터가 포함되어야 합니다.

API 인증

SDK Key

이는 S2S 기본 사항 에서 한 번 정의된 공유 S2S 파라미터입니다.

기기 식별자

플랫폼별 식별자

이는 S2S 기본 사항 에서 한 번 정의된 공유 S2S 파라미터입니다.

기기 파라미터

기기 정보

이는 S2S 기본 사항 에서 한 번 정의된 공유 S2S 파라미터입니다.

애플리케이션 파라미터

앱 정보

앱 식별자( i ), app_v 및 att_authorization_status 는 공유 파라미터입니다. S2S 기본 사항의 애플리케이션 파라미터 를 참조하십시오.

파라미터 세부 정보


        install

boolean

세션이 설치 또는 재설치 후 첫 번째 세션을 나타내는지 여부를 표시합니다.

true - 신규 설치/재설치 후 첫 번째 세션
false - 후속 세션(앱이 이미 설치됨)

필요 대상: 재설치 추적 기능

예시: true


        install_time

iOS, Android

integer

첫 번째 앱 설치의 Unix 타임스탬프.

예시: 1510040127


        update_time

iOS, Android

integer

마지막 앱 업데이트의 Unix 타임스탬프.

예시: 1510040127

부정 방지 파라미터

설치 소스 검증

파라미터 세부 정보


        install_source

Android, PC

string

설치 소스 패키지 이름 또는 스토어 식별자.

Android: Install Source Package Name

Android 예시: com.android.vending (Google Play Store)

PC 지원 스토어:

steam
epic
microsoftstore
humblestore
gog
selfdistributed


        install_receipt

iOS

string

부정 검증을 위한 Base64로 인코딩된 iOS 설치 영수증.

예시(축약): MIJF9wYJKoZIhvcNAQcCoIJF6DCCReQCAQExCzAJBgUrDgMCGgUAMII1m...

딥링킹 파라미터

딥링크 지원

파라미터 세부 정보


        openuri

iOS, Android

string

앱을 연 URL로 인코딩된 딥링크, Universal Link 또는 App Link.

원본 URL: myapp://home/page?queryparam1=value1&queryparam2=value2

인코딩된 예시: myapp%3A%2F%2Fhome%2Fpage%3Fqueryparam1%3Dvalue1%26queryparam2%3Dvalue2


        ddl_enabled

iOS, Android

boolean

앱이 응답에 디퍼드 딥링크 URL을 기대하는지 여부를 표시합니다.

true - 응답에 디퍼드 딥링크를 기대함
false - 디퍼드 딥링크를 기대하지 않음

응답 예시:

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


        singular_link_resolve_required

iOS, Android

boolean

Singular 숏 링크를 롱 링크로 해석(resolve)하도록 요청합니다. Singular 숏 링크를 포함하는 openuri 와 함께 사용해야 합니다.

true - 확장된 롱 링크 반환
false - 링크를 해석하지 않음

응답 예시:

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

고급 어트리뷰션 파라미터

플랫폼 어트리뷰션 강화

파라미터 세부 정보


        install_ref

Android (Google Play)
Native PC (Google Play Games)

JSON

JSON URL로 인코딩된 Google Install Referrer 정보. Android 및 Google Play Games PC 설치에 대해 가장 정확한 어트리뷰션을 제공합니다.

Android JSON 구조:

{
   "installBeginTimestampSeconds":"1568939453",
   "referrer":"utm_source=google-play&utm_medium=organic",
   "clickTimestampSeconds":"0",
   "referrer_source":"service",
   "current_device_time":"1568944524"
}

Native PC JSON 구조:

{
   "install_time_epoch_seconds":"1568939453",
   "install_referrer":"utm_source=google-play&utm_medium=organic"
}

필요 대상:

Facebook 사용자 수준 내보내기
Data Destination 공유
포스트백 정확도

추가 정보:

URL로 인코딩된 예시: %7B%22installBeginTimestampSeconds%22%3A%221568939453%22...


        meta_ref

Android (Google Play)

JSON

2025년 6월 18일부로: Meta Advanced Mobile Measurement (AMM) 이 Meta Install Referrer 구현의 필요성을 제거합니다. AMM이 활성화된 경우 권장되지 않습니다.

세분화된 사용자 수준 어트리뷰션 데이터를 위한 JSON URL로 인코딩된 Meta Install Referrer.

JSON 구조:

{
  "install_referrer": {
    "utm_source":"apps.facebook.com",
    "utm_campaign": "fb4a",
    "utm_content": {
      "source":{
        "data":"c7e6b890bf18a059c2185650bdb1af3dced7...",
        "nonce":"24859720343e2381daee9f39ae61"
        },
      "app":533744218636280,
      "t":1731181327
      },
    "is_ct":1,
    "actual_timestamp":1731181444
  }
}

자세히 알아보기: Meta Referrer FAQ


        attribution_token

iOS

string

AdServices 프레임워크(iOS 14.3+)의 Apple Search Ads 어트리뷰션 토큰.

검색 방법: 설치/재설치 후 첫 번째 앱 실행 시 attributionToken() 사용.

예시(축약): KztLg%2FIkNsWDMuBMOU%2BySnkPU5myJb4OFmeaMUE%2BTqQJP...

선택 파라미터

선택 파라미터는 추적 기능을 강화하고 고급 기능을 지원합니다.

타임스탬프 파라미터

파라미터 세부 정보


        utime

integer

세션의 10자리 Unix 타임스탬프.

예시: 1483228800


        umilisec

integer

밀리초를 포함한 13자리 Unix 타임스탬프.

예시: 1483228800000

네트워크 & 위치 파라미터

이는 S2S 기본 사항 에서 한 번 정의된 공유 S2S 파라미터입니다.

커스텀 속성

파라미터 세부 정보


        global_properties

JSON

커스텀 키-값 쌍이 포함된 URL로 인코딩된 JSON 객체.

제한:

최대 5개의 키-값 쌍
키와 값당 최대 200자

JSON: {"key1":"value1","key2":"value2"}

URL로 인코딩됨: %7B%22key1%22%3A%22value1%22%2C%22key2%22%3A%22value2%22%7D

앱 삭제 추적 지원

파라미터 세부 정보


        apns_token

iOS

string

16진수로 인코딩된 Apple Push Notification Service (APNs) 기기 토큰.

iOS 앱 삭제 추적에 필요
16진수로 인코딩된 문자열이어야 함
APNs 토큰 검색

예시: b0adf7c9730763f88e1a048e28c68a9f806ed032fb522debff5bfba010a9b052

fcm

Android

string

Firebase Cloud Messaging 기기 토큰.

Android 앱 삭제 추적에 필요
FCM 토큰 검색

예시: bk3RNwTe3H0CI2k_HHwgIpoDKCIZvvD...MExUdFQ3P1

데이터 개인정보 보호 파라미터

이는 S2S 기본 사항 에서 한 번 정의된 공유 S2S 파라미터입니다.

크로스 디바이스 지원

이는 S2S 기본 사항 에서 한 번 정의된 공유 S2S 파라미터입니다.

SKAdNetwork 지원

파라미터 세부 정보


        skan_conversion_value

iOS

integer

세션 시점의 최신 SKAdNetwork 전환값.

자세히 알아보기: SKAdNetwork 구현

예시: 7


        skan_first_call_timestamp

iOS

integer

SKAdNetwork API에 대한 첫 번째 호출의 Unix 타임스탬프.

예시: 1483228800


        skan_last_call_timestamp

iOS

integer

세션 시점의 SKAdNetwork API에 대한 가장 최근 호출의 Unix 타임스탬프.

예시: 1483228800

Google Ads ICM 지원 (베타)

파라미터 세부 정보


        odm_info

iOS

string

Google Ads Integrated Conversion Measurement (베타)에 필요합니다.

Google Ads ICM 문서


        odm_error

iOS

string

Google Ads Integrated Conversion Measurement (베타)에 필요합니다.

Google Ads ICM 문서

요청 예시

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

예시 관련 고지: 코드 샘플에는 필요한 모든 파라미터가 포함되지 않을 수 있습니다. 프로덕션 구현 전에 전체 파라미터 목록을 검증하십시오. 개발/테스트에는 고유한 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',
    'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
    'asid': 'edee92a2-7b2f-45f4-a509-840f170fc6d9',
    'install': 'true',
    'n': 'MyCoolAppName',
    'bd': 'Build/13D15',
    'app_v': '1.2.3',
    'openuri': 'myapp://home/page?queryparam1=value1',
    'ddl_enabled': 'true',
    'install_source': 'com.android.vending',
    'install_time': 1510040127,
    'update_time': 1510090877
}

response = requests.get('https://s2s.singular.net/api/v1/launch', params=params)
print(response.json())

cURL 예시

curl -G "https://s2s.singular.net/api/v1/launch" \
  --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 "aifa=8ecd7512-2864-440c-93f3-a3cabe62525b" \
  --data-urlencode "asid=edee92a2-7b2f-45f4-a509-840f170fc6d9" \
  --data-urlencode "install=true" \
  --data-urlencode "n=MyCoolAppName" \
  --data-urlencode "bd=Build/13D15" \
  --data-urlencode "app_v=1.2.3" \
  --data-urlencode "openuri=myapp://home/page?queryparam1=value1" \
  --data-urlencode "ddl_enabled=true" \
  --data-urlencode "install_source=com.android.vending" \
  --data-urlencode "install_time=1510040127" \
  --data-urlencode "update_time=1510090877"

HTTP 예시

GET /api/v1/launch
    ?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
    &aifa=8ecd7512-2864-440c-93f3-a3cabe62525b
    &asid=edee92a2-7b2f-45f4-a509-840f170fc6d9
    &install=true
    &n=MyCoolAppName
    &bd=Build%2F13D15
    &app_v=1.2.3
    &openuri=myapp%3A%2F%2Fhome%2Fpage%3Fqueryparam1%3Dvalue1
    &ddl_enabled=true
    &install_source=com.android.vending
    &install_time=1510040127
    &update_time=1510090877 HTTP/1.1
Host: s2s.singular.net
Accept: application/json

Java 예시

// Base URL
String baseUrl = "https://s2s.singular.net/api/v1/launch";

// 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("aifa", "8ecd7512-2864-440c-93f3-a3cabe62525b");
params.put("asid", "edee92a2-7b2f-45f4-a509-840f170fc6d9");
params.put("install", "true");
params.put("n", "MyCoolAppName");
params.put("bd", "Build/13D15");
params.put("app_v", "1.2.3");
params.put("openuri", "myapp://home/page?queryparam1=value1");
params.put("ddl_enabled", "true");
params.put("install_source", "com.android.vending");
params.put("install_time", "1510040127");
params.put("update_time", "1510090877");

// 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();

응답 코드 & 오류

SESSION 엔드포인트는 요청 성공 또는 실패를 나타내는 HTTP 상태 코드와 JSON 응답을 반환합니다.

전체 오류 문서: S2S 응답 코드 & 오류 처리

테스트 & 검증

실시간 데이터 검증을 위해 Singular SDK Console을 사용하여 프로덕션 배포 전에 S2S 연동을 확인하십시오.

테스트 절차

엔드투엔드 검증

테스트 기기 등록: 기기 광고 ID를 확보하여 Singular SDK Console 에 추가합니다
콘솔 로깅 활성화: 테스트 데이터를 캡처하기 위해 SDK Console에 기기 식별자를 추가합니다
개발용 앱 ID 사용: 테스트 데이터를 프로덕션 데이터와 분리하기 위해 앱 식별자를 개발 버전(예: com.singular.app.dev )으로 재정의합니다
앱 실행: 종료 상태에서 앱을 열어 세션을 트리거합니다
클라이언트 데이터 검증: 앱이 필요한 모든 Singular 데이터 포인트를 서버로 전송하는지 확인합니다
서버 요청 확인: 서버가 필요한 모든 파라미터와 함께 https://s2s.singular.net/api/v1/launch 로 SESSION 요청을 전송하는지 확인합니다
SDK Console 확인: 몇 초 내에 SESSION 이벤트가 SDK Console에 나타나야 합니다
테스트 반복: 모든 앱 진입 및 포그라운드 작업에서 SESSION이 트리거되는지 검증합니다

SDK Console 세션 이벤트

필수 검증: EVENT 요청 전에 앱 열림/포그라운드에서 SESSION 이벤트가 발생하는지 확인하십시오. 잘못된 순서는 어트리뷰션 오류를 유발합니다.

성공 지표: SESSION이 SDK Console에 나타나면 성공적인 엔드투엔드 연동 테스트를 완료한 것입니다!

추가 리소스

테스트 문서

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

서버 간(Server-to-Server) - SESSION 엔드포인트 API 레퍼런스

SESSION 엔드포인트 API 레퍼런스

개요

서버 간(Server-to-Server) 사용 사례

데이터 흐름 아키텍처

주요 고려 사항

세션 관리

세션을 전송하는 시점

세션 트리거

세션 타임아웃 로직

어트리뷰션 처리

세션 기반 어트리뷰션

이벤트 순서 요구사항

고급 옵션

확장 기능

API 엔드포인트 사양

엔드포인트 URL

기본 URL 및 메서드

필수 파라미터

API 인증

SDK Key

기기 식별자

플랫폼별 식별자

기기 파라미터

기기 정보

애플리케이션 파라미터

앱 정보

부정 방지 파라미터

설치 소스 검증

딥링킹 파라미터

딥링크 지원

고급 어트리뷰션 파라미터

플랫폼 어트리뷰션 강화

선택 파라미터

타임스탬프 파라미터

네트워크 & 위치 파라미터

커스텀 속성

앱 삭제 추적 지원

데이터 개인정보 보호 파라미터

크로스 디바이스 지원

SKAdNetwork 지원

Google Ads ICM 지원 (베타)

요청 예시

Python 예시

cURL 예시

HTTP 예시

Java 예시

응답 코드 & 오류

테스트 & 검증

테스트 절차

엔드투엔드 검증

추가 리소스

테스트 문서