SDK 연동 가이드

0. 개요 (Overview)

본 가이드는 TUNE 서비스의 원태그 SDK를 모바일 앱(Android/iOS)에 성공적으로 설치하고, 데이터매니저 내 어트리뷰션(Attribution) 및 MMP 기능을 활성화하기 위한
통합 연동 가이드라인입니다.

🎯 연동 목적

정밀한 성과 측정: 모바일 광고 캠페인을 통해 유입된 사용자의 앱 설치, 앱 실행 및 핵심 행동 데이터를 실시간으로 수집하여 유입 경로를 명확히 분석합니다.
마케팅 자동화 및 최적화: 수집된 사용자 행동 데이터를 CDP(고객 데이터 플랫폼) 및 외부 DSP(광고 플랫폼)와 연동하여 실시간 리타겟팅 및 개인화 추천 마케팅의 성과를 극대화합니다.

👥 가이드 대상

앱 개발자: AOS 및 iOS 환경 내 SDK 연동 및 사용자 이벤트 스크립트 구현 담당자
마케팅 PO / 실무자: TUNE 어드민 내 외부 APP 트래커 및 딥링크 정책 설정 담당자

💡

원태그(OneTag) & MMP 소개

원태그(OneTag)는 TUNE 플랫폼의 핵심 트래킹 스크립트이자 SDK로, 앱 내 사용자 행동 이벤트를 실시간으로 수집하여 포스트백을 통해 CDP로 전송합니다.

MMP(Mobile Measurement Partner) 기능은 광고 채널(DSP)별 기여도(어트리뷰션)를 측정하고, 앱 설치, 딥링크 오픈, 앱 내 행동(구매, 가입 등)을 정밀 분석하여
광고 성과(ROI)를 극대화합니다.

SDK 연동 가이드

1. 어트리뷰션 정책 (Attribution Policy)

광고 클릭 및 노출 후 사용자가 앱을 설치하거나 전환을 일으켰을 때, 성과가 어떤 캠페인에 귀속되는지 정의하는 표준 정책입니다.

1. 어트리뷰션 정책 기본 구조

⏱️ 어트리뷰션 윈도우 (Attribution Window)

클릭(Click) 기반 어트리뷰션: 기본 7일 (필요 시 최대 30일까지 확장 가능)
노출(View) 기반 어트리뷰션: 기본 24시간 귀속
커스터마이징 가능: 광고주 또는 캠페인 특성에 따라 자유로운 윈도우 범위 조정 가능

🎯 라스트 클릭 (Last Click) 우선 모델

동일한 전환 이벤트에 다중 캠페인이 연결되는 경우, 마지막 클릭 발생 캠페인에 최종 기여 귀속
클릭 이력이 존재하지 않는 유입의 경우에만 노출(View) 기반 성과 귀속 처리

2. 주요 어트리뷰션 정책 요소

어트리뷰션 우선 순위

클릭 이벤트가 노출 이벤트보다 항상 높은 우선순위로 처리됩니다. 클릭과 노출이 동시에 혹은 중복하여 감지되는 경우 클릭 이벤트에 귀속합니다.

어트리뷰션 수집 데이터

[필수 수집 데이터]

광고 소스 (Source): Google Ads, Facebook 등 유입 채널
캠페인 ID (Campaign ID): 캠페인 고유 식별자
광고 그룹 (Ad Group): 세부 광고주 마케팅 그룹
광고 소재 (Creative): 노출된 광고 그래픽/콘텐츠

[추가 수집 데이터]

설치 출처 (Install Referrer): OS 스토어 유입 상세 경로
사용자 세그먼트: 유저 연령대, 성별, 성향 등 세분화 지표

어트리뷰션 조건 정책

앱을 최초로 설치한 이후 발생하는 첫 번째 전환 이벤트는 최초에 기여(어트리뷰션)된 캠페인에 귀속됩니다. 이후 추가로 발생하는 전환 이벤트는 사용자가 새롭게 광고 캠페인에 유입되는 것을 기준으로 재귀속(Re-attribution) 처리됩니다.

