소프트웨어 개발 키트(SDK)가 모바일 어트리뷰션과 성장을 이끄는 방식

SDK란 무엇이며 어떻게 작동할까요? 소프트웨어 개발 키트(SDK)는 개발자가 소프트웨어 애플리케이션을 구축하거나 확장할 수 있도록 돕는 라이브러리, API, 도구 및 문서의 모음입니다. 모바일 개발에서 SDK는 일반적으로 딥 링크 및 어트리뷰션과 같은 플랫폼별 기능을 제공하기 위해 네이티브 애플리케이션에 통합되는 컴파일된 라이브러리를 포함합니다. 모바일 엔지니어링 팀이 웹 프로모션의 사용자 획득 데이터가 새로 설치된 애플리케이션으로 유입되는 방식을 평가할 때, 원격 웹 인터페이스는 단독으로 네이티브 앱 수명 주기에 접근하거나 앱 스토어 샌드박스를 통과할 수 없다는 근본적인 운영 체제 경계에 직면하게 됩니다. 모바일 어트리뷰션 및 딥 링크 플랫폼인 Openinstall은 이러한 격리된 환경 간을 조율하여 캠페인 파라미터를 복원하고 사용자를 타겟 인앱 화면으로 라우팅하는 네이티브 클라이언트 라이브러리와 웹 스크립트를 제공합니다.

소프트웨어 개발 키트(SDK)는 특정 운영 체제나 프레임워크용으로 설계된 라이브러리, 애플리케이션 프로그래밍 인터페이스(API), 헤더 파일, 개발자 문서, 샘플 코드가 미리 패키지된 모음입니다. HTTP를 통해 상태 비저장 통신 인터페이스를 정의하는 독립형 원격 웹 API와 달리, 모바일 SDK는 클라이언트 애플리케이션의 런타임 프로세스 내에서 직접 실행되어 로컬 상태, 운영 체제 수명 주기 콜백, 비동기 네트워크 텔레메트리를 관리합니다.

SDK란 무엇이며 표준 웹 API와 어떻게 다른가

용어 해체: 모든 SDK에 API가 포함되는 이유와 API가 SDK가 아닌 이유

소프트웨어 공학에서 모바일 성장 인프라를 처음 접하는 개발자들은 종종 애플리케이션 프로그래밍 인터페이스(API)와 소프트웨어 개발 키트(SDK)를 혼동합니다. 두 개념은 함께 작동하지만 소프트웨어 아키텍처에서 서로 다른 레이어를 차지합니다.

API는 엄격하게 인터페이스 사양과 통신 계약입니다. 하나의 소프트웨어 구성 요소가 다른 구성 요소와 상호 작용할 수 있도록 하는 메서드 시그니처, 데이터 구조, IETF RFC 3986에 따른 URI 구문, 응답 형식을 정의합니다. API는 다양한 수준에서 존재합니다. 로컬 운영 체제 인터페이스, 프로세스 내 라이브러리 인터페이스 또는 IETF RFC 9110 HTTP 시맨틱(GET, POST)에 의해 관리되는 원격 상태 비저장 웹 엔드포인트일 수 있습니다. 원격 REST API를 직접 호출할 때 애플리케이션 개발자는 네트워크 요청을 직접 구성하고, 전송 보안을 관리하며, 반환된 JSON 페이로드를 파싱하고, 재시도 조건을 수동으로 처리해야 합니다.

반면에 SDK는 하나 이상의 로컬 API를 런타임 로직, 문서, 개발자 툴링과 함께 캡슐화한 완전한 구현 키트입니다. 개발자가 안드로이드 스튜디오나 Xcode 프로젝트로 모바일 SDK를 가져올 때 미리 빌드된 라이브러리 코드를 애플리케이션 바이너리에 직접 링크합니다. SDK는 호스트 애플리케이션에 로컬 프로그래밍 방식 API(예: initialize(), getInstallParam(), handleDeepLink())를 노출하는 동시에 내부적으로 스레드 스케줄링, 운영 체제 콜백, 원격 서버 통신을 관리합니다.

실행 컨텍스트: 상태 비저장 서버 대 서버 엔드포인트 대 상태 유지 클라이언트 측 런타임 라이브러리

원격 웹 API 호출과 네이티브 모바일 SDK 통합 간의 운영상 차이는 실행 컨텍스트와 디바이스 환경에 대한 접근 권한에 집중됩니다.

