Singular 통합 계획
서드파티 데이터 통합으로 생성된 데이터는 클러스터의 소비 데이터양에 포함됩니다
개요
인터페이스 소개
| 인터페이스명 | 타입 | 세분화 | 어트리뷰션 | 비용 | 수익 | 노출 | 클릭 | 전환 |
|---|---|---|---|---|---|---|---|---|
| Internal BI Postbacks | 콜백 | 유저 수준 | ✅ | ✅ | ✅ |
Singular는 파트너 설정 콜백 기능을 제공하며, 이 기능을 사용하여 어트리뷰션 데이터, 광고 수익, 전환 데이터를 포함한 유저 단위 데이터를 콜백할 수 있습니다
Singular 데이터 연동을 시작하기 전에 AE 시스템의 유저 식별 규칙을 읽고 AE가 #distinct_id와 #account_id로 유저를 식별하는 방식을 이해했는지 확인하십시오
통합 절차
- Singular 클라이언트 SDK와 AE 클라이언트 SDK를 연동하고, Singular SDK에 AE 유저 식별 ID를 설정합니다
- AE 백엔드에 로그인하여 서드파티 통합 모듈로 이동한 후 Singular 콜백 계획을 추가하고 관련 설정을 완료한 다음 콜백 주소를 가져옵니다
- Singular 백엔드에서 Internal BI 콜백을 추가합니다
- AE 시스템이 데이터를 정상적으로 수신했는지 확인하고 리포트를 구축합니다
1. 클라이언트 SDK 설정
Singular의 콜백 데이터를 AE 프로젝트의 유저 데이터와 연결하려면 Singular SDK에서 AE 프로젝트의 계정 ID와 게스트 ID를 전송해야 합니다.
먼저 AE SDK를 초기화하고, Singular SDK를 초기화할 때 AE SDK의 게스트 ID를 Singular의 커스텀 유저 ID로 설정할 것을 강력히 권장합니다. 다음은 Android 코드 예시입니다:
// AE SDK 초기화
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// AE의 게스트 ID 가져오기. AE의 #distinct_id에 대응
String te_distinct_id = TDAnalytics.getDistinctId();
// SingularConfig에 AE의 게스트 ID를 전달하여 커스텀 유저 ID로 사용하고 초기화
SingularConfig config = new SingularConfig("SDK KEY","SDK SECRET")
.withCustomUserId(te_distinct_id);
Singular.init(context, config);
2. 계획 설정
SDK 설정을 완료한 후 AE 시스템 백엔드에 로그인하여 서드파티 통합 모듈에서 Singular 계획 설정을 완료해야 합니다. 아래 그림은 Singular Internal BI Postbacks 계획의 설정 화면입니다:
2.1 유저 식별 필드
Singular Internal BI Postbacks 데이터는 유저 수준 데이터이므로 유저 식별 규칙, 즉 Singular SDK에 설정한 AE 시스템의 유저 식별 ID를 설정해야 합니다. AE 시스템은 이 설정에 따라 콜백 데이터를 변환할 때 해당 필드를 데이터의 유저 식별 필드로 설정합니다.
이 문서의 이전 단계에 따라 클라이언트 SDK를 설정한 경우 다음 설정을 사용하십시오:
- 계정 ID 연관 필드: 없음
- 게스트 ID 연관 필드: user_id
2.2 이벤트 테이블 저장 설정
이벤트 테이블 저장 설정 스위치를 켜면 Singular가 콜백하는 데이터가 모두 이벤트 테이블에 기록됩니다. 이벤트 데이터 저장을 활성화할 것을 권장합니다.
2.3 유저 속성 저장 규칙
기본적으로 AE 시스템은 Singular 데이터를 유저 속성에 기록하지 않습니다. 유저 어트리뷰션 정보 필드 등 일부 필드를 유저 테이블에 기록하려면 먼저 규칙을 켜서 실행되도록 한 다음, 속성 매핑 기능으로 유저 테이블에 기록할 필드를 추가하십시오. 소스 속성명에는 필드의 저장명을 입력해야 합니다:
다음과 같이 유저 속성 저장 규칙을 설정할 것을 권장합니다:
- 모든 이벤트 포함을 끕니다
- 소스 이벤트명에서 singular_install을 선택합니다
- 저장 규칙으로 user_setOnce를 사용합니다
- 속성 필드는 다음과 같이 설정합니다:
| 소스 데이터명 | 대상 속성명 | 설명 |
|---|---|---|
| network | te_ads_object.media_source | 미디어 채널 |
| tracker_campaign_name | te_ads_object.campaign_name | 캠페인 이름 |
| tracker_sub_campaign_name | te_ads_object.ad_group_name | 광고 그룹 이름 |
| tracker_creative_name | te_ads_object.ad_name | 광고 이름 |
2.4 통합 설정
통합 설정 모듈에서 데이터 수집의 세부 설정을 제어할 수 있습니다. 예를 들어 저장 후 이벤트 이름 등이 있습니다
통합 설정의 내용은 JSON이며, 다음 내용에 따라 커스텀 설정할 수 있습니다:
| 모듈 | 이름 | 의미 |
|---|---|---|
| sink_event | event_mapping | 저장 후 이벤트 이름, 커스텀 가능. Key는 Singular 콜백 데이터의 이벤트 이름이고, Value는 해당 이벤트의 저장 후 이벤트 이름입니다. 여기에 기재되지 않은 이벤트는 콜백 데이터의 이벤트 이름 앞에 singular_ 접두사를 붙여 저장 이벤트 이름으로 사용합니다 |
2.5 엔드포인트 주소
엔드포인트 주소에는 AE 시스템이 Singular 콜백 데이터를 수신하는 주소가 표시됩니다. 이 주소를 그대로 복사하여 이후 Singular 콜백을 설정할 때 입력하십시오:
여기에 주소가 표시되지 않으면 오른쪽 상단 메뉴의 프로젝트 관리 → 프로젝트 구성 → 연동 설정에서 공용 네트워크 주소를 설정하십시오. 이 주소는 AE SDK에 설정한 데이터 수집 주소입니다. 설정한 후 Singular 설정 페이지의 엔드포인트 주소로 돌아와 엔드포인트 주소를 복사하십시오.
마지막으로 오른쪽 상단의 저장 버튼을 클릭하여 Singular 계획을 저장하는 것을 잊지 마십시오.
3. 콜백 설정 및 데이터 저장
3.1 콜백 설정
Singular 계획을 생성한 후 Singular 백엔드에 로그인하여 Attribution > Partner Configuration(어트리뷰션 설정 - 채널 설정) 페이지로 이동합니다. 채널 파트너 추가에서 Thinking Data를 검색하여 클릭하면 AE 시스템과의 콜백 설정을 추가할 수 있습니다.
Configuration 페이지로 이동하여 먼저 데이터를 콜백할 App과 Site를 선택합니다
다음으로 AE 시스템에 있는 Singular 통합 계획의 콜백 주소를 Postback URL에 입력합니다
마지막으로, Singular는 기본적으로 설치 이벤트(install)와 리인게이지먼트 이벤트(Re-Engagement)를 콜백합니다. 콜백할 인앱 이벤트가 더 있다면 상단 탭에서 In app Events Postback으로 전환한 후 아래 목록에 콜백할 이벤트를 추가하십시오. 수익 이벤트는 Revenue Events Postbacks 메뉴에서 선택할 수 있습니다:
참고: SDK 이벤트 목록에는 다음과 같은 수익 이벤트 옵션이 있습니다:
-
__IAP__는 커스텀 이름이 없는 모든 인앱 구매 이벤트를 의미합니다
-
이벤트 이름이 그대로 표시되는 수익 이벤트는 이름이 변경된 인앱 구매 이벤트를 의미합니다
-
__ADMON_USER_LEVEL_REVENUE__는 광고 수익 이벤트를 의미합니다(Ad Revenue Attribution을 설정한 경우)
-
__REVENUE__에는 다음이 포함됩니다:
- 모든 인앱 구매 이벤트(__IAP__ 및 커스텀 인앱 구매 이벤트 포함)
- 광고 수익 이벤트(Ad Revenue Attribution을 설정한 경우)
- 또한 모든 수익 데이터를 하나의 이벤트로 통합하여 콜백합니다
콜백을 설정할 때 인앱 구매 이벤트를 AE SDK에서 이미 전송하고 있는지 확인하십시오. AE SDK에서 이미 인앱 구매 이벤트를 전송하고 있다면 데이터 중복을 피하기 위해 Singular에서 __IAP__ 및 기타 인앱 구매 이벤트를 콜백하지 않는 것을 권장합니다
또한 __REVENUE__는 모든 수익 이벤트를 하나의 이벤트로 통합하므로, 프로젝트에서 인앱 구매 이벤트와 광고 수익 이벤트를 모두 기록하고 있다면 __REVENUE__를 설정하지 말고 각 수익 이벤트를 개별적으로 설정할 것을 권장합니다. 이렇게 하면 인앱 구매와 광고 수익화 데이터를 더 잘 구분할 수 있습니다
3.2 이벤트 저장 규칙
-
데이터의 user_id 필드를 유저의 게스트 ID로 사용합니다
-
데이터의 event_utc_timestamp 필드, 즉 이벤트 발생 시간을 데이터의 #event_time으로 사용합니다
-
데이터 이벤트 이름은 데이터의 event_name에 접두사 singular_를 붙여 사용하며, 이름이 없는 수익 이벤트의 이름은 다음과 같습니다:
- __IAP__：singular_iap
- __ADMON_ USER_LEVEL_REVENUE__：singular_ad_revenue
- __REVENUE__：singular_revenue
-
나머지 필드는 모두 저장되며, 다음은 Internal BI Postbacks가 콜백하는 필드입니다:
| 필드 | 의미 |
|---|---|
| app_name | 앱 이름 |
| longname | 앱의 bundle ID |
| platform | 운영체제. 값은 iOS 또는 Android |
| event_name | 이벤트 이름 |
| idfa | iOS의 IDFA |
| idfv | iOS의 IDFV |
| aifa | Android 디바이스의 광고 식별자 ID |
| android_id | Android ID. AIFA를 사용할 수 없는 경우에만 전송됨 |
| singular_id | (지원 중단) iOS 디바이스에서 데이터 추적을 제한한 경우(LAT 활성화 시)에만 전송되며, Singular 내부 ID를 사용 |
| event_utc_timestamp | 이벤트 발생 시의 UNIX 타임스탬프 |
| click_utc_timestamp | 클릭 시의 UNIX 타임스탬프 |
| install_utc_timestamp | 설치 시의 UNIX 타임스탬프 |
| is_organic | 1은 자연 유입 유저, 0은 비자연 유입 유저 |
| is_viewthrough | 1은 노출 어트리뷰션 유저, 0은 그 반대 |
| network | 유저가 어트리뷰션된 미디어 채널 |
| campaign | Singular가 식별한 Campaign 이름 |
| campaign_group | Singular가 식별한 Campaign 그룹 이름(일부 플랫폼만 해당) |
| creative | Singular가 식별한 크리에이티브 이름 또는 크리에이티브 ID |
| site | Source site & Sub Site for click. Available if passed in click |
| user_id | 커스텀 유저 ID. 2.1의 설정에 따라 값은 AE 시스템의 게스트 ID와 같아야 함 |
| singular_click_id | Singular가 생성한 고유 클릭 ID |
| is_reengagement | 1은 리인게이지먼트 광고로 복귀한 유저, 0은 그 반대 |
| click_ip | 광고 클릭 시의 IP 주소 |
| os_version | 광고 클릭 시의 OS 버전 |
| app_version | 설치 또는 이벤트 발생 시의 앱 버전 |
| country | 유저 설치 시의 국가(지역) |
| city | 유저 설치 시의 도시 |
| limit_ad_tracking | 1은 추적 제한 활성화, 0은 그 외의 경우 |
| device_model | 디바이스 모델 |
| device_brand | 디바이스 브랜드 |
| match_type | 어트리뷰션 매칭 모드. 값은 deterministic (디바이스 ID 매칭, 정확한 매칭), probabilistic (Android 전용, 퍼지 매칭) 또는 none (즉 자연 유입). |
| amount | 수익 데이터만 콜백됨. 미국 달러 기준 수익 값 |
| currency | 수익 데이터만 콜백됨. 수익 통화의 ISO 4217 세 자리 알파벳 통화 코드 |
| is_first_event | 1은 해당 이벤트(수익 또는 커스텀 이벤트)가 이 디바이스의 첫 번째 이벤트임을, 0은 첫 번째 이벤트가 아님을 의미 |
| tracker_campaign_name | 채널이 콜백한 Campaign 이름 |
| tracker_campaign_id | 채널이 콜백한 Campaign ID |
| tracker_sub_campaign_name | 채널이 콜백한 Sub-campaign 이름 |
| tracker_sub_campaign_id | 채널이 콜백한 Sub-campaign ID |
| tracker_creative_name | 채널이 콜백한 크리에이티브 이름 |
| tracker_creative_id | 채널이 콜백한 크리에이티브 ID |
| tracker_publisher_id | 채널이 콜백한 해시 처리된 App ID |
| tracker_publisher_sub_id | 채널이 콜백한 Publisher SUB ID |
| tracker_publisher_site_name | 채널이 콜백한 App 이름 |
| tracker_publisher_site_id | 채널이 콜백한 App ID |
| tracker_publisher_sub_site_name | 채널이 콜백한 Sub-publisher 이름 |
| tracker_publisher_sub_site_id | 채널이 콜백한 Sub-publisher ID |
| tracker_name | 추적된 Campaign 이름 |
| network_tiktok_restricted | TikTok의 노출 어트리뷰션 유저 데이터에는 이 제한 필드가 있음. 자세한 내용은 부록 참조 |
| campaign_tiktok_restricted | TikTok의 노출 어트리뷰션 유저 데이터에는 이 제한 필드가 있음. 자세한 내용은 부록 참조 |
| fb_campaign_id | Facebook의 Campaign ID. Facebook 서비스 약관의 제한을 받음. 자세한 내용은 부록 참조 |
| fb_campaign_name | Facebook의 Campaign 이름. Facebook 서비스 약관의 제한을 받음. 자세한 내용은 부록 참조 |
| fb_adset_id | Facebook의 Ad Set(광고 그룹) ID. Facebook 서비스 약관의 제한을 받음. 자세한 내용은 부록 참조 |
| fb_adset_name | Facebook의 Ad Set(광고 그룹) 이름. Facebook 서비스 약관의 제한을 받음. 자세한 내용은 부록 참조 |
| fb_ad_id | Facebook의 광고 ID. Facebook 서비스 약관의 제한을 받음. 자세한 내용은 부록 참조 |
| fb_ad_name | Facebook의 광고 이름. Facebook 서비스 약관의 제한을 받음. 자세한 내용은 부록 참조 |
| twitter_campaign_name | Twitter의 Campaign 이름. Twitter 서비스 약관의 제한을 받음. 자세한 내용은 부록 참조 |
| twitter_campaign_id | Twitter의 Campaign ID. Twitter 서비스 약관의 제한을 받음. 자세한 내용은 부록 참조 |
| twitter_line_id | Twitter의 Line Item(광고 그룹) ID. Twitter 서비스 약관의 제한을 받음. 자세한 내용은 부록 참조 |
| fraud_status | 부정 트래픽 식별 결과. fraud postbacks를 활성화한 경우에만 콜백됨. 값은 "valid"/"suspicious"/"rejected"(유효/의심/거부) |
| fraud_reason | 부정 트래픽 데이터의 식별 규칙 이름. fraud postbacks를 활성화한 경우에만 콜백됨 |
3.3 표준화 필드
Singular 콜백 데이터의 일부 필드는 AE 시스템에서 표준화 처리합니다:
| 필드 | 표준화 필드 | 의미 |
|---|---|---|
| app_name | te_ads_object.app_name | 앱 이름 |
| longname | te_ads_object.app_id | 앱 ID |
| platform | te_ads_object.platform | 플랫폼(Android, iOS 등) |
| country | te_ads_object.country | 국가/지역 코드 |
| amount | te_ads_object.revenue | 수익화 수익 |
| currency | te_ads_object.currency | 수익 통화 |
| network | te_ads_object.media_source | 미디어 채널 |
| tracker_campaign_name | te_ads_object.campaign_name | 캠페인 이름 |
| tracker_campaign_id | te_ads_object.campaign_id | 캠페인 ID |
| tracker_sub_campaign_name | te_ads_object.ad_group_name | 광고 그룹 이름, 수익화 광고의 Unit 이름 |
| tracker_sub_campaign_id | te_ads_object.ad_group_id | 광고 그룹 ID, 수익화 광고의 Unit ID |
| tracker_creative_name | te_ads_object.ad_name | 광고 이름 |
| tracker_creative_id | te_ads_object.ad_id | 광고 ID |
4. 부록
일부 플랫폼은 유저 단위 데이터를 다른 서드파티 플랫폼으로 콜백하는 것을 제한하며, 여기에는 Internal BI Postbacks를 사용하여 AE 시스템으로 콜백하는 경우도 포함됩니다. 아래 표는 이러한 플랫폼의 제한 규칙입니다:
| 플랫폼 이름 | 제한 규칙 |
|---|---|
| Facebook 유저 단위 데이터는 어트리뷰션 후 6개월이 지나면 삭제되므로, 어트리뷰션 6개월 후에는 Facebook 어트리뷰션 유저가 Singular 시스템에서 "Organic"(즉 자연 유입)으로 표시됩니다. 또한 최종 사용자 약관상 Facebook 노출 어트리뷰션의 유저 단위 데이터를 가져오는 것은 허용되지 않으므로, Facebook 노출 어트리뷰션 유저의 어트리뷰션 정보는 모두 "Unattributed"로 표시됩니다 | |
| Google Ads (Adwords) | Google Ads 유저 단위 데이터는 어트리뷰션 후 6개월이 지나면 삭제되므로, 어트리뷰션 6개월 후에는 Google Ads 어트리뷰션 유저가 Singular 시스템에서 "Organic"(즉 자연 유입)으로 표시됩니다 |
| Snapchat | Snapchat의 데이터 공유 정책은 Snapchat 데이터를 서드파티와 공유하는 것을 일절 금지합니다 |
| TikTok | TikTok 유저 단위 데이터는 어트리뷰션 후 6개월이 지나면 삭제되므로, 어트리뷰션 6개월 후에는 TikTok 어트리뷰션 유저가 Singular 시스템에서 "Organic"(즉 자연 유입)으로 표시됩니다. 또한 최종 사용자 약관상 TikTok 노출 어트리뷰션의 유저 단위 데이터를 가져오는 것은 허용되지 않으므로, 2022-05-02 이후 TikTok 노출 어트리뷰션 유저의 어트리뷰션 정보는 모두 "TikTok Restricted"로 표시됩니다 |
Twitter 연동 지점이 Twitter의 디바이스 단위 어트리뷰션 데이터를 수신할 자격이 있는지 확인하십시오 Twitter 유저 단위 데이터는 어트리뷰션 후 6개월이 지나면 삭제되므로, 어트리뷰션 6개월 후에는 Twitter 어트리뷰션 유저가 Singular 시스템에서 "Organic"(즉 자연 유입)으로 표시됩니다. 또한 Twitter 최종 사용자는 서드파티에서 자신의 데이터를 삭제할 권리가 있으며, 이러한 유저의 데이터는 유저 단위 데이터에 나타나지 않지만 집계 데이터에서는 계속 집계됩니다 |