3. 어트리뷰션 모델 정책 세부 사항

🔗 딥링크 처리: 딥링크를 통해 설치된 유입의 경우 딥링크 URL 파라미터를 파싱하여 귀속을 측정합니다.

💡

예시: https://example.com/install?campaignId=98765&source=facebook

위 파라미터에서 campaignId=98765와 source=facebook 데이터를 자동 저장하고, 앱 설치 후 최초 실행 시 해당 캠페인으로 어트리뷰션을 귀속합니다.
🛡️ 중복 어트리뷰션 방지: 동일한 사용자로부터 감지된 동일 전환 이벤트는 반드시 하나의 캠페인에만 단일 기여 처리됩니다. 중복 수집을 방지하기 위하여 고유 이벤트 ID 또는 트랜잭션 식별 키를 검증합니다.
⚠️ 오류 및 누락 예외 처리: 기여 데이터 파라미터가 유효하지 않거나 전송 누락이 발생한 트래픽은 기본값인 "Organic" (자연 유입) 캠페인으로 귀속시킵니다. 필수 키가 유실된 잘못된 파라미터 접속의 경우 안전하게 기본 연동 화면으로 리디렉션 처리됩니다.
🎯 리타겟팅 캠페인 독립화: 리타겟팅 목적의 마케팅 캠페인은 기존의 일반 캠페인 데이터와 분리하여 독립적으로 집계합니다. 리타겟팅 터치 클릭 발생 시 기존 캠페인 기여 데이터는 무효화되며 신규 리타겟팅 채널에 새롭게 어트리뷰션됩니다.
🌐 네트워크 간 중복 제어: 한 사용자가 어트리뷰션 윈도우 기간 내에 여러 타 광고 네트워크 지면의 링크를 순차적으로 클릭한 경우, 가장 마지막 클릭(Last Click) 이벤트를 전송한 네트워크에 최종 광고 기여를 할당합니다.

4. 전환 데이터 처리 흐름

클릭 / 노출 및 전송

광고 터치 시 기여 데이터를 TUNE 서버로 실시간 전송합니다.

로컬 데이터 저장

수집된 기여 파라미터를 SDK 내부 로컬 저장소에 캐시합니다.

앱 설치 경로 수집

설치 직후 OS 스토어 유입 경로(Referrer 등)를 파싱합니다.

실행 시 기여 귀속

로컬 캐시와 서버 정보 데이터를 비교 분석하여 캠페인에 귀속합니다.

행동 추적 및 재귀속

추가 유입/인앱 전환 감지 시 최신 캠페인 성과로 재귀속합니다.

5. 기술 구현 시 주의 사항

🔒 어트리뷰션 데이터 보안 암호화

사용자 개인 식별 정보 및 기여 모델에 관한 모든 트래킹 데이터는 암호화(Hashing/AES)를 의무적으로 적용하여 로컬 캐시 및 네트워크 전송을 수행해야 합니다.

💾 로컬 유실 방지 이중화 (Backup)

기기의 비정상 종료나 캐시 강제 삭제로 인한 유입 유실을 극복하기 위해 SDK는 기기 암호 스토리지와 서버 실시간 데이터베이스 백업을 동시 병행해야 합니다.

🚦 다중 캠페인 우선순위 큐 관리

사용자가 짧은 시간 내에 복수 마케팅 채널에 노출되는 경우를 대비해 SDK는 각 클릭 및 노출 로그의 큐 관리 및 우선순위 귀속 판별 프로세스를 정상적으로 수행해야 합니다.

⏱️ 서버 - 단말 간 정확한 시간 동기화

시간 왜곡 및 조작 행위로 인한 어트리뷰션 오류를 방지하기 위해, 만료 시점(Window) 판별 시 기기 로컬 타임 대신 서버 표준시(NTP)와 폰의 부팅 유효 경과 시간(Uptime)을 연계 활용합니다.

6. 어트리뷰션 정책 요약

