RudderStack은 오픈소스 고객 데이터 플랫폼(CDP)입니다 기업이 고객 데이터를 수집, 연동하고 다양한 대상으로 라우팅할 수 있게 해줍니다. 고객 데이터 파이프라인을 관리하기 위한 중앙 집중식 플랫폼을 제공하여, 조직이 웹사이트, 모바일 앱, 서버, 클라우드 서비스 등 다양한 소스에서 데이터를 쉽게 수집할 수 있도록 합니다.

Singular은 iOS 및 Android 모바일 활동에 대해 Singular Server-to-Server(S2S) REST API를 통해 Rudderstack으로부터 이벤트 데이터를 받을 수 있습니다. 이를 "Cloud-Mode" 대상 이라고 합니다. 아래 지침은 Rudderstack에서 Singular 대상을 추가하는 방법을 설명합니다.

대상 가이드	엔지니어링 팀
사전 요구사항	이 문서는 이미 Rudderstack iOS 또는 Android SDK가 앱에 연동되어 있음을 가정합니다.

이 연동을 사용하려면 Rudderstack의 모바일 SDK를 사용해야 합니다. 이 연동은 비모바일 이벤트 데이터와 호환되지 않습니다. 서버 또는 웹 이벤트는 지원되지 않습니다.

RudderStack은 "Cloud-Mode"를 통해 Singular로 전송할 수 있는 두 가지 유형의 트랙 이벤트를 지원합니다:

세션 이벤트
커스텀 이벤트

지원되는 기능

기본 설치 어트리뷰션
Google Install Referrer 어트리뷰션
SkAdNetwork 버전 3 지원(수동 모드)
Apple Search Ads 어트리뷰션
커스텀 인앱 이벤트 트래킹
매출 트래킹
Custom User ID
삭제(Uninstall) 트래킹
Limited Data Sharing(동의) 지원
API v2를 통한 Singular Device ID(SDID)

지원되지 않는 기능

SkAdNetwork 버전 4 지원
전환 모델을 위한 SkAdNetwork 관리 모드(Managed Mode)
META Install Referrer 어트리뷰션
딥링킹

Singular이 제공하는 "전체 기능(Full Feature Functionality)"에 대한 S2S 지원이 필요한 경우, Rudderstack과는 별도로 Singular S2S REST API를 직접 구현해야 합니다. Server-to-Server(S2S) 연동 가이드 를 여기 에서 확인하세요.

Singular Device ID(SDID) 및 API 버전

RudderStack이 사용하는 Singular API 버전은 이벤트에 존재하는 식별자 필드에 따라 달라집니다:

이벤트에 Singular Device ID(SDID) 가 존재하면, RudderStack은 자동으로 Singular API v2 를 사용하고 기존의 플랫폼별 식별자( idfa , andi , idfv , aifa )를 무시합니다.
그렇지 않으면 RudderStack은 플랫폼별 식별자로 폴백하여 Singular API v1 을 사용하여 이벤트를 전송합니다.

Singular Device ID(및 선택적으로 데이터 공유 동의)를 전송하려면, 이벤트의 integrations.Singular 객체 내에 singularDeviceId 와 limitDataSharing 를 포함하세요:

rudderanalytics.track(
  "Order Completed", {
    revenue: 30,
    currency: "USD"
  }, {
    integrations: {
      Singular: {
        singularDeviceId: "SINGULAR_DEVICE_ID",
        limitDataSharing: true  // optional
      }
    }
  }
);

시작하기

RudderStack 대시보드 에서 소스를 추가하세요. 그런 다음 대상 목록에서 Singular 을 선택하세요.
대상에 이름을 지정하고 Continue 를 클릭하세요.

연결 설정

Singular을 대상으로 성공적으로 구성하려면 다음 설정을 구성해야 합니다:

API Key: 여기에 Singular "SDK Key" 를 입력하세요. 이는 필수 항목입니다.
Singular "SDK KEY" 는 Singular 대시보드의 "Developer Tools > SDK Integration > SDK Keys" 에서 확인할 수 있습니다.