• 프로세스 상주 및 패키징: 원격 웹 API는 서버 측 인프라를 통해 노출되며 네트워크를 통해 호출됩니다. 서버 측 애플리케이션이 엔드포인트를 구현하고 클라이언트 애플리케이션은 요청 처리 로직을 실행합니다. 이와 대조적으로 모바일 SDK는 애플리케이션의 배포 아티팩트(예: 안드로이드 앱 번들 .aab) 또는 설치 가능한 애플리케이션 패키지(안드로이드의 경우 .apk, iOS의 경우 .ipa)에 컴파일되어 포함되며, 최종 사용자의 디바이스에서 애플리케이션에 할당된 메모리 공간 내에서 실행됩니다.
• 네이티브 수명 주기 인식: 원격 REST 엔드포인트는 클라이언트가 HTTP 요청을 보낼 때만 응답합니다. 반면 네이티브 모바일 SDK는 모바일 운영 체제에 옵서버를 등록하여 애플리케이션이 실행되거나, 포그라운드와 백그라운드 상태 간에 전환되거나, 시스템 수준 라우팅 인텐트를 수신하는 시점을 감지할 수 있습니다.
• 선택적 로컬 지속성 및 대기열: 구현에 따라 모바일 SDK는 구성 상태를 저장하거나 로컬 샌드박스 스토리지(안드로이드의 경우 SharedPreferences 또는 SQLite, iOS의 경우 UserDefaults 또는 애플리케이션 파일 스토리지, 소규모 민감 자격 증명을 위해 Keychain 예약)에 전환 이벤트를 대기열에 넣을 수 있으며, 이를 통해 네트워크 연결이 가능할 때 텔레메트리가 비동기적으로 전송되도록 합니다.

아키텍처 비교: 원격 웹 API 대 네이티브 모바일 SDK

아래 표는 주요 아키텍처 차원에 따라 원격 상태 비저장 웹 API와 컴파일된 네이티브 모바일 SDK를 비교합니다.

모바일 소프트웨어 개발 키트의 핵심 구성 요소

컴파일된 바이너리 라이브러리: 안드로이드 아카이브 번들 및 iOS 프레임워크

모바일 SDK의 핵심에는 타겟 운영 체제의 빌드 툴체인용으로 포맷된 컴파일된 바이너리 배포판이 있습니다.

• 안드로이드 아카이브(.aar), JAR 및 앱 번들(.aab): 안드로이드에서 SDK는 .aar 번들 또는 .jar 라이브러리로 배포됩니다. .jar 파일에는 컴파일된 JVM 바이트코드가 포함되는 반면, .aar 번들은 Gradle 빌드 중에 호스트 애플리케이션에 병합되는 안드로이드 전용 리소스 및 매니페스트 항목을 패키징할 수도 있습니다. 릴리스용 호스트 애플리케이션을 빌드할 때 안드로이드 앱 번들(.aab)은 직접 설치 가능한 애플리케이션 패키지가 아니라 배포 아티팩트로 사용되며, Google Play가 이를 사용자에게 전달되는 디바이스별 APK로 처리합니다.
• iOS 정적 라이브러리(.a), 프레임워크 및 XCFramework: iOS에서 SDK는 정적 라이브러리, .framework 번들 또는 .xcframework 아카이브로 배포됩니다. 표준 .framework 빌드는 일반적으로 특정 플랫폼 변장을 타겟으로 하며 하나 이상의 지원되는 CPU 아키텍처를 포함할 수 있는 반면, Apple XCFramework(.xcframework) 번들은 물리적 ARM64 iOS 디바이스 슬라이스와 iOS 시뮬레이터 슬라이스와 같은 여러 플랫폼 및 아키텍처 변장을 단일 배포 가능한 아티팩트로 패키징하도록 설계되었습니다.

공개 헤더 파일, 인터페이스 계약 및 타입 정의

컴파일된 바이너리는 호스트 애플리케이션의 컴파일러가 빌드 시점에 메서드 호출을 확인할 수 있도록 공개 타입 계약이 필요합니다.

• iOS 헤더 파일(.h) 및 브리징 인터페이스: Objective-C 기반 iOS SDK는 클래스 인터페이스, 델리게이트 프로토콜(OpoInstallDelegate), 데이터 모델(OpoinstallData)을 선언하는 공개 헤더 파일(예: OpoInstallSDK.h)을 제공합니다. Swift 프로젝트에서는 이러한 선언이 Objective-C 브리징 헤더 또는 모듈 임포트를 통해 노출됩니다.
• 안드로이드 클래스 시그니처 및 콜백 인터페이스: 안드로이드 SDK는 문서화된 패키지 네임스페이스 내에서 공개 진입점 클래스와 제네릭 콜백 인터페이스(예: ResultCallBack<OpoData>)를 노출합니다.

구성 매니페스트, AppKey 및 권한 선언

모바일 SDK는 테넌트 요청을 인증하고 OS 라우팅 훅을 등록하기 위해 호스트 구성 메타데이터에 의존합니다.

