세션 엔드포인트 API 참조

세션 엔드포인트 API 참조

서버 간 사용 사례

Singular REST API를 사용하면 SDK의 대안으로 서버 간 직접 연동이 가능합니다. 런치 또는 세션 엔드포인트를 사용하면 애플리케이션에서 세션 추적이 가능합니다. 앱이 디바이스별 데이터를 서버로 전달하고, 서버가 해당 데이터를 Singular의 서버로 전송하면, Singular 플랫폼은 이 정보를 처리합니다: 인스톨 어트리뷰션, 리인게이지먼트 어트리뷰션, 리텐션 지표에 대한 정보를 처리합니다. 이렇게 처리된 데이터는 보고서, 내보내기 로그, 구성된 포스트백을 자동으로 채우고 마케팅 캠페인에 대한 종합적인 분석을 제공합니다.

SDK는 디바이스 및 앱 데이터를 자동으로 수집하지만, S2S 접근 방식은 사용자가 직접 수집해야 합니다:

  1. 앱에서 필요한 데이터 포인트 수집
  2. 이 데이터를 서버로 전달
  3. REST API를 통해 Singular로 전송
  4. Singular의 응답을 앱에 다시 전달

session-data-flow.png

핵심 포인트

  • 유연성: 데이터 수집 및 전송에 대한 완전한 제어
  • 기능 패리티: 적절한 데이터 제공 시 모든 SDK 기능 지원
  • 연동 경로: 클라이언트 → 서버 → Singular API
  • 실시간 처리: 한 번에 하나의 요청만 처리, 일괄 처리 없음
  • 순차적 데이터 흐름: 이벤트는 시간 순서대로 처리해야 합니다.
  • 데이터 중복 제거: Singular: 수신된 데이터는 중복 제거되지 않습니다. 요청을 재생해야 하는 경우 성공적인 요청을 하나(1)만 보내고 로그를 저장하는 것이 좋습니다.
  • 데이터 유효성 검사: 디바이스 수준 데이터는 영구적이며 한번 수집된 데이터는 삭제할 수 없습니다. Singular에 데이터를 전송하기 전에 철저한 데이터 유효성 검사를 구현하여 정확성을 보장하세요.

세션 관리

런치 엔드포인트는 새로운 사용자 세션에 대한 앱 열기 이벤트를 Singular에 알리는 데 사용됩니다.

  • 세션 초기화(실행 요청)에 필요합니다:
    • 신규 앱 설치
    • 종료된 상태에서 앱 실행
    • 앱이 백그라운드에서 포그라운드로 돌아오는 경우
  • 이벤트 추적 전에 세션을 설정해야 합니다.
  • 잘못된 세션 순서는 데이터 불일치를 초래합니다.
  • 세션 타임아웃을 구현하고 지난 1분 이내에 앱을 사용하지 않은 경우에만 Singular에게 세션 알림을 보내는 것이 좋습니다. 사용자가 앱을 백그라운딩한 다음 1분 이내에 앱을 포그라운드하는 경우 Singular 세션이 트리거되지 않지만, 1분 이상 포그라운드하는 경우 세션이 트리거됩니다.
  • 딥링킹을 지원하려면 항상 'open_uri' 파라미터에 openURL을 사용하여 앱 오픈에 대한 세션을 전송해야 합니다.

시작하기

세션 엔드포인트 설명서를 참조하세요:

세션 알림 엔드포인트에 추가 매개변수를 포함해야 하는 Singular의 서버 간(S2S) 연동의 고급 옵션을 검토하세요. 여기에서 고급 옵션에 대해 자세히 알아보세요.

세션 보고

Singular와의 가장 기본적인 연동은 사용자 세션이 발생할 때 Singular에 알림을 보내 Singular가 여러 내부 프로세스를 트리거할 수 있도록 하는 것입니다:

  • 특정 디바이스에서 앱의 첫 번째 세션인 경우, Singular는 새로운 인스톨을 인식하고 인스톨 어트리뷰션 프로세스를 트리거합니다.
  • 해당 세션이 리인게이지먼트 세션에 해당하는 경우, Singular는 리인게이지먼트 어트리뷰션 프로세스를 트리거합니다( 리인게이지먼트 FAQ에서 자세히 알아보기).
  • 그렇지 않으면 Singular는 이를 세션으로 표시하여 사용자 활동 및 리텐션 지표를 추적하는 데 사용합니다.