참고: "Cloud-Mode" 연동의 경우 API Key(SDK Key) 값만 입력합니다 .
"Secret"은 비워 두세요.
Session Event Name: 세션 이벤트로 사용할 이벤트 이름을 입력하세요. 이 설정은 클라우드 모드를 통해 이벤트를 전송하는 경우에만 적용됩니다.
RudderStack은 Singular launch API를 통해 세션 이벤트를 Singular로 전송합니다.
RudderStack은 대시보드 설정에 지정되어 있거나 다음 세 가지 라이프사이클 이벤트 중 하나인 경우에만 이벤트를 세션 이벤트로 간주합니다:
- Application Installed
- Application Opened
- Application Updated
라이프사이클 이벤트 트래킹이 활성화되어 있으면 RudderStack이 위 세 가지 라이프사이클 이벤트를 자동으로 트래킹합니다.
Use device mode to send events: 이 토글은 "Cloud Mode"를 사용할 때 비활성화되어야 합니다 . Android 또는 iOS 플랫폼을 사용하는 경우, 이 설정을 활성화하여 디바이스 모드를 통해 이벤트를 전송할 수 있습니다. 그런 다음 프로젝트에 Singular을 추가하는 단계는 Singular Device Mode 가이드를 따르세요.
클라이언트 측 이벤트 필터링: Singular로 전달되는 이벤트 중 차단하거나 허용할 이벤트를 지정합니다. 자세한 내용은 Client-side Events Filtering 가이드를 참조하세요.
동의 관리 설정: 드롭다운에서 동의 관리 제공자를 선택하고 관련 동의 카테고리 ID를 입력하여 소스의 동의 관리 설정을 구성합니다. 자세한 내용은 Consent Management in RudderStack 을 참조하세요.

Unity SDK 설정

다음 설정은 Unity를 소스로 사용할 때 적용됩니다:

설정	설명
Match ID mapping	이 설정을 사용하여 Singular의 match ID를 다음 이벤트 필드 중 하나에 매핑합니다: `context.device.advertisingId` 또는 `properties.match_id`.

세션 이벤트 요구사항

지원되는 SESSION 이벤트 매핑

Rudderstack 모바일 SDK가 자동으로 캡처하는 속성

이 섹션에는 RudderStack 이벤트 속성과 관련 Singular 필드의 매핑이 나와 있습니다.

다음 표에는 RudderStack이 모바일 플랫폼( Android 및 iOS )에 대해 자동으로 캡처하는 속성의 매핑이 나와 있습니다:

RudderStack 속성	Singular 속성	존재 여부	설명
context.os.name	p	필수	소스 플랫폼(Android 또는 iOS).
context.app.namespace	i	필수	앱의 패키지 이름(Android) 또는 번들 ID(iOS).
context.app.version	app_v	필수	앱 버전.
context.ip / request_ip (해당 순서로)	ip	필수	사용자의 IP 주소. IP 익명화에 대한 정보는 아래 참고를 확인하세요.
context.os.version	ve	필수	세션 시점의 디바이스 OS 버전.
context.device.model	mo	필수	디바이스 모델. 이 파라미터는 ma 파라미터와 함께 사용해야 합니다.
context.device.manufacturer	ma	필수	디바이스 하드웨어의 제조사. 이 파라미터는 mo 파라미터와 함께 사용해야 합니다.
context.locale	lc	필수	밑줄로 구분된 두 글자 언어 및 국가 코드를 사용하는 디바이스의 IETF 로컬 태그.
context.device.id	idfv	필수	대시가 포함된 대문자 형식의 원본 IdentifierForVendor . 이는 iOS 앱에만 적용됩니다 .
context.device.id	andi	필수	소문자 형식의 원본 Android ID . 이는 Android 앱에만 적용되며 광고 ID(aifa)와 App Set ID(asid)가 없는 경우 필수입니다. 자세한 내용은 아래 FAQ를 참조하세요.
context.app.build	bd	필수	디바이스 빌드(URL 인코딩됨).
context.device.adTrackingEnabled	dnt	필수	do not track(dnt)가 비활성화된 경우 true를 전달하고(dnt=0), 그렇지 않으면 false를 전달합니다(dnt=1). 광고 ID를 SDK에 전달하면 자동으로 캡처됩니다.
context.app.name	n	선택	UI에 표시되는 사람이 읽을 수 있는 앱 이름.
timestamp / originalTimestamp	utime	선택	세션 시간(UNIX 시간).
context.network.wifi	c	선택	연결 유형(WiFi 또는 통신사).
context.network.carrier	cn	선택	인터넷 제공업체의 통신사 이름.
integrations.Singular.limitDataSharing	data_sharing_options.limit_data_sharing	선택	데이터 공유에 대한 JSON URL 인코딩된 사용자 동의. 이후의 모든 이벤트 요청에서 유지되고 전달되어야 합니다.