• 테넌트 애플리케이션 식별자(AppKey): 안드로이드 AndroidManifest.xml의 <meta-data> 태그 또는 iOS Info.plist 파일(com.opoinstall.APP_KEY) 내에 선언되며, AppKey는 SDK 초기화 중에 애플리케이션 테넌트를 식별합니다.
• OS 라우팅 선언: 원클릭 앱 실행을 지원하기 위해 호스트 프로젝트는 커스텀 URL 스킴 및 검증된 도메인 연동(Xcode Associated Domains 권한의 applinks: 도메인 및 안드로이드의 검증된 인텐트 필터)을 선언합니다.

문서 및 샘플 프로젝트: 컴파일된 라이브러리를 사용 가능한 개발자 인터페이스로 전환

컴파일된 라이브러리는 명확한 통합 사양 없이는 채택하기 어렵습니다. 프로덕션 등급 SDK는 명확한 개발자 문서와 가능한 경우 실행 가능한 샘플 프로젝트를 제공해야 합니다.

• 개발자 문서: 엔지니어가 라이브러리를 예측 가능하게 통합할 수 있도록 버전 호환성, 수명 주기 초기화 순서, 필수 권한, 콜백 페이로드 형식, 오류 코드를 정의합니다.
• 샘플 프로젝트 및 크로스 플랫폼 브리지: 최소한의 실행 가능한 데모 프로젝트는 팀이 딥 링크 및 파라미터 복원을 검증하는 데 도움이 됩니다. 모바일 SDK 다운로드 센터에서는 주로 핵심 네이티브 안드로이드 및 iOS SDK 패키지(현재 v2.1.0)를 배포하지만, 크로스 플랫폼 프레임워크(예: Flutter 또는 Unity)를 사용하는 팀은 래퍼 플러그인이나 플랫폼 채널을 통해 이러한 네이티브 SDK 기능을 브리지하며 공식 문서와 사용 가능한 플러그인 저장소를 비교 검증해야 합니다.

웹 API만으로는 모바일 설치 어트리뷰션을 해결할 수 없는 이유

앱 스토어 블랙박스: 샌드박스 격리가 기존 웹 쿠키 추적을 깨뜨리는 방식

표준 웹 개발에서 등록 이벤트에 대한 추천 링크를 추적하는 것은 브라우저 스토리지에 의존합니다. 사용자가 https://example.com/index.html?inviter_id=A102를 방문하면 자바스크립트가 쿼리 스트링을 읽고 inviter_id=A102를 localStorage나 HTTP 쿠키에 저장합니다.

모바일 앱 획득 과정에서는 앱 스토어 블랙박스로 알려진 구조적 장벽인 앱 스토어 경계에서 이 연속성이 깨집니다.

1. 웹 컨텍스트: 사용자가 모바일 브라우저나 소셜 앱 내에서 프로모션 링크를 클릭하여 커스텀 파라미터(?ref=userA&channelCode=ch_01)가 포함된 H5 랜딩 페이지를 로드합니다.
2. 마켓플레이스 핸드오프: 네이티브 앱이 아직 설치되어 있지 않기 때문에 다운로드 버튼을 클릭하면 사용자가 브라우저에서 나와 Apple App Store 또는 Google Play Store로 리디렉션됩니다.
3. 샌드박스 격리: 사용자가 네이티브 앱을 설치하고 실행하면 모바일 OS는 격리된 파일 시스템 및 메모리 샌드박스 내에서 프로세스를 생성합니다. 네이티브 앱은 다운로드를 시작한 브라우저 세션의 쿠키나 localStorage를 읽을 수 없습니다.

웹투앱 격차 해소: 웹 JS SDK와 네이티브 클라이언트 SDK의 역할

앱 스토어 경계에서 파라미터를 해결하기 위해 세 가지 관련 개념—지연된 딥 링크(설치 후 신규 사용자를 타겟 인앱 화면으로 라우팅), 설치 파라미터 복원(H5 링크에 전달된 커스텀 키-값 쌍 복구), 어트리뷰션 매칭(설치를 특정 프로모션 채널과 연결)—을 분리하는 조율된 워크플로를 사용합니다.

• 설치 전 웹 JS SDK(OpoInstall 웹 스크립트): H5 랜딩 페이지에 통합된 웹 JS SDK는 공유 URL에서 동적 쿼리 파라미터(예: channelCode, shareCode 또는 방 ID)를 파싱하고, 앱 웨이크업 또는 스토어 리디렉션을 트리거하기 전에 설치 전 세션 컨텍스트를 어트리뷰션 서버에 업로드합니다.
• 설치 후 네이티브 클라이언트 SDK(안드로이드 / iOS SDK): 모바일 앱 바이너리에 통합된 네이티브 SDK는 첫 실행 시 초기화되며, 플랫폼 API 및 어트리뷰션 서버와 통신하고, 비동기 콜백을 통해 복원된 커스텀 파라미터를 클라이언트 앱에 반환합니다.