세션 요청과 Singular 서버에 대한 후속 이벤트 요청의 타이밍은 매우 중요합니다:

  1. 이벤트가 발생하기 전에 Singular 세션이 수신되어야 합니다.
    예를 들어, 사용자가 앱 사용을 시작할 때 앱 열기에서 세션을 트리거하고, 세션에 이어 인앱 이벤트가 전송될 수 있습니다. 사용자가 앱을 백그라운드에서 장시간(1분 이상) 사용하면 세션이 시간 초과됩니다. 앱이 다시 포그라운드로 돌아오면 다른 세션이 전송됩니다. 앱 수명 주기 이벤트와 타이머를 사용하여 세션 관리를 관리하고 Singular에 대한 세션 요청을 규제하는 것이 좋습니다.
  2. 앱에서 발생하는 이벤트는 해당 세션 이후에 실시간으로 전송되어야 합니다.

세션 API 엔드포인트

HTTP 메서드 및 세션 엔드포인트

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

필수 파라미터

다음 표에는 이 엔드포인트가 지원하는 필수 파라미터가 나열되어 있습니다. 나열된 모든 매개변수는 쿼리 매개변수입니다.

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

 

  • 모든 필수 매개변수는 세션 API 요청에 포함되어야 합니다.
  • 매개변수는 지정된 형식과 데이터 유형을 따라야 합니다.
필수 파라미터
API 키
파라미터 설명
a
string

a 매개변수는 Singular SDK 키를 지정합니다.

메인 메뉴의 개발자 도구 아래 Singular UI에서 SDK 키를 검색합니다.

참고: 보고 API 키는 데이터가 거부될 수 있으므로 사용하지 마세요.

 

예시 값:
sdkKey_afdadsf7asf56
디바이스 식별자 매개변수
파라미터 설명
idfa

지원되는 플랫폼:

  • iOS
string

idfa 매개변수는 광고주가 사용자 행동(예: 광고 클릭, 앱 설치)을 추적하고 특정 캠페인에 어트리뷰션하여 정확한 광고 타겟팅 및 캠페인 최적화를 가능하게 하는 광고주 식별자(IDFA) 를 지정하는 매개변수입니다.

iOS 14.5부터는 앱이 IDFA에 액세스하기 전에 사용자가 ATT(앱 추적 투명성) 프레임워크를 통해 옵트인해야 합니다. 사용자가 IDFA에 옵트인하지 않으면 IDFA를 사용할 수 없게 되어 추적 기능이 제한됩니다.

  • IDFA를 사용할 수 없는 경우 요청에서 매개 변수를 생략하세요.
  • 요청에 NULL 또는 빈 문자열을 전달하지 마세요.
  • IDFA 식별자를 검색하는 방법

 

예제 값:
DFC5A647-9043-4699-B2A5-76F03A97064B
파라미터 설명
idfv

지원되는 플랫폼:

  • iOS
string

idfv 매개변수는 특정 공급업체 또는 개발자에게만 해당하는 Apple이 디바이스에 할당하는 고유 식별자인 IDFV(공급업체용 식별자)를 지정합니다. 특정 디바이스에서 동일한 공급업체의 모든 앱에서 일관성을 유지하므로 공급업체는 사용자를 개인적으로 식별하지 않고도 앱 생태계 전반에서 사용자 행동과 상호 작용을 추적할 수 있습니다.

 

예제 값:
21DB6612-09B3-4ECC-84AC-B353B0AF1334
파라미터 설명
aifa

지원되는 플랫폼입니다:

  • Android
    (구글 플레이 기기)
string

aifa 매개변수는 Google 광고 식별자(GAID)를 지정하며, Singular 또는 Android 광고 ID(AAID)로도 알려져 있습니다. 이 식별자는 Android 기기에 할당된 사용자 재설정이 가능한 고유 식별자입니다. 이를 통해 광고주와 앱 개발자는 앱 전반의 사용자 행동(예: 광고 클릭, 앱 설치)을 추적하고 특정 캠페인에 어트리뷰션하여 사용자 개인정보를 유지하면서 정확한 광고 타겟팅 및 캠페인 최적화를 수행할 수 있습니다.

  • AIFA를 사용할 수 없는 경우 요청에서 매개변수를 생략하세요.
  • Google Play 기기에서만 필요합니다.
  • Google Play 이외의 기기에서는 매개변수를 생략하세요.
  • 요청에 NULL 또는 빈 문자열을 전달하지 마세요.
  • AIFA 식별자를 검색하는 방법

 

예제 값:
8ecd7512-2864-440c-93f3-a3cabe62525b
파라미터 설명
asid

지원되는 플랫폼입니다:

  • Android
    (구글 플레이 기기)
string