구분	기본 설정	설명
클릭 윈도우	7일	클릭 후 7일 이내에 전환이 발생하면 해당 캠페인에 성과가 귀속됩니다. (최대 30일 확장 가능)
노출 윈도우	24시간	노출 후 24시간 이내에 클릭 없이 전환이 발생하면 해당 캠페인에 귀속됩니다.
우선 순위	클릭 > 노출	동시 유입되거나 어트리뷰션 판정 시 클릭 기여가 노출 기여보다 항상 우선 처리됩니다.
딥링크	캠페인 데이터 귀속	딥링크 파라미터(`campaignId`, `source` 등)를 로컬에 기록하고 앱 실행 시 기여를 어트리뷰션합니다.
중복 처리	라스트 클릭 우선	하나의 전환 행동에 여러 광고가 연관된 경우 마지막에 클릭된 캠페인을 기준으로 최종 판정합니다.
오류 처리	Organic 캠페인에 귀속	유효하지 않거나 필수 파라미터가 유실된 기여 데이터는 Organic(자연 유입)으로 귀속 처리합니다.

SDK 연동 가이드

2. 원태그(OneTag) 설치 가이드

웹 사이트 및 하이브리드 웹뷰 환경에 원태그 스크립트를 삽입하여 사용자 트래킹 및 성과를 수집할 수 있습니다.

TUNE 대시보드 Appkey 발급

TUNE 대시보드 내 [원태그] 메뉴에 접속하여 Android (AOS), iOS, Web 플랫폼별 Appkey를 먼저 발급받아야 합니다. 발급이 완료되면 각 플랫폼 연동 시 사용할 Appkey가 생성됩니다.

생성된 앱키 자사 SDK에 삽입

발급 완료된 고유 Appkey를 각 플랫폼용 자사 SDK 초기화 코드에 적용하여 연동을 완료합니다. 상세한 SDK 설정 및 초기화 방법은 3. SDK 설치 가이드를 참고해 주세요.

💡

도메인 등록 안내

추적 스크립트를 설치하더라도 TUNE 어드민 페이지에 해당 도메인이 정상 등록되어 있지 않은 경우, 수집 데이터 검증 단계에서 누락이 발생할 수 있습니다.

SDK 연동 가이드

3. SDK 설치 가이드

모바일 네이티브 애플리케이션에 Onetag SDK를 설치하여 인앱 행동 분석 및 MMP 어트리뷰션을 연동합니다.

원태그 모바일 SDK는 Android(AOS)와 iOS 플랫폼을 모두 지원합니다. 연동하고자 하는 모바일 OS 플랫폼의 상세 개발 가이드를 선택해 주세요.

Android (AOS)

Android SDK 설치

AndroidManifest.xml 설정, Application 클래스에서의 초기화, 하이브리드 앱 웹뷰 바인딩 등의 연동 단계를 제공합니다.

iOS

iOS SDK 설치

CocoaPods/SPM 라이브러리 추가, Info.plist 권한 설정, AppDelegate SDK 초기화 등의 연동 단계를 제공합니다.

SDK 연동 가이드

3-1. Android (AOS) SDK 설치 가이드

💡

AOS SDK 설치와 관련된 상세 가이드를 확인하려면 링크를 클릭해주세요.

AndroidManifest.xml 설정

Android 환경에서 네트워크 통신과 구글 광고 ID(AD_ID)를 수집하기 위한 필수 권한을 선언합니다.

<manifest xmlns:android="http://schemas.android.com/apk/res/android" ...>

                <uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

                <application
                ...
                android:usesCleartextTraffic="true" >
                ...
                </application>
                </manifest>

SDK 초기화 (Application 영역)

앱이 시작될 때 Mobtune SDK를 연동하기 위해 Application 클래스의 onCreate() 단계에서 초기화와 생명주기 콜백을 등록합니다.

public class MyApplication extends Application{
                @Override
                public void onCreate(){
                super.onCreate();

                // 발급받으신 고유 APP_KEY를 입력해 주세요.
                MobtuneSDK.init(this, "YOUR_APP_KEY");

                if (Build.VERSION.SDK_INT >= 14) {
                registerActivityLifecycleCallbacks(new MobtuneLifecycleCallbacks(this));
                }
                }
                }