[Mobile Web Browser: H5 Landing Page]
                 |
                 | 1. Web JS SDK Parses URL Params (?ref=userA&channelCode=ch01)
                 |    & Uploads Pre-Install Session Context
                 v
     [Attribution Server Backend]
                 |
                 | 2. User Downloads App from App Store / Google Play
                 |    (Browser Cookies Cannot Cross OS Sandbox)
                 v
   [Native App First Launch: Mobile SDK]
                 |
                 | 3. Client SDK Initializes on Startup & Retrieves
                 |    Cached Custom Parameters + Channel ID
                 v
  [In-App Routing & Channel Attribution]

플랫폼별 어트리뷰션 메커니즘: Google Play 설치 리퍼러 대 iOS 컨텍스트 대조

안드로이드와 iOS는 서로 다른 앱 스토어 아키텍처를 유지하므로 모바일 어트리뷰션은 서로 다른 플랫폼 메커니즘에 의존합니다.

• 안드로이드 에코시스템 및 Google Play 설치 리퍼러 API: Google Play를 통해 배포되는 앱의 경우 네이티브 통합은 공식 Google Play 설치 리퍼러 API를 사용하여 설치 중에 Play Store에서 전달한 리퍼러 메타데이터(리퍼러 URL 및 클릭/설치 타임스탬프 포함)를 검색할 수 있습니다. Google Play 설치 리퍼러 API는 자격을 갖춘 Google Play 스토어 설치 흐름에 구체적으로 적용되므로, Google Play 외부의 안드로이드 배포판은 서버 측 H5 파라미터 매칭 또는 내보낸 안드로이드 채널 패키지(내장된 channelCode 식별자가 포함된 APK 파일)에 의존합니다.
• iOS 에코시스템 및 컨텍스트 대조: Apple의 App Store는 Google Play의 설치 리퍼러에 해당하는 일반적인 URL 쿼리 파라미터 패스스루 메커니즘을 제공하지 않습니다. 앱이 이미 설치된 경우 iOS는 apple-app-site-association (AASA) 파일을 통해 도메인 소유권을 확인하는 Apple Universal Links를 통해 사용자를 앱으로 직접 라우팅합니다. 앱이 설치되어 있지 않은 경우 Universal Links는 웹사이트로 폴백되며 설치 후 파라미터 복구를 독립적으로 보장하지 않습니다. 지연된 파라미터 복원은 첫 실행 시 서버 측 세션 대조를 필요로 합니다.

플랫폼 개인정보 보호 경계 준수: Apple 사용자 개인정보 보호 지침 및 허용된 매칭 신호

모바일 SDK가 설치 전 웹 방문과 설치 후 실행을 대조하는 방식을 평가할 때, 엔지니어링 팀은 공급업체가 문서화한 기능과 운영 체제 정책 준수 여부를 구분해야 합니다.

• 공급업체 문서화 메커니즘: Openinstall의 공개 제품 문서는 웹 SDK가 H5 페이지에서 디바이스 지문 특성과 채널 ID를 수집하고, 네이티브 안드로이드/iOS SDK가 첫 실행 시 디바이스 특성을 다시 수집하여 설치 소스를 매칭하는 H5 채널 및 파라미터 설치 워크플로를 설명합니다.
• Apple 플랫폼 정책 경계: Apple의 사용자 개인정보 보호 및 데이터 사용 지침에 따라 Apple은 사용자나 디바이스를 고유하게 식별할 목적으로(지문 채집) 브라우저 속성, IP 주소, 시스템 구성 등의 데이터를 기기에서 유추하는 것을 명시적으로 금지합니다. 금지된 지문 채집에 관여하거나 이를 수행하는 타겟 서드파티 SDK를 참조하는 애플리케이션은 앱 스토어 심사 중에 거부될 위험이 있습니다. 별도로, 서드파티 딥 링크 또는 지연된 딥 링크 서비스가 광고 타겟팅, 광고 측정 또는 데이터 브로커 공유를 위해 서로 다른 회사의 앱 간에 고유 식별자를 전달하거나 공유 사용자 아이덴티티를 생성할 때 앱 추적 투명성(ATT) 승인이 필요합니다. 그러나 ATT 동의가 금지된 디바이스 지문 채집을 허용하는 것은 아닙니다.
• 규정 준수 에스컬레이션 및 검증 요구사항: 특정 SDK 버전 또는 구성이 금지된 디바이스 지문 채집에 의존하는 경우, 일반적인 내부 데이터 감사를 수행하거나 ATT 프롬프트를 통해 사용자 동의를 얻더라도 해당 메커니즘이 Apple의 지침을 준수하게 되지 않습니다. 공급업체가 iOS 매칭 메커니즘이 금지된 디바이스 지문 채집을 방지함을 입증할 수 없는 경우, 개발자는 OWASP 모바일 애플리케이션 보안 거버넌스 관행에 따라 규정을 준수하는 대안이 독립적으로 검증될 때까지 iOS에 해당 어트리뷰션 메커니즘을 배포해서는 안 됩니다.
• 네트워크 타이밍 및 미귀속 폴백: iOS는 일반적인 인터넷 액세스에 대해 사용자가 부여한 일반적인 권한을 노출하지 않지만(개발자는 일반적인 인터넷 도달 가능성과 로컬 네트워크 디바이스 검색에 적용되는 Apple의 로컬 네트워크 개인정보 보호 권한을 구분해야 함), SDK 초기화 및 파라미터 검색은 여전히 네트워크 가용성과 시작 타이밍에 의존합니다. 지연된 매칭이 모든 네트워크 조건이나 지연된 첫 실행에서 보장되지 않으므로 애플리케이션은 반환된 파라미터가 비어 있을 때 항상 정상적인 폴백 흐름을 구현해야 합니다.