asid 매개변수는 안드로이드 앱 세트 ID를 지정합니다. ASID는 개발자가 개인정보 보호를 고려한 방식으로 자신의 앱에서 사용자를 추적할 수 있는 방법을 제공합니다. 분석 및 사기 방지에 특히 유용하지만 개인 맞춤형 광고나 측정과 같은 광고 목적으로는 사용할 수 없습니다.

  • ASID는 GAID/AIFA 존재 여부와 관계없이 모든 Google Play 기기 요청에 필요합니다.
  • Google Play 기기가 아닌 기기에서는 매개변수를 생략하세요.
  • 요청에 NULL 또는 빈 문자열을 전달하지 마세요.
  • ASID 식별자를 검색하는 방법

 

예시 값:
edee92a2-7b2f-45f4-a509-840f170fc6d9
파라미터 설명
amid

지원되는 플랫폼입니다:

  • Android
    (구글 플레이 서비스가 없는 아마존 디바이스)
string

amid 매개변수는 사용자의 개인정보를 보호하는 데 도움이 되는 사용자 재설정이 가능한 고유 식별자인 광고 ID를 지정합니다. 관심사 기반 광고를 표시하거나 분석을 생성하기 위해 사용자의 행동에 대한 정보를 수집하는 경우 광고 ID를 사용해야 하며, 다른 식별자나 추적 방법을 사용할 수 없습니다. 사용자는 광고 ID를 재설정하거나 관심사 기반 광고를 모두 수신 거부할 수 있습니다.

  • AMID는 Google Play 서비스가 없는 Amazon 기기에 대한 모든 요청에 필요합니다.
  • AMID를 사용할 수 없는 경우 매개 변수를 생략합니다.
  • 요청에 NULL 또는 빈 문자열을 전달하지 마세요.
  • AMID 식별자를 검색하는 방법

 

예제 값:
df07c7dc-cea7-4a89-b328-810ff5acb15d
파라미터 설명
oaid

지원되는 플랫폼입니다:

  • Android
    (구글 플레이 서비스가 없는 중국 제조 기기)
string

oaid 매개변수는 OAID(오픈 광고 식별자)를 지정합니다. OAID는 Android 기기, 특히 중국에서 제조된 기기에서 광고 목적으로 사용되는 고유한 익명 식별자입니다. 중국 시장과 같이 구글 플레이 서비스를 사용할 수 없거나 지원하지 않는 기기에서 구글의 광고 ID(GAID)를 대체하기 위해 모바일 보안 연합(MSA)에서 도입했습니다.

OAID는 주로 Google Play 서비스가 제한된 환경에서 광고 어트리뷰션 및 사용자 추적에 사용되며, 광고주와 개발자가 익명성을 유지하면서 사용자 행동을 추적할 수 있도록 합니다.

OAID는 화웨이, 샤오미 등의 브랜드를 포함한 대부분의 중국 제조 안드로이드 기기에서 사용할 수 있습니다. MSA SDK 또는 화웨이 모바일 서비스(HMS)를 사용하여 액세스할 수 있습니다.

  • 구글 플레이 서비스가 없는 중국산 Android 기기에서는 OAID가 필요합니다.
  • OAID를 사용할 수 없는 경우 매개 변수를 생략하세요.
  • 요청에 NULL 또는 빈 문자열을 전달하지 마세요.
  • OAID 식별자를 검색하는 방법

 

예제 값:
01234567-89abc-defe-dcba-987654321012
파라미터 설명
andi

지원되는 플랫폼입니다:

  • Android
    (구글 플레이 기기가 아닌 기기)
string

andi 매개변수는 디바이스를 처음 설정할 때 Android 운영 체제에서 생성되는 64비트 고유 식별자인 Android ID를 지정합니다. 이는 디바이스의 수명 기간 동안 지속되도록 설계되었지만 공장 초기화와 같은 특정 조건에서는 초기화될 수 있습니다.

안드로이드 ID는 각 디바이스마다 고유하며, 안드로이드 8.0(오레오)부터는 앱과 사용자별로 범위가 지정됩니다. 즉, 동일한 디바이스에 있는 여러 앱은 동일한 서명 키를 공유하지 않는 한 서로 다른 Android ID를 받게 됩니다.

Android ID는 디바이스를 초기화하거나 OTA(무선) 업데이트 후 앱을 삭제했다가 다시 설치하지 않는 한 일정하게 유지됩니다.

  • ANDI는 Google Play 기기에서 사용이 금지되어 있습니다. 위에 언급된 AIFA 및 ASID 식별자를 사용하세요.
  • 다른 식별자를 사용할 수 없고 앱이 Google Play 스토어에서 호스팅되지 않는 경우에만 ANDI를 Singular로 전송할 수 있습니다.
  • 다른 식별자를 사용할 수 있는 경우 매개변수를 생략하세요.
  • 요청에 NULL 또는 빈 문자열을 전달하지 마세요.
  • ANDI 식별자를 검색하는 방법

 

예제 값:
fc8d449516de0dfb
매개변수 설명
sdid