하이브리드 앱(Hybrid App) 웹뷰 연동

웹뷰 기반의 하이브리드 앱인 경우, 정확한 크로스 도메인 트래킹 및 사용자 식별을 위해 WebView 객체를 SDK에 바인딩해야 합니다.

@Override
                protected void onCreate(Bundle savedInstanceState){
                super.onCreate(savedInstanceState);
                setContentView(R.layout.activity_main);

                webview = findViewById(R.id.webview);

                // WebView 객체를 Mobtune SDK에 바인딩
                MobtuneSDK.setWebView(webview);
                }

SDK 연동 가이드

3-2. iOS SDK 설치 가이드

💡

iOS SDK 설치와 관련된 상세 가이드를 확인하려면 링크를 클릭해주세요.

SDK 가져오기 & Info.plist 설정

CocoaPods 또는 Swift Package Manager(SPM)를 통해 MobtuneSDK_IOS 라이브러리를 프로젝트에 추가합니다.
App Tracking Transparency(ATT) 대응을 위해 Info.plist에 사용자 권한 요청 목적(NSUserTrackingUsageDescription)에 대한 설명을 반드시 기입해 주세요.

SDK 초기화

Swift 기반 AppDelegate 파일의 didFinishLaunchingWithOptions 메서드 내에서 발급받은 App Key를 기반으로 SDK를 초기화합니다.

import MobtuneSDK_IOS // SDK 모듈 임포트

                @main
                class AppDelegate: UIResponder, UIApplicationDelegate{
                func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions:
                [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

                // iOS SDK 초기화 및 발급받은 고유 APP_KEY 설정
                MobtuneSDK.shared.initialize(appKey: "YOUR_APP_KEY")

                return true
                }
                }

SDK 연동 가이드

4. [중요] TUNE 관리자 화면 연동 설정

SDK 설치 완료 후, TUNE 플랫폼에서 앱 트래킹 데이터를 수집하고 포스트백 연동을 활성화하기 위해 관리자 화면 세팅을 필수로 진행해야 합니다.

🛠️

연동 경로
TUNE 관리자 ➔ CDP/DMP ➔ 데이터 연동 관리 ➔ [외부 APP 트래커] 탭

[TUNE 어드민]
            └── 📂 CDP/DMP
            └── 📂 데이터 연동 관리
            └── 📑 외부 APP 트래커 (탭 선택)

1) 신규 앱 트래커 연동 설정

[외부 APP 트래커] 탭에서 [트래커 연동 추가] 버튼을 클릭합니다.
사용 중인 플랫폼의 앱 패키지명(AOS Package Name / iOS App Bundle ID)을 정확히 입력합니다.
SDK 연동 정보 검증을 위해 발급받은 App Key 및 Secret Key가 정상 등록되어 있는지 교차 검증합니다.

2) 외부 MMP 포스트백(Postback) 및 파트너 설정

타사 MMP(예: AppsFlyer, Adjust, Singular 등)를 혼용하거나 독립적인 광고 네트워크(DSP)로 성과를 돌려주기 위한 포스트백 정보를 매핑합니다.

연동 트래커 선택: 하단의 연동 파트너 리스트 중 매핑하고자 하는 트래커를 선택 및 활성화(ON)합니다.
포스트백 URL 등록: 각 이벤트별(설치, 가입, 구매 등) 수신받을 포스트백 파라미터 규격을 검토 및 매핑합니다.
룩백 윈도우(Lookback Window) 조정: 비즈니스 정책 및 계약 조건에 맞게 클릭/노출 어트리뷰션 유효 기간을 수정 설정합니다 (기본 클릭 7일 / 노출 24시간).

SDK 연동 가이드

5. 앱 내 주요 사용자 이벤트 수집 (공통)

정밀한 캠페인 ROI 분석 및 행동 기반 마케팅을 위해 앱 내에서 발생하는 핵심 이벤트를 수집 및 전송해야 합니다.

Android 수집 예시 (Purchase)