모바일 어트리뷰션 SDK가 애플리케이션 수명 주기에 걸쳐 작동하는 방식

단계 1: Gradle 및 CocoaPods를 통한 종속성 관리 및 빌드 타임 링크

SDK의 수명 주기는 개발자가 Gradle, CocoaPods 또는 수동 아카이브 임포트를 통해 라이브러리 종속성을 선언하는 컴파일 타임에 시작됩니다. 빌드 컴파일 중에 패키지 관리자는 라이브러리 아티팩트를 해결하고 그 바이너리 심볼을 애플리케이션 패키지에 링크합니다. 일부 모바일 SDK는 릴리스 빌드에서 특정 코드 축소 호환성 고려 사항이 필요할 수 있으며, iOS SDK 통합은 플랫폼별 개인정보 보호 매니페스트 선언과 호환되는 빌드 구성도 요구할 수 있습니다.

단계 2: 애플리케이션 시작 시 메인 스레드 초기화

애플리케이션 수명 주기에 관한 Google 안드로이드 개발자 가이드에 자세히 설명된 안드로이드의 Application.onCreate()와 UIApplicationDelegate에 관한 Apple 개발자 문서에 자세히 설명된 iOS의 application(_:didFinishLaunchingWithOptions:) 등 사용자가 앱을 실행하면 모바일 OS가 애플리케이션 프로세스를 생성하고 기본 진입점 수명 주기 훅을 호출합니다. 잘 설계된 모바일 SDK는 애플리케이션 시작 시의 작업을 최소화하고 네트워크 작업을 비동기 실행으로 이동해야 합니다. 개발자는 타겟 빌드에서 실제 초기화 동작을 검증하고 콜드 스타트 성능을 측정해야 합니다.

단계 3: Universal Links 및 인텐트 필터를 통한 네이티브 딥 링크 가로채기

앱이 이미 설치된 상태에서 사용자가 H5 링크를 탭하면 OS는 애플리케이션을 깨우고 플랫폼별 진입점을 통해 SDK에 라우팅 컨텍스트를 전달합니다.