지원되는 플랫폼입니다:

  • PC
  • Xbox
  • 플레이스테이션
  • Nintendo
  • 메타퀘스트
  • CTV
string

sdid 파라미터는 Singular 디바이스 ID를 지정합니다. 이 값은 고유한 앱 설치를 나타내는 클라이언트 측에서 생성된 UUIDv4입니다. 이는 PC 및 콘솔 애플리케이션에 사용되는 유일한 디바이스 식별자입니다.

 

예제 값:
40009df0-d618-4d81-9da1-cbb3337b8dec
파라미터 설명
sing

지원되는 플랫폼:

  • 특수 사용 사례에 제한됨
  • 자세한 내용은 솔루션 엔지니어 또는 CSM에게 문의하세요.
string

sing 매개변수는 기업 고객으로 제한되며 고객 정의 식별자를 지정합니다. 다른 모든 식별자를 사용할 수 없는 특수한 용도로만 사용됩니다. 이 식별자는 앱별 솔루션 엔지니어가 앱 단위로 활성화해야 합니다.

 

예제 값:
da534a95-1b1b-47d4-94b6-07955ec85177
디바이스 파라미터
파라미터 설명
p
string

p 매개변수는 앱의 플랫폼을 지정합니다.

다음 목록에는 허용되는 대소문자를 구분하는 매개변수 값이 포함되어 있습니다:

  • Android
  • iOS
  • PC
  • Xbox
  • Playstation
  • Nintendo
  • 메타퀘스트
  • CTV

 

예제 값입니다:
Android
매개변수 설명
ip
string

ip 매개변수는 디바이스의 공인(IPV4) IP 주소를 지정합니다. IPV6는 지원되지 않습니다.

 

값 예시:
172.58.29.235
매개변수 설명
ve
string

ve 매개변수는 세션 시점의 디바이스 OS 버전을 지정합니다.

 

예제 값입니다:
9.2
매개변수 설명
ma

지원되는 플랫폼입니다:

  • Android
  • iOS
string

ma 매개변수는 디바이스 하드웨어의 제조사(일반적으로 소비자 대상 이름)를 지정합니다. 이 파라미터는 model 파라미터와 함께 사용해야 합니다.

디바이스 제조사를 검색하는 방법

 

예시:
Samsung, LG, Apple
파라미터 설명
mo

지원되는 플랫폼:

  • Android
  • iOS
string

mo 매개변수는 디바이스 하드웨어의 모델을 지정합니다. 이 매개 변수는 make 매개 변수와 함께 사용해야 합니다.

디바이스 모델을 검색하는 방법

 

예시:
iPhone 4S, Galaxy SIII
파라미터 설명
lc

지원되는 플랫폼:

  • Android
  • iOS
string

lc 매개변수는 밑줄로 구분된 두 글자의 언어와 국가 코드를 사용하여 디바이스에 대한 IETF 로캘 태그를 지정합니다.

디바이스 로캘을 검색하는 방법

 

값 예시:
en_US
파라미터 설명
bd

지원되는 플랫폼입니다:

  • Android
  • iOS
string

bd 매개변수는 URL로 인코딩된 디바이스의 빌드를 지정합니다.

디바이스 빌드를 검색하는 방법

 

예제 값입니다:
Build%2F13D15
애플리케이션 파라미터
파라미터 설명
i
string

i 매개변수는 앱 식별자를 지정합니다.

Android의 경우 패키지 이름, iOS의 경우 번들 ID 또는 애플리케이션의 대소문자를 구분하는 매개변수 값입니다:

  • Android의 경우 패키지 이름
  • iOS용 번들 ID
  • PC, Xbox, Playstation, Nintendo, MetaQuest 또는 CTV의 경우 지정된 식별자입니다.

 

예시 값입니다:
com.singular.app
파라미터 설명
app_v
string

app_v 매개변수는 애플리케이션 버전을 지정합니다.

 

예시:
1.2.3
매개변수 설명
install
string

install 매개변수는 이 세션이 설치 또는 재설치 후 첫 번째 세션을 나타내는지 여부를 지정합니다. 앱을 설치한 후 첫 번째 세션인 경우'true'를, 앱이 이미 설치되어 있고 후속 세션 또는 앱이 열려 있는 경우'false'를 전달합니다. 이 매개변수는 재설치 추적 기능에 필요합니다.

 

예시
true
파라미터 설명
install_time

지원되는 플랫폼:

  • Android
  • iOS
int

install_time 매개변수는 첫 번째 앱 설치 시간을 UNIX 시간으로 지정합니다. 이 값을 검색하려면 플랫폼의 링크를 사용합니다.

 

값 예시:
1510040127
매개변수 설명
update_time