IP를 익명화하려면 context.ip 필드에 플레이스홀더 IP를 전송할 수 있습니다. RudderStack은 백엔드에서 자동으로 캡처하는 대신 이를 IP 주소로 사용합니다. 모바일 SDK의 경우, Transformations 기능을 활용하여 이를 수행할 수 있습니다 - 클라우드 모드 를 통해 이벤트를 전송할 때.

이벤트 속성을 통해 전달해야 하는 속성

다음 표에는 이벤트 속성을 통해 전달해야 하는 속성의 매핑이 나와 있습니다:

이 속성들은 SDK에 유지되지 않으며 모든 이벤트와 함께 전달해야 합니다.

RudderStack 속성	Singular 속성	존재 여부	설명
properties.install_ref	install_ref	필수	Google Install Referrer 정보.
properties.referring_application	install_source	필수	Android의 설치 소스 패키지 이름. getInitiatingPackageName() 를 사용하여 이를 검색하세요.
properties.install_receipt	install_receipt	필수	설치로부터 받은 영수증. 이를 검색하려면 iOS Install Receipt 가이드를 따르세요.
properties.asid	asid	필수	Android v12+ 디바이스용 App Set ID. 광고 ID(aifa)와 Android ID(andi)가 없는 경우 필수입니다. 자세한 내용은 아래 FAQ를 참조하세요.
properties.url	openui	필수	앱이 딥링크/유니버설 링크를 통해 열린 경우, 인코딩된 딥링크 URL의 값.
context.device.attTrackingStatus	att_authorization_status	필수	App Tracking Transparency 권한 상태 .
userId	custom_user_id	선택	identify 호출을 통해 전달된 사용자 ID.
properties.attribution_token	attribution_token	선택	iOS 14.3 이상에서 Apple Search Ads를 어트리뷰션하는 데 사용됩니다. 자세한 내용은 여기 를 참조하세요.
properties.skan_conversion_value	skan_conversion_value	선택	세션 알림 시점의 최신 SkAdNetwork 값.
properties.skan_first_call_timestamp	skan_first_call_timestamp	선택	SkAdNetwork API에 대한 첫 번째 호출의 UNIX 타임스탬프.
properties.skan_last_call_timestamp	skan_last_call_timestamp	선택	세션 알림 시점의 SkAdNetwork API에 대한 마지막 호출의 UNIX 타임스탬프.
properties.install	install	선택	설치 플래그. 앱 설치 후 첫 번째 세션에서 true로 설정하고, 그렇지 않으면 false로 설정합니다. 재설치 트래킹 기능에 필요합니다.
properties.install_time / timestamp / originalTimestamp	install_time	선택	설치 시간(UNIX 시간).
properties.update_time / timestamp / originalTimestamp	update_time	선택	업데이트 시간(UNIX 시간).

이벤트 속성을 통해 한 번만 전달하면 되는 속성:

다음 표에는 이벤트 속성을 통해 한 번만 전달하면 되는 속성의 매핑이 나와 있습니다:

이 속성들은 SDK에 유지되며 한 번만 전달하면 됩니다.

RudderStack 속성	Singular 속성	존재 여부	설명
context.device.token	fcm	선택	Firebase Cloud Messaging 디바이스 토큰. Android에서 삭제 트래킹에 필요합니다.
context.device.token	apns_token	선택	Apple Push Notification Service 디바이스 토큰. iOS에서 삭제 트래킹에 필요합니다.
context.device.advertisingId	idfa	필수	대시가 포함된 대문자 형식의 원본 광고 ID . 이는 iOS 앱에만 적용됩니다 .
context.device.advertisingId	aifa	필수	대시가 포함된 소문자 형식의 원본 광고 ID 입니다. 이는 Android 앱에만 적용됩니다 . App Set ID(asid)와 Android ID(andi)가 없는 경우 필수입니다. 자세한 내용은 아래 FAQ를 참조하세요.

디바이스 토큰 설정에 대한 자세한 내용은 관련 SDK 문서를 참조하세요:

Android
iOS

RudderStack은 디바이스 토큰 매핑에 대해 fcm 만 지원합니다.

커스텀 이벤트 요구사항

RudderStack은 세션 이벤트를 제외한 모든 이벤트를 Singular의 evt 엔드포인트를 통해 커스텀 이벤트로 전송합니다.

지원되는 EVENT 매핑

Rudderstack 모바일 SDK가 자동으로 캡처하는 속성

이 섹션에는 RudderStack 이벤트 속성과 관련 Singular 필드의 매핑이 나와 있습니다.

다음 표에는 RudderStack이 모바일 플랫폼( Android 및 iOS )에 대해 자동으로 캡처하는 속성의 매핑이 나와 있습니다:

RudderStack 속성	Singular 속성	존재 여부	설명
context.os.name	p	필수	소스 플랫폼(Android 또는 iOS).
context.app.namespace	i	필수	앱의 패키지 이름(Android) 또는 번들 ID(iOS).
context.ip / request_ip (동일한 순서로)	ip	필수	사용자의 IP 주소.
context.device.advertisingId	idfa	필수	대시가 포함된 대문자 형식의 원본 IdentifierForVendor . 이는 iOS 앱에만 적용됩니다 .
context.device.advertisingId	aifa	필수	대시가 포함된 소문자 형식의 원본 광고 ID 입니다. 이는 Android 앱에만 적용됩니다 . App Set ID(asid)와 Android ID(andi)가 없는 경우 필수입니다. 자세한 내용은 아래 FAQ를 참조하세요.
context.device.id	idfv	필수	대시가 포함된 대문자 형식의 원본 IdentifierForVendor . 이는 iOS 앱에만 적용됩니다 .
context.device.id	andi	필수	소문자 형식의 원본 Android ID . 이는 Android 앱에만 적용되며 광고 ID(aifa)와 App Set ID(asid)가 없는 경우 필수입니다. 자세한 내용은 아래 FAQ를 참조하세요.
context.os.version	ve	필수	세션 시점의 디바이스 OS 버전.
timestamp / originalTimestamp	utime	선택	세션 시간(UNIX 시간).
integrations.Singular.limitDataSharing	data_sharing_options.limit_data_sharing	선택	데이터 공유에 대한 JSON URL 인코딩된 사용자 동의. 이후의 모든 이벤트 요청에서 유지되고 전달되어야 합니다.

Singular은 (Android에서) asid 보다 aifa 를, andi 보다 asid 를 우선하며, (iOS에서) idfv 보다 idfa 를 우선합니다.

이벤트 속성을 통해 전달해야 하는 속성

다음 표에는 이벤트 속성을 통해 전달해야 하는 속성의 매핑이 나와 있습니다:

이 속성들은 SDK에 유지되지 않으며 모든 이벤트와 함께 전달해야 합니다.