아래는 대표적인 결제(Purchase) 완료 이벤트 구현 예시입니다.

// 1. 구매한 상품 개별 정보 생성
            ProductItem productItem1 = new ProductItem()
            .setProductId("test_product_1") // 상품 고유 ID
            .setProductName("원태그 가방") // 상품명
            .setPrice("100000") // 상품 가격
            .setQuantity("1"); // 구매 개수

            ProductItem productItem2 = new ProductItem()
            .setProductId("test_product_2")
            .setProductName("TUNE 모자")
            .setPrice("30000")
            .setQuantity("2");

            // 2. 전체 주문 정보 생성 및 이벤트 전송
            ProductInfo product = new ProductInfo()
            .setPaymentMethod(MobtuneParameter.PAYMENT_CARD) // 결제 수단 (예: 카드)
            .setOrderId("ORD_20260716_0001") // 주문 번호
            .addProduct(productItem1)
            .addProduct(productItem2);

            MobtuneSDK.sendEvent(MobtuneEvent.PURCHASE, product);

📌 주요 추적 이벤트 항목

페이지뷰 / 화면 조회 (PageView)
상품 상세페이지 조회 (Product Detail View)
장바구니 담기 (Add to Cart)
구매 완료 (Purchase)

SDK 연동 가이드

6. 딥링크 & 리타겟팅 정책 (DeepLink & Re-targeting)

앱의 스키마 및 도메인 기반 딥링크 설정 및 캠페인 귀속 로직 안내입니다.

🛠️

TUNE 어드민 딥링크 설정 경로
데이터 매니저 ➔ 트래킹 링크 관리 ➔ 앱 및 딥링크 설정

[TUNE 어드민]
            └── 📂 데이터 매니저
            └── 📂 트래킹 링크 관리
            └── 📑 앱 및 딥링크 설정

상세 가이드: 해당 화면에서 앱의 Scheme 값, iOS의 Universal Link 도메인, Android의 App Link 호스트 정보를 사전에 바인딩해야만 정상적인 딥링크 광고 트래킹 링크를 생성할 수 있습니다.

딥링크(Deep Link) 어트리뷰션

사용자가 딥링크 광고를 클릭하여 신규 앱 설치를 진행하거나 앱을 즉시 실행했을 때, 파라미터 기반으로 광고 성과를 식별합니다.

동작 예시: https://example.com/install?campaignId=98765&source=facebook
기록 데이터: campaignId=98765, source=facebook 등
처리 흐름: 앱 최초 실행 시 딥링크 파라미터를 파싱하여 해당 캠페인 성과로 즉각 귀속합니다.

리타겟팅(Re-targeting) 캠페인 기여도 교체

리타겟팅 캠페인의 데이터는 기존 신규 유입 캠페인과 완전히 분리되어 관리됩니다.
이미 앱을 설치하여 사용 중인 상태에서 리타겟팅 광고 클릭이 추가로 감지될 경우, 기존 캠페인 기여도를 만료(무효화) 처리하고 신규 리타겟팅 캠페인 성과로 재귀속시킵니다.

SDK 연동 가이드

7. 설치 후 최종 검증

원태그 SDK 연동과 관리자 화면 세팅을 마친 후 아래 절차에 따라 데이터가 정상 수집 및 전송되는지 필히 점검하셔야 합니다.

TUNE 어드민 접속

TUNE 어드민에 로그인한 후 데이터매니저 ➔ 데이터 수집관리 ➔ 이벤트별 수집 현황 메뉴로 이동합니다.

이벤트 수집 상태 확인

앱 설치, 페이지뷰, 구매 완료 등 전송을 시도한 이벤트들이 '수집 활성화' 상태인지, 실시간 데이터가 유입되고 있는지 검증합니다.

포스트백 작동 확인

연동된 CDP 및 외부 DSP 파트너 채널로 실시간 데이터 포스트백이 오류 없이 누계 처리되고 있는지 보고서나 실시간 로그를 통해 최종 확인합니다.

App Client Post Installation Verification

앱 어트리뷰션 정상 수집 예시

1 / 10