지원되는 플랫폼입니다:

  • Android
  • iOS
int

update_time 매개변수는 마지막 앱 업데이트 시간을 UNIX 시간으로 지정합니다. 이 값을 검색하려면 플랫폼의 링크를 사용합니다.

 

예제 값:
1510040127
매개변수 설명
att_authorization_status

지원되는 플랫폼:

  • iOS
int

att_authorization_status 매개변수는 앱 추적 투명성(ATT) 상태 코드를 지정합니다. iOS 14.5부터는 IDFA 식별자에 액세스하기 위해 ATT(앱 추적 투명성) 프롬프트가 필요합니다.

참고: ATT 프롬프트를 구현하지 않더라도 "미결정"을 나타내는'0' 값으로 ATT 인증 상태를 전달해야 합니다.

지원되는 값은 다음과 같습니다:

  • 0 - 미결정.
  • 1 - 제한됨, 사용자가 앱 추적을 비활성화했습니다.
  • 2 - 거부됨: 사용자가 권한 부여를 거부했습니다.
  • 3 - 승인됨, 사용자가 권한을 부여했습니다.

 

예시:
3
사기 매개변수
파라미터 설명
install_source

지원되는 플랫폼:

  • Android
  • PC
string

install_source 매개변수는 Android에서 설치 소스 패키지 이름을 지정합니다. PC의 설치 소스로 권장되는 값은 설치 스토어입니다.

PC에서 지원되는 설치 스토어 이름은 다음과 같습니다:

  • steam
  • epic
  • microsoftstore
  • humblestore
  • gog
  • 자체 배포

 

Android(구글 플레이 스토어)의 예시입니다:

com.vending.android
파라미터 설명
install_receipt

지원 플랫폼:

  • iOS
string

install_receipt 매개변수는 설치 시 받은 영수증을 지정합니다. iOS 설치 영수증에서 검색하는 방법을 알아보세요.

 

iOS에서 받은 base64 인코딩된 영수증 문자열의 예입니다:
MIJF9wYJKoZIhvcNAQcCoIJF6DCCReQCAQExCzAJBgUrDgMCGgUAMII1mAYJKoZIhvcNAQcBoII1iQSCNYUxgjWBMAoCAQgCAQEEAhYAMAoCARQCAQEEAgwAMAsCAQECAQEEAwIBADALAgELAgEBBAMCAQAwCwIBDwIBAQQDAgEAMAsCARACAQEEAwIBADALAgEZAgEBBAMCAQMwDAIBAwIBAQQEDAIyNTAMAgEKAgEBBAQWAjQrMAwCAQ4CAQEEBAICAM8wDQIBDQIBAQQFAgMCIuAwDQIBEwIBAQQFDAMxLjAwDgIBCQIBAQQGAgRQMjU1
딥링킹 매개변수
파라미터 설명
openuri

지원되는 플랫폼:

  • Android
  • iOS
URL-encoded string

openuri 매개변수는 앱이 딥링크, iOS 유니버설 링크 또는 안드로이드 앱 링크를 통해 열렸는지 여부를 지정하며, URL로 인코딩된 오픈 URL 값을 제공해야 합니다.

오픈 URL:
myapp://home/page?queryparam1=value1&queryparam2=value2

 

예시 값입니다:
myapp%3A%2F%2Fhome%2Fpage%3Fqueryparam1%3Dvalue1%26queryparam2%3Dvalue2
파라미터 설명
ddl_enabled

지원되는 플랫폼입니다:

  • Android
  • iOS
string

ddl_enabled 매개변수는 앱이 디퍼드 딥링크를 지원할 수 있도록 설정했는지 여부를 지정합니다. 서버가 디퍼드 딥링크 URL을 반환할 것으로 예상하면'true'를, 그렇지 않으면'false'를 전달합니다.

 

값 예시:
true

 

예제 응답:
{
  "deferred_deeplink": "myapp://deferred-deeplink",
  "status": "ok",
  "deferred_passthrough": "passthroughvalue"
}
파라미터 설명
singular_link_resolve_required

지원되는 플랫폼:

  • Android
  • iOS
string

singular_link_resolve_required 매개변수는 Singular 짧은 링크를 확인하는 데 사용됩니다. Singular 짧은 링크인 'openuri'의 값과 함께 전송해야 합니다. 서버가 확장된 쇼트 링크(롱 링크)를 반환할 것으로 예상하면'true'를, 그렇지 않으면'false'를 전달합니다. 쇼트 링크 처리를 참조하세요.

 

값 예시:
true

 