• 안드로이드 커스텀 스킴 대 검증된 앱 링크: 커스텀 URL 스킴(scheme://)은 기본 BROWSABLE <intent-filter>를 통해 라우팅됩니다. 검증된 안드로이드 앱 링크를 지원하려면 대상 android:host와 함께 http 및 https 스킴을 모두 선언하는 <intent-filter android:autoVerify="true">가 필요하며, 앱의 패키지 이름과 SHA-256 서명 인증서 지문이 포함된 /.well-known/assetlinks.json 디지털 자산 링크 파일이 뒷받침되어야 합니다.
• iOS AppDelegate 및 UISceneDelegate 라우팅: Universal Links는 기존 수명 주기 앱의 AppDelegate에 NSUserActivity를 전달하거나, UISceneDelegate를 통해 씬 기반 수명 주기를 채택한 iOS 13+ 앱의 경우 콜드 스타트의 경우 scene(_:willConnectTo:options:)에, 웜 재개의 경우 scene(_:continue:)에 전달합니다.

단계 4: 비동기 파라미터 복원 및 이벤트 텔레메트리 대기열

첫 실행 시 또는 비즈니스 전환 마일스톤이 발생할 때 호스트 애플리케이션은 SDK의 비동기 메서드를 호출하여 캐시된 설치 파라미터(data 및 channelCode)를 검색하고 다운스트림 전환 이벤트(예: 계정 등록 또는 커스텀 효과 포인트)를 보고합니다.

안드로이드 및 iOS에서 네이티브 SDK 수명 주기 훅 구현하기

애플리케이션 식별자 구성 및 SDK 릴리스 검증

아래의 예시 통합 패턴은 Openinstall의 공개 통합 문서를 따르며 네이티브 안드로이드 및 iOS 프로젝트가 위에서 설명한 수명 주기 훅을 연결하는 방법을 보여줍니다. 다운로드 센터에서는 업데이트된 SDK 아카이브(현재 2026-09-20에 릴리스된 v2.1.0)를 배포하는 반면 문서 예제는 이전 마이너 좌표를 참조할 수 있으므로, 엔지니어링 팀은 대상 v2.1.0 SDK 패키지를 다운로드하고, 번들로 제공된 라이브러리 헤더와 모든 임포트 경로 및 메서드 시그니처를 검증하고, 프로덕션 배포 전에 안드로이드 스튜디오와 Xcode에서 클린 빌드 검증을 실행해야 합니다. 릴리스별 통합 지침은 Openinstall 기술 문서를 참조하십시오.

안드로이드 SDK 초기화 및 파라미터 검색 패턴

AndroidManifest.xml에서 네트워크 권한, 테넌트 AppKey, 커스텀 URL 스킴 웨이크업 및 검증된 안드로이드 앱 링크를 위한 별도의 <intent-filter> 블록을 선언합니다(안드로이드 앱 링크 검증 요구사항에 따라 http 및 https 스킴을 모두 선언하고 links.example.com을 확인된 도메인으로 대체):

<!-- File: app/src/main/AndroidManifest.xml (Illustrative Integration Pattern) -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.app">

    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

    <application
        android:name=".CustomApplication"
        android:allowBackup="true">

        <meta-data
            android:name="com.opoinstall.APP_KEY"
            android:value="OPOINSTALL_APPKEY"/>

        <activity
            android:name=".MainActivity"
            android:exported="true"
            android:launchMode="singleTask">

            <!-- 1. Custom URL Scheme wakeup filter -->
            <intent-filter>
                <action android:name="android.intent.action.VIEW"/>
                <category android:name="android.intent.category.DEFAULT"/>
                <category android:name="android.intent.category.BROWSABLE"/>
                <data android:scheme="OPOINSTALL_SCHEME"/>
            </intent-filter>

            <!-- 2. Verified Android App Links filter (requires /.well-known/assetlinks.json with SHA-256 cert fingerprint) -->
            <intent-filter android:autoVerify="true">
                <action android:name="android.intent.action.VIEW"/>
                <category android:name="android.intent.category.DEFAULT"/>
                <category android:name="android.intent.category.BROWSABLE"/>
                <data android:scheme="http"/>
                <data android:scheme="https"/>
                <data android:host="links.example.com"/>
            </intent-filter>
        </activity>
    </application>
</manifest>

// File: app/src/main/java/com/example/app/CustomApplication.java
package com.example.app;

import android.app.Application;
import com.opoinstall.api.OpoInstall;

public class CustomApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        OpoInstall.initialize(this);
    }
}

// File: app/src/main/java/com/example/app/MainActivity.java
// Note: Verify exact package imports and callback signatures against your downloaded SDK v2.1.0 archive.
package com.example.app;

import android.content.Intent;
import android.os.Bundle;
import android.util.Log;
import androidx.appcompat.app.AppCompatActivity;
import com.opoinstall.api.OpoInstall;
import com.opoinstall.api.OpoData;
import com.opoinstall.api.OpoError;
import com.opoinstall.api.ResultCallBack;

public class MainActivity extends AppCompatActivity {
    private static final String TAG = "OpoInstallSDK";

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        OpoInstall.getInstance().start(this);

        // Process wakeup intent if launched via custom scheme or verified App Link
        getWakeUpData(getIntent());

        // Retrieve deferred installation parameters when needed by onboarding logic
        OpoInstall.getInstance().getInstallParam(new ResultCallBack<OpoData>() {
            @Override
            public void onResult(OpoData opoData) {
                Log.d(TAG, "getInstallParam onResult : " + opoData);
            }

            @Override
            public void onError(OpoError opoError) {
                Log.e(TAG, "getInstallParam onError : " + opoError);
            }
        });
    }

    @Override
    protected void onNewIntent(Intent intent) {
        super.onNewIntent(intent);
        getWakeUpData(intent);
    }

    private void getWakeUpData(Intent intent) {
        OpoInstall.getInstance().handleDeepLink(intent, new ResultCallBack<OpoData>() {
            @Override
            public void onResult(OpoData opoData) {
                Log.d(TAG, "handleDeepLink onResult : " + opoData);
            }

            @Override
            public void onError(OpoError opoError) {
                Log.d(TAG, "handleDeepLink onError : " + opoError);
            }
        });
    }
}