RudderStack 속성	Singular 속성	존재 여부	설명
event	n	필수	이벤트의 이름. 이는 사용자가 정의합니다 .
context.device.attTrackingStatus	att_authorization_status	필수	App Tracking Transparency 권한 상태 .
userId	custom_user_id	선택	identify 호출을 통해 전달된 사용자 ID.
properties.skan_conversion_value	skan_conversion_value	선택	세션 알림 시점의 최신 SkAdNetwork 값.
properties.skan_first_call_timestamp	skan_first_call_timestamp	선택	SkAdNetwork API에 대한 첫 번째 호출의 UNIX 타임스탬프.
properties.skan_last_call_timestamp	skan_last_call_timestamp	선택	세션 알림 시점의 SkAdNetwork API에 대한 마지막 호출의 UNIX 타임스탬프.
properties.eventAttributes	e	선택	JSON 형식의 커스텀 이벤트 속성. SDK에 유지되지 않으므로 모든 이벤트와 함께 전달해야 합니다.
properties.is_revenue_event	is_revenue_event	선택	이벤트가 매출 이벤트인지 여부를 결정합니다. SDK에 유지되지 않으므로 모든 이벤트와 함께 properties를 통해 전달해야 합니다.
properties.receipt_signature	receipt_signature	선택	영수증 서명.

매출 이벤트에 특정한 사용자 정의 속성

다음 표에는 매출 이벤트에 특정한 사용자 정의 속성 의 매핑이 나와 있습니다:

RudderStack 속성	Singular 속성	존재 여부	설명
properties.total/ properties.value / properties.revenue	amt	선택	통화 금액.
properties.currency	cur	선택	ISO 4217 세 글자 통화 코드. amt 파라미터와 함께 사용해야 합니다.
properties.purchase_receipt	purchase_receipt	선택	구매로부터 받은 영수증.
properties.product_id/properties.sku	purchase_product_id	선택	제품 SKU 식별자.
properties.orderId / properties.purchase_transaction_id (해당 순서로)	purchase_transaction_id	선택	거래 식별자.

value, revenue, total 속성 중 하나라도 설정하면, is_revenue_event 속성으로 명시적으로 지정하지 않는 한 RudderStack이 자동으로 해당 이벤트를 매출 이벤트로 간주합니다.

커스텀 이벤트의 경우 몇 가지 중요한 고려사항이 아래에 나와 있습니다:

RudderStack은 Android의 경우 context.userAgent 에서, iOS의 경우 이벤트 속성에서 user agent를 가져옵니다.
RudderStack은 커스텀 이벤트에 전달된 추가 속성을 Singular의 e 필드에 저장합니다.

테스트

이벤트가 Singular로 성공적으로 전달되었는지 어떻게 확인할 수 있나요?

이벤트가 Singular로 성공적으로 전달되었는지 확인하려면, RudderStack의 Destination live events 기능을 사용할 수 있습니다.

또한 Singular 대시보드 로 이동하여 다음 단계를 따라 이벤트 전달을 확인할 수도 있습니다:

Testing Console 사용 방법에 대한 자세한 가이드는 여기를 따르세요

"Developer Tools > Testing Console" 로 이동하세요.
Add Device 를 클릭하고 관련 디바이스 식별자를 입력하세요:
Singular로 전송된 모든 이벤트의 실시간 로그를 확인할 수 있습니다:

FAQ

Android에는 어떤 디바이스 ID 속성이 필요한가요?

Android 요청의 경우, Singular은 다음 우선순위 순서로 다음 속성 중 하나가 필요합니다:

```
aifa
```
```
asid
```
```
andi
```

이들 중 어느 것도 사용할 수 없는 경우, null이나 undefined 대신 빈 값으로 하나 이상을 전송해야 합니다. 이들을 모두 전송하면 RudderStack은 Google의 데이터 정책에 따라 andi 속성을 삭제합니다.

Rudderstack - Singular Destination (클라우드 모드)