예제 응답:
{
  "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

지원되는 플랫폼:

  • 안드로이드
    (구글 플레이 기기)
JSON URL-encoded string

install_ref 매개변수는 Google 설치 리퍼러 정보를 표시할지 여부를 지정합니다. 설치 리퍼러에는 사용자를 Google Play 스토어로 보낸 사용자에 대한 정보가 포함되어 있습니다. Singular에서 설치 리퍼러를 사용할 수 있는 경우, 설치 어트리뷰션에 가장 정확한 방법을 제공합니다. 이 값을 검색하여 첫 번째 세션 알림 호출 시 Singular에 전달하세요.

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

사용자 수준 내보내기에서 Facebook 데이터를 수신하고, 데이터 대상과 공유하고, 포스트백을 전송하는 등 몇 가지 중요한 Singular 기능에 필요합니다.

Google Play는 사용자가 스토어에 도착할 때 리퍼러 정보를 수집합니다. 나중에 사용자가 리디렉션된 앱을 설치하면 Google Play는 해당 정보를 앱에서 사용할 수 있도록 합니다. 자세한 내용은 Google 개발자 문서를 참조하세요.

 

예제 값:
%7B%22installBeginTimestampSeconds%22%3A%221568939453%22%2C%22referrer%22%3A%22utm_source%3Dgoogle-play%26amp%3Butm_medium%3Dorganic%22%2C%22clickTimestampSeconds%22%3A%220%22%2C%22referrer_source%22%3A%22service%22%2C%22current_device_time%22%3A%221568944524%22%7D
파라미터 설명
meta_ref

지원되는 플랫폼입니다:

  • Android
    (구글 플레이 기기)
JSON URL-encoded string

meta_ref 파라미터는 광고주가 안드로이드 앱 설치에 대한 세분화된 사용자 수준의 어트리뷰션 데이터에 액세스할 수 있도록 Facebook에서 도입한 안드로이드 전용 측정 솔루션인 "메타 리퍼러"를 지정합니다( Facebook의 데이터 정책 참조). 이 솔루션은 앱 설치 측정을 위해 '구글 플레이 인스톨 리퍼러'('구글 인스톨 리퍼러 통과하기' 참조)와 '메타 인스톨 리퍼러' 기술을 모두 구현하는 것으로 구성되어 있습니다. 메타 리퍼러에 대한 자세한 내용은 해당 주제에 대한 FAQ에서 확인하세요.

{
  "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,
  }
}

 

예시 값:
%7B%22install_referrer%22%3A%7B%22utm_source%22%3A%22apps.facebook.com%22%2C%22utm_campaign%22%3A%22fb4a%22%2C%22utm_content%22%3A%7B%22source%22%3A%7B%22data%22%3A%22c7e6b890bf18a059c2185650bdb1af3dced7...%22%2C%22nonce%22%3A%2224859720343e2381daee9f39ae61%22%7D%2C%22app%22%3A533744218636280%2C%22t%22%3A1731181327%7D%2C%22is_ct%22%3A1%2C%22actual_timestamp%22%3A1731181444%2C%7D%7D
파라미터 설명
attribution_token

지원되는 플랫폼:

  • iOS
string

attribution_token 매개변수는 애드서비스 프레임워크를 통해 iOS 14.3 이상에서 검색된 Apple 검색 광고 어트리뷰션 토큰을 지정합니다.

앱 설치 또는 재설치 후 앱이 처음 초기화되는 즉시 attributionToken()을 사용하여 어트리뷰션 토큰을 검색합니다.

 

예시 값:
KztLg%2FIkNsWDMuBMOU%2BySnkPU5myJb4OFmeaMUE%2BTqQJP1HWL%2FBdpQKNHSnghf0uQpWDsdNcoWHHlXzrRta22Aww4QsUdPGKLwAAAVADAAAAwgAAAIAOMB3LOGJVmcso4G42C3bF8API7suoQgqrM9xfbMKtjpn0anD4Xca2Ma8fMa%2FZLBqWalHYmm58zs4bH1XUDtBcSex1d80D4AhnnPoSYFukr%2ACfLCEnT2lHurPb5cPPQ17ewCd3ctuuZYGHuvV66AkU1ExJUguciTXTNEgY%2Fc19rQAAAB%2BF8udKcAQxkREhEtyGQGRUFydziffiLHBN7bXKSHPFAAAAnwGYh9H%2BPP4rEQGnbnTiQUnkfqgfKQAAAIYCCLjE6nnxqwDQPb4%2FF0Wve%2FVnSwwUxYGsi2a3V5dioUgCzty2kAG8kUsNjk0rU0Z0UrOhvCR%2FGfLXQv7HsMIZlbeKoHast6%2BXfiFsA2x244gztybPDecoGAvsmOeBKxjJqPDGqYxIpBgGaggGg1wonia%2BhxqjcLpEKG%2F%2F%2FEOZb3Jdf%2FaN%2FQABBEkLAAA%3D

요청 본문

이 메서드를 호출할 때 요청 본문을 제공하지 마십시오. 요청은 쿼리 매개변수와 함께 GET 메서드를 사용하여 전송해야 합니다.

 

요청 예제

다음 코드 샘플은 지원되는 모든 매개변수를 나타내지 않을 수 있습니다. 요청을 구현할 때는 위에 나열된 모든 필수 매개변수를 포함하고 프로덕션 인스턴스에서 데이터를 전송하기 전에 올바른 값이 전달되고 있는지 확인해야 합니다. 개발 및 테스트를 위해 고유한 `i` 매개변수(애플리케이션 식별자)를 사용하는 것이 좋습니다.

 

PYTHON CURL HTTP JAVA

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

 

선택적 매개변수

다음 표에는 이 엔드포인트가 지원하는 선택적 매개변수가 나열되어 있습니다. 나열된 모든 매개변수는 쿼리 매개변수입니다.

선택적 매개변수
타임스탬프 매개변수
파라미터 설명
utime
int

utime 매개 변수는 세션의 시간을 10자리 UNIX 시간으로 지정합니다.

 

예제 값입니다:

1483228800
매개변수 설명
umilisec
int

umilisec 매개 변수는 세션의 시간(밀리초)을 13자리 UNIX 시간으로 지정합니다.

 

예제 값:

1483228800000
장치 및 네트워크 매개변수
매개변수 설명
global_properties
JSON URL-encoded string

global_properties 매개변수는 최대 5개의 키-값 쌍을 포함하는 URL 인코딩된 JSON 객체를 허용합니다. 각 키와 값의 길이는 최대 200자까지 가능합니다.

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

JSON 객체는 반드시

  • JSON 문자열로 변환되고 URL로 인코딩됩니다.

 

예제 값입니다:

%7B%22key1%22%3A%22value1%22%2C%22key2%22%3A%22value2%22%7D
매개변수 설명
use_ip
string

use_ip 매개변수는 Singular가 'ip' 매개변수 대신 HTTP 요청에서 IP 주소를 추출하도록 지시합니다. 이 기능을 사용하려면'true'를 전달합니다.

  • 이 매개변수를 사용하면 Singular가 IP 주소를 기반으로 디바이스의 지리적 위치를 파악하지 못합니다. 선택 사항인 'country' 파라미터에 사용자의 두 글자 국가 코드를 입력할 수 있습니다.
  • 이 파라미터는 'ip' 파라미터와 상호 배타적입니다. 'ip' 매개변수와 함께 사용하지 마세요.
  • 데이터 거부를 방지하려면 요청에 'ip' 또는 'use_ip' 매개변수를 제공해야 합니다.

 

예제 값

true
파라미터 설명
country
string

country 매개변수에는 세션 실행 시 사용자의 ISO 3166-1 알파-2 두 글자 국가 코드가 포함되어야 합니다. 이 매개 변수는 다음과 같은 경우에만 필요합니다:

  • 'ip' 파라미터를 사용할 수 없는 경우
  • 'ip' 파라미터를 사용할 수 있는 경우 국가는 IP 주소에서 자동으로 결정되며 'country' 파라미터는 필요하지 않습니다.

 

값 예시:

US
파라미터 설명
ua
URL-encoded string

ua 매개변수는 디바이스의 사용자 에이전트를 지정합니다.

Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148

값은 URL 인코딩된 값이어야 합니다.

 

예시 값:

Mozilla%2F5.0%20(iPhone%3B%20CPU%20iPhone%20OS%2014_0%20like%20Mac%20OS%20X)%20AppleWebKit%2F605.1.15%20(KHTML%2C%20like%20Gecko)%20Mobile%2F15E148
파라미터 설명
c

지원되는 플랫폼:

  • iOS
  • Android
string

c 매개변수는 네트워크 연결 유형'와이파이' 또는'통신사'를 지정합니다.

 

예제 값입니다:

wifi
매개변수 설명
cn

지원되는 플랫폼:

  • iOS
  • Android
string

cn 매개변수는 인터넷 제공업체의 통신사 이름을 지정합니다.

 

예시 값:

Comcast
추적 지원 제거
파라미터 설명
apns_token

지원되는 플랫폼:

  • iOS
string

apns_token 매개변수는 Apple 푸시 알림 서비스(APNS) 디바이스 토큰을 지정합니다.

 

예제 값입니다:

b0adf7c9730763f88e1a048e28c68a9f806ed032fb522debff5bfba010a9b052
매개변수 설명
fcm

지원 플랫폼:

  • Android
string

fcm 매개변수는 파이어베이스 클라우드 메시징 디바이스 토큰을 지정합니다.

  • Android 제거 추적에 필요
  • FCM 토큰을 검색하는 방법
  • 다음 예제와 같이 세션을 Singular에 보고할 때 fcm 매개변수에 디바이스 토큰을 전달합니다:

 

예시 값:

bk3RNwTe3H0CI2k_HHwgIpoDKCIZvvD...MExUdFQ3P1
데이터 프라이버시
파라미터 설명
data_sharing_options
JSON URL-encoded string

data_sharing_options 매개변수는 정보 공유에 대한 최종 사용자의 동의를 지정합니다. 설정된 경우 이 값은 유지되며 사용자에 대한 모든 후속 '세션' 및 '이벤트' 요청에 전달되어야 합니다.

  • 사용자가 정보 공유에 동의(옵트인)했음을 나타내려면 'false'를 전달합니다:
    {"limit_data_sharing":false}
  • 사용자가 거부한 경우 'true'를 전달합니다:
    {"limit_data_sharing":true}

값은 URL로 인코딩된 JSON 문자열이어야 합니다.

 

값 예시:

%7B%22limit_data_sharing%22%3Atrue%7D
매개변수 설명
dnt

지원되는 플랫폼입니다:

  • Android
  • iOS
int

dnt 매개변수는 추적 금지 상태를 지정합니다. 추적 금지가 활성화되면 1을, 추적 금지가 비활성화되면 0을 전달합니다.

 

값 예시:
0
파라미터 설명
dntoff

지원되는 플랫폼:

  • iOS
  • Android
int

dntoff 매개변수는 추적 금지가 꺼져 있는지 여부를 지정합니다. '추적 금지'가 활성화된 경우 0을, '추적 금지'가 비활성화된 경우 1을 전달합니다.

 

값 예시:
1
교차 장치 지원
파라미터 설명
custom_user_id
string

custom_user_id 매개변수는 내부 사용자 ID를 지정합니다.

 

예시 값:

123456789abcd
iOS SkAdNetwork 지원
파라미터 설명
skan_conversion_value

지원 플랫폼:

  • iOS
int

skan_conversion_value 파라미터는 이 세션 알림 시점의 최신 SKAdNetwork 전환 값을 지정합니다(SKAdNetwork 구현에 대해 자세히 알아보기).

 

값 예시:

7
파라미터 설명
skan_first_call_timestamp

지원 플랫폼:

  • iOS
int

skan_first_call_timestamp 파라미터는 기본 SkAdNetwork API에 대한 첫 번째 호출의 유닉스 타임스탬프를 지정합니다(SKAdNetwork 구현에 대해 자세히 알아보기).

 

예시 값:

1483228800
파라미터 설명
skan_last_call_timestamp

지원 플랫폼:

  • iOS
int

skan_last_call_timestamp 매개변수는 이 세션 알림 시점에 기본 SkAdNetwork API에 대한 최신 호출의 유닉스 타임스탬프를 지정합니다(SKAdNetwork 구현에 대해 자세히 알아보기).

 

예시 값:

1483228800

세션 테스트

서버 간 연동을 연동한 후에는 제품 인스턴스를 라이브로 전환하기 전에 Singular가 데이터를 수신하는지 확인해야 합니다. 자세한 내용은 테스트 가이드를 참조하세요. 대략적으로 다음 단계를 따라야 합니다:

  1. 테스트 기기 광고 ID를 획득하고 Singular SDK 콘솔에 ID를 추가합니다.
  2. Singular SDK 콘솔을 열고 디바이스 식별자를 추가하여 데이터 캡처를 시작합니다.
  3. 앱 식별자를 개발 앱 식별자(com.singular.app.dev)로 재정의하여 테스트 데이터와 이벤트를 프로덕션 데이터와 별도로 유지합니다.
  4. 종료된 상태에서 앱 빌드 또는 열기
  5. 모든 필수 Singular 데이터 포인트가 포함된 앱 열기 유효성 검사를 서버로 전송합니다.
  6. 서버 유효성 검사는 모든 필수 데이터 포인트와 함께 Singular'실행' 엔드포인트에 세션 알림을 트리거합니다.
  7. 몇 초 후, 세션 이벤트가 Singular SDK 콘솔에 표시됩니다.
    s2s_session.png
  8. 테스트를 반복하여 앱 열기가 모든 앱 항목 또는 '포그라운드' 작업에서 세션을 트리거하는지 확인합니다.
중요 확인 사항

앱 열기 또는 포그라운드에서 세션 이벤트가 발생하고 이벤트가 수신되기 전에 세션 이벤트가 발생하는지 확인합니다.

SDK 콘솔에 세션이 표시되면 세션 처리에 대한 엔드투엔드 테스트를 완료한 것입니다!