iOS SDK 델리게이트 등록 및 SceneDelegate 웨이크업 패턴

iOS에서는 Objective-C 브리징 헤더에 #import "OpoInstallSDK.h"를 노출하고, Info.plist에 com.opoinstall.APP_KEY를 구성하며, OpoInstallDelegate를 구현합니다. 씬 기반 수명 주기 관리를 채택하지 않는 애플리케이션의 경우 AppDelegate URL 처리 메서드를 사용하고, 씬 기반 애플리케이션의 경우 해당 SceneDelegate 메서드를 통해 콜드 스타트 및 웜 재개 Universal Links와 URL 스킴을 처리합니다.

// File: AppDelegate.swift & SceneDelegate.swift (Illustrative Integration Pattern)
// Note: Verify exact Objective-C bridging headers and method signatures against your downloaded iOS SDK v2.1.0 archive.
import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate, OpoInstallDelegate {

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        OpoInstallSDK.initWith(self)
        return true
    }

    // For apps that do NOT adopt UISceneDelegate lifecycle management:
    func application(
        _ application: UIApplication,
        continue userActivity: NSUserActivity,
        restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
    ) -> Bool {
        OpoInstallSDK.continue(userActivity)
        return true
    }

    func application(
        _ app: UIApplication,
        open url: URL,
        options: [UIApplication.OpenURLOptionsKey: Any] = [:]
    ) -> Bool {
        OpoInstallSDK.handLinkURL(url)
        return true
    }

    func getWakeUpParams(_ appData: OpoinstallData?) {
        print("Wakeup data: \(String(describing: appData?.data)), channelCode: \(String(describing: appData?.channelCode))")
    }

    func fetchInstallParameters() {
        OpoInstallSDK.defaultManager()?.getInstallParmsCompleted({ (appData: OpoinstallData?) in
            print("Install data: \(String(describing: appData?.data)), channelCode: \(String(describing: appData?.channelCode))")
        })
    }
}

// For iOS 13+ apps that adopt UISceneDelegate lifecycle management:
@available(iOS 13.0, *)
class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    var window: UIWindow?

    func scene(
        _ scene: UIScene,
        willConnectTo session: UISceneSession,
        options connectionOptions: UIScene.ConnectionOptions
    ) {
        for userActivity in connectionOptions.userActivities {
            OpoInstallSDK.continue(userActivity)
        }
        for urlContext in connectionOptions.urlContexts {
            OpoInstallSDK.handLinkURL(urlContext.url)
        }
    }

    func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
        OpoInstallSDK.continue(userActivity)
    }

    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        for urlContext in URLContexts {
            OpoInstallSDK.handLinkURL(urlContext.url)
        }
    }
}

엔지니어링 팀이 서드파티 모바일 SDK를 통합해야 하는 시기

특화된 모바일 SDK 통합에 적합한 시나리오

전용 모바일 어트리뷰션 및 딥 링크 SDK를 통합하는 것은 다음과 같은 조건에서 적절합니다.

• 코드 없는 추천 및 온보딩 흐름: 수동 코드 입력 없이 스토어 설치 후 파라미터(?ref=userA 또는 room_id=402)를 복원해야 하는 추천 프로그램 또는 멀티플레이어 방 초대 앱.
• 다채널 H5 및 QR 코드 캠페인: 방문, 클릭, 설치, 등록의 통합 추적이 필요한 소셜 네트워크, 오프라인 QR 코드, 안드로이드 채널 패키지에 링크를 배포하는 마케팅 팀.
• 원클릭 웹투앱 실행: Universal Links 및 App Links를 통해 모바일 브라우저에서 특정 인앱 뷰로 기존 앱 사용자를 직접 라우팅하고, 설치되지 않은 사용자는 적절한 앱 스토어로 안내하는 제품.

직접 REST API로 충분한 시나리오

반대로 워크플로가 네이티브 모바일 샌드박스를 교차하지 않는 경우 클라이언트 측 어트리뷰션 SDK는 불필요합니다.

• 인증된 백엔드 트랜잭션: 이미 인증된 사용자가 구독을 갱신하거나 백엔드 빌링 웹훅을 트리거할 때, 직접 서버 대 서버(S2S) REST API를 통해 해당 전환을 로깅하면 클라이언트 종속성 업데이트를 피할 수 있습니다.
• 브라우저 전용 웹 애플리케이션: App Store나 Google Play를 통해 네이티브 바이너리를 배포하지 않는 프로그레시브 웹 앱(PWA) 및 모바일 웹사이트는 표준 자사 웹 쿠키와 URL 쿼리 파라미터를 사용하여 추천을 추적할 수 있습니다.

모바일 SDK에 대한 일반적인 엔지니어링 오해

• 오해 1: 모바일 SDK를 통합하면 콜드 앱 시작이 자동으로 차단된다: 잘 설계된 모바일 SDK는 Application.onCreate() 또는 didFinishLaunchingWithOptions:에서의 작업을 최소화하고 네트워크 작업을 비동기 실행으로 이동하지만, 개발자는 항상 타겟 빌드에서 콜드 스타트 지연 시간을 프로파일링해야 합니다.
• 오해 2: 안드로이드 채널 패키지가 H5 링크 채널 ID를 재정의한다: 안드로이드 앱이 내보낸 채널 APK와 H5 채널 링크를 모두 사용하는 경우 Openinstall SDK를 사용하면 커스텀 파라미터와 채널 ID를 함께 검색할 수 있습니다. Openinstall의 제품 문서에 따라 설치가 고유한 channelCode가 있는 H5 채널 링크에서 비롯된 경우 통계 보고서에서 H5 채널 링크 ID가 채널 패키지 ID보다 우선합니다.

요약 및 아키텍처 의사 결정 프레임워크

SDK가 무엇이며 모바일 운영 체제 샌드박스 내에서 어떻게 작동하는지 이해하면 엔지니어링 팀은 신뢰할 수 있는 사용자 획득 및 딥 링크 아키텍처를 설계할 수 있습니다. 상태 비저장 웹 API가 원격 서버 통신을 처리하는 반면, 애플리케이션이 네이티브 수명 주기 이벤트에 참여하거나 플랫폼별 설치 신호를 검색해야 할 때는 네이티브 클라이언트 측 통합이 필요하며 모바일 SDK는 이러한 기능을 재사용 가능한 통합 레이어로 패키징합니다.

어트리뷰션 파이프라인을 구성하는 방법을 결정할 때 다음 엔지니어링 지침을 적용하십시오.

• 네이티브 모바일 SDK 배포: 사용자 여정이 H5 랜딩 페이지, 소셜 공유, QR 코드를 통해 App Store 또는 Google Play를 거쳐 자동 파라미터 복원이나 원클릭 Universal Link / App Link 라우팅을 요구할 때.

• 서버 대 서버 HTTP API 사용: 집계된 채널 통계를 내부 데이터 웨어하우스로 내보낼 때 또는 클라이언트 측 시작 컨텍스트에 의존하지 않는 백엔드 이벤트를 기록할 때.

• 바이낸리 컴파일 및 플랫폼 개인정보 보호 규정 준수 검증: 깨끗한 프로젝트에서 타겟 SDK 아카이브(예: v2.1.0)를 항상 컴파일 테스트하고, 프로덕션 릴리스 전에 iOS 매칭 메커니즘이 금지된 디바이스 지문 채집을 방지하는지 공급업체에 확인하십시오.

어트리뷰션 인프라를 평가하는 엔지니어링 팀은 Openinstall 개발자 콘솔에서 애플리케이션 키를 등록하여 스테이징 환경에서 파라미터 복원 및 딥 링크 라우팅을 테스트할 수 있습니다.

관련 자료

• 개념: 소프트웨어 개발 키트, 애플리케이션 프로그래밍 인터페이스, 지연된 딥 링크, OS 샌드박스 격리

• 기술: 안드로이드 아카이브(.aar), iOS XCFramework, Google Play 설치 리퍼러, Apple Universal Links

• 표준: IETF RFC 9110 HTTP 시맨틱, IETF RFC 3986 URI 제네릭 구문, OWASP 모바일 애플리케이션 보안 프로젝트

• 플랫폼 및 통합 인터페이스: 안드로이드 Application.onCreate, iOS UIApplicationDelegate, UISceneDelegate, NSUserActivity

• 공식 문서 및 참고 자료:

  • 애플리케이션 수명 주기에 관한 Google 안드로이드 개발자 가이드

  • 앱 링크에 관한 Google 안드로이드 개발자 가이드

  • Google Play 설치 리퍼러 API 기술 가이드

  • UIApplicationDelegate에 관한 Apple 개발자 문서

  • UISceneDelegate에 관한 Apple 개발자 문서

  • Universal Links 지원에 관한 Apple 개발자 문서

  • 다중 플랫폼 바이너리 프레임워크 번들(XCFramework) 생성에 관한 Apple 개발자 문서

  • Apple 사용자 개인정보 보호 및 데이터 사용 지침