모바일 앱은 어떻게 설치 후 초대 파라미터를 전달할까요?

모바일 앱은 어떻게 설치 후 초대 파라미터를 전달할까요? 설치 후 초대 파라미터를 전달하려면 브라우저 측의 리디렉션 컨텍스트를 네이티브 클라이언트의 콜드 스타트 생명주기와 연결하는 서버 지원 매칭 파이프라인을 실행해야 합니다. 플레이어 ID, 그룹 토큰, 쿠폰 ID와 같은 동적 페이로드를 첫 실행 시점에 복원함으로써 개발자는 수동 프로모션 코드 입력 없이도 컨텍스트 기반 온보딩을 구현할 수 있습니다.

핵심 요약

• 온보딩 컨텍스트 복구: 앱 스토어의 경계를 넘어 콜드 스타트 시점에 동적 초대 파라미터를 복원합니다.
• 상태 전환 파이프라인: 브라우저 측 메타데이터를 네이티브 애플리케이션 시작 세션과 연결합니다.
• 파라미터 토큰 검증: 보안 백엔드 검사를 통해 리디렉션 루프 전반에서 데이터 무결성을 보장합니다.
• 개인정보 보호 기반 매칭: 영구적인 하드웨어 식별자를 수집하지 않고도 사용자 맞춤형 메타데이터를 확인합니다.

운영체제가 브라우저 저장소와 네이티브 샌드박스를 분리하는 이유

설치 파라미터가 앱 스토어 다운로드를 거치며 어떻게 네이티브 환경으로 전송되지 않는지 이해하려면 최신 운영체제의 보안 경계를 분석해야 합니다. iOS와 Android 모두 사용자 개인정보 보호를 위해 엄격한 컨테이너화 정책을 시행합니다. WebKit이나 Chromium이 관리하는 HTTP 쿠키, 로컬 저장소, 세션 데이터베이스와 같은 표준 브라우저 저장소는 네이티브 애플리케이션 샌드박스와 완전히 분리되어 있습니다.

이러한 의도적인 아키텍처 장벽으로 인해 잠재 사용자가 브라우저에서 추천 링크를 클릭하면 웹 뷰 세션과 네이티브 운영체제 환경 사이에 샌드박스 파티션이 즉시 생성됩니다. 사용자가 앱 스토어나 Google Play로 리디렉션되면, 네이티브 스토어 클라이언트는 이전 브라우저 상태를 읽어올 수 있는 API 노출 권한이 없습니다. 앱 패키지가 설치되고 첫 콜드 스타트가 실행되면, 네이티브 애플리케이션은 공유 메모리 접근 권한이 없는 새로 초기화된 격리 컨테이너에서 실행됩니다. 이러한 운영체제 격리로 인해 브라우저 측의 초대 컨텍스트가 단절되며, 따라서 설치 경계를 넘어 동적 컨텍스트를 재구성하는 과정이 필수적입니다.

설치 지연형 파라미터의 생명주기

자동 파라미터 복원 시스템은 브라우저 환경과 네이티브 앱 클라이언트 간의 보안 데이터 파이프라인을 구축하여 데이터 손실 문제를 해결합니다. 런타임 시 설치 지연형 파라미터의 생명주기는 스토어 샌드박스 전체에서 실행 컨텍스트를 유지하기 위해 몇 가지 개별 단계를 거칩니다:

브라우저 세션
       │
       ▼
리디렉션 캡처 (H5 메타데이터 페이로드)
       │
       ▼
앱 스토어 리디렉션 (설치 샌드박스)
       │
       ▼
콜드 런치 인터셉트 (네이티브 초기화)
       │
       ▼
비동기 파라미터 쿼리 (매칭 서버)
       │
       ▼
동적 컨텍스트 해석 (로컬 런타임 실행)

이 멀티 플랫폼 시퀀스는 초대자 ID, 동적 쿠폰 코드, 게임 로비 토큰과 같은 동적 페이로드가 안전하게 보존되도록 합니다. 사용자가 앱을 처음 설치하고 실행하면, 네이티브 클라이언트 라이브러리는 플랫폼 정책이 허용하는 범위 내에서 클립보드 캐시 등을 조회하여 원래 파라미터를 복구합니다.

설치 후 모바일 앱이 복원할 수 있는 파라미터 유형

최신 모바일 애플리케이션은 설치 후 런타임을 사용자 정의하기 위해 다양한 설치 파라미터를 활용합니다. 이러한 동적 파라미터 전달 기능을 통해 개발자는 변수를 하드코딩하지 않고도 첫 실행 상태를 구성할 수 있습니다:

이러한 동적 컨텍스트 토큰을 복원하면 개발자는 일반적인 환영 화면을 건너뛰고 사용자의 잔존율을 높이는 맞춤형 온보딩 흐름을 실행할 수 있습니다.

런타임 상태 머신 및 부트스트랩 파이프라인

레이아웃 깜박임이나 빈 화면 없이 복원된 실행 파라미터를 처리하기 위해 네이티브 애플리케이션 아키텍처는 비동기 부트스트랩 파이프라인을 구현합니다. 모바일 애플리케이션이 실행될 때 초기화 프로세스는 엄격한 상태 머신 라우팅 로직을 따릅니다:

• 초기화 상태: 네이티브 클라이언트 라이브러리가 메인 애플리케이션 스레드에서 초기화되며, 첫 UI 렌더링 패스 이전에 콜백 리스너를 등록합니다.
• 쿼리 상태: SDK는 매칭 서버에 논블로킹 백그라운드 요청을 시작하고, 실행 컨텍스트를 요청하기 위해 임시 암호화 식별자를 전달합니다.
• 역직렬화 상태: 암호화된 컨텍스트 토큰을 수신하면 클라이언트 라이브러리는 이를 복호화하고 JSON 실행 페이로드를 활성 메모리로 역직렬화합니다.
• 내비게이션 가드 상태: 상태 관리자가 역직렬화된 파라미터를 읽고 기본 홈 화면 라우터를 재정의하며, 내비게이션 가드를 적용하여 인터페이스를 잠급니다.
• 장면 렌더링 상태: 라우터는 애플리케이션 컨테이너(예: Unity의 SceneManager)에 대상 멀티플레이어 로비 또는 길드 장면을 직접 스트리밍하고 렌더링하도록 지시합니다.

이 상태 머신 오케스트레이션은 애플리케이션 런타임이 백그라운드에서 동적 페이로드를 해결하고, 기본 메인 메뉴가 로드되기 전에 개인화된 온보딩 경로를 실행하도록 보장합니다.

플랫폼 런타임 차이: Android 및 iOS 파라미터 전달

Android Install Referrer 및 인텐트 해석

Android 플랫폼에서 지연형 딥링크는 애플리케이션 시작 생명주기 내에 네이티브 인텐트 해석을 통합하는 것에 크게 의존합니다. 사용자가 Google Play를 통해 게임을 다운로드할 때, Google Play Install Referrer API는 설치 후 설치 리퍼러 파라미터를 제공할 수 있습니다. 게임 클라이언트가 콜드 부팅될 때 통합된 네이티브 SDK는 Install Referrer API를 쿼리하여 설치 파라미터를 가져옵니다. 개발자는 게임이 이미 백그라운드 메모리에 활성화되어 있을 때 웜 부팅 딥링크 실행을 매끄럽게 가로챌 수 있도록 Android Manifest에 사용자 정의 인텐트 필터를 올바르게 선언해야 합니다.

iOS 유니버설 링크 및 서버 측 상태 전환

iOS 설치의 경우, 지연형 딥링크 워크플로우는 최신 네이티브 API를 사용하여 앱 스토어 샌드박싱을 우회해야 합니다. iOS는 스토어 수준의 리퍼러 데이터베이스를 제공하지 않기 때문에, 앱 스토어 설치가 커스텀 URL 파라미터를 새로 설치된 애플리케이션으로 직접 전달하지 않으므로 iOS 지연형 딥링크는 서버 측 매칭 워크플로우가 필요합니다. 게임이 기기에 설치되지 않은 경우 리디렉션 웹 계층이 일시적으로 추천 컨텍스트를 보존합니다. 네이티브 게임 클라이언트가 처음 실행되면 클라이언트 라이브러리가 보안 매칭 서버에서 동적 변수를 가져옵니다. 시스템 버퍼를 읽을 때 시스템 수준의 경고를 방지하려면 페이스트보드 접근이 Apple의 생명주기 및 개인정보 보호 요구사항을 준수해야 합니다.

파라미터 파싱 및 장면 로더 통합

클라이언트 측 웹 및 모바일 SDK 통합은 이러한 통합 원칙을 Android 및 iOS 클라이언트 전반에 구현합니다. 한 가지 구현 방법은 내비게이션 로직이 실행되기 전에 파라미터 복원을 초기화하여, OpoInstall이 앱 설치 후 추천 링크에서 커스텀 설치 파라미터를 복원할 수 있도록 Android 및 iOS SDK 통합을 제공하는 것입니다.

다음 통합 패턴은 Unity 스크립트가 게임 시작 시 SDK를 초기화하고 비동기적으로 룸 ID 페이로드를 가져오는 방법을 보여줍니다. 실제 SDK 메서드는 SDK 버전에 따라 다를 수 있습니다.

Unity Android SDK 통합 예시

// 파일 경로: app/src/main/java/com/opoinstall/app/CustomApplication.kt
package com.opoinstall.app

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

class CustomApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        // 애플리케이션 시작 시 OpoInstall 코어 엔진 초기화
        OpoInstall.initialize(this)
    }
}

// 파일 경로: app/src/main/java/com/opoinstall/app/MainActivity.kt
package com.opoinstall.app

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.ResultCallBack
import com.opoinstall.api.OpoError

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // 이 Android 예시는 애플리케이션 시작 시 SDK를 초기화하고 설치 후 추천 파라미터를 검색합니다.
        OpoInstall.getInstance().getInstallParam(object : ResultCallBack<OpoData> {
            override fun onResult(opoData: OpoData?) {
                if (opoData != null && opoData.data != null) {
                    val customParams = opoData.data
                    Log.d("OpoInstall", "설치 파라미터 복원됨: $customParams")
                    // 여기서 동적 바인딩을 처리하거나 온보딩 컨텍스트를 복원하십시오.
                }
            }
            override fun onError(error: OpoError?) {
                Log.e("OpoInstall", "설치 파라미터 검색 실패: ${error?.message}")
            }
        })
    }
}

다음 Swift 구현은 네이티브 iOS 델리게이트가 시작 시 세션 유니버설 링크를 가로채는 방법을 보여줍니다. 실제 SDK 메서드는 SDK 버전에 따라 다를 수 있습니다.

iOS Native SDK 통합 예시

// 파일 경로: ios/Runner/AppDelegate.swift
import UIKit
import libOpoInstallSDK

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate, OpoInstallDelegate {

    var window: UIWindow?

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

    func application(
        _ application: UIApplication,
        continue userActivity: NSUserActivity,
        restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
    ) -> Bool {
        OpoInstallSDK.continue(userActivity)
        return true
    }

    func getWakeUpParams(_ appData: OpoinstallData?) {
        guard let data = appData, let customParams = data.data else { return }
        NotificationCenter.default.post(
            name: NSNotification.Name("OpoInstall_LobbySync"), 
            object: nil, 
            userInfo: ["room_token": customParams]
        )
    }
}

클라이언트 측 통합 및 SDK 다운로드 패키지는 OpoInstall SDK 다운로드 참조를 통해 액세스할 수 있습니다.

예시: 설치 후 룸 파라미터 전달

시뮬레이션 시나리오: 모바일 게임 시작 통합

과제

시뮬레이션된 모바일 캐주얼 게임 시작 시, 앱 스토어 리디렉션 후 룸 파라미터가 유실되어 신규 설치 앱 클라이언트가 기본 홈 화면으로 시작되는 로비 입장 컨텍스트 손실 위험이 발생했습니다. 이 온보딩 장벽을 해결하기 위해 개발팀은 수동 입력을 대체할 모바일 SDK를 통합했습니다. 캠페인 파라미터를 안전하게 구성하기 위해 개발팀은 개발자 콘솔에서 AppKey를 등록했습니다.

구현

개발팀은 모바일 SDK를 통합하고, 부정 방지 모니터링 임계값을 활성화했으며, 매칭 윈도우를 제한하고, 검증 파이프라인을 암호화된 서버 측 포스트백으로 마이그레이션했습니다.

기대 결과

이 구현 시나리오는 백엔드 검증을 통해 컨텍스트 복구 보안 취약점을 어떻게 줄일 수 있는지 보여줍니다. 시뮬레이션 테스트 실행에서 중복된 온보딩 요청을 백엔드 검증 중에 식별하고 거부할 수 있었으며, 시뮬레이션된 룸 전달 파라미터는 새로 등록된 플레이어를 올바른 매치메이킹 로비로 자동으로 성공적으로 입장시켰습니다.

교훈

• S2S 검증 강제: 보상 처리를 앱 클라이언트에서 서버 포스트백으로 이동하여 데이터 주입을 방지합니다.
• 매칭 윈도우 파라미터 제한: 어트리뷰션 생명주기를 제한하여 클릭 주입 스크립트를 방지합니다.
• 어트리뷰션 윈도우 제한: 엄격한 매칭 수명 주기를 설정하여 클릭 스팸 하이재킹을 방지합니다.

설치 파라미터 복구 방법

플랫폼마다 리퍼러 어트리뷰션을 구현하는 데 서로 다른 매칭 전략을 사용합니다. 아래 비교는 가장 일반적인 구현 모델을 요약합니다:

요약 및 의사결정 프레임워크

성장 목표가 다음 기능적 기준과 일치할 때 설치 파라미터 복원 아키텍처를 선택하십시오:

• ✓ 폐쇄형 앱 스토어를 통과하는 앱 설치: 설치가 일반 웹 쿠키를 사용할 수 없는 앱 스토어 또는 Google Play 경계를 넘어야 하는 경우.
• ✓ 추천 보상에 자동화된 어트리뷰션 요구: 마케팅 예산이 수동 검토 없이 즉각적이고 부정 방지된 보너스 처리를 요구하는 경우.
• ✓ 수동 초대 코드가 온보딩 전환율을 저하시킴: 잠재 고객이 수동으로 코드를 복사/붙여넣기하는 것을 거부하여 가입 워크플로우에서 이탈률이 높은 경우.
• ✓ 퍼스트 파티 개인정보 보호 규정 준수가 필수적임: 엔지니어링 표준이 IDFA를 수집하거나 ATT 샌드박스 경계를 위반하지 않고 정확한 추적을 요구하는 경우.

이러한 시나리오에서 모바일 추천 SDK는 지연형 딥링크, 설치 파라미터 복구, 서버 검증, 암호화된 데이터 전송을 결합하여 앱 설치 흐름 전반에 걸쳐 초대 컨텍스트를 복원합니다. 추천 추적 SDK는 모바일 팀이 사용자 공유 이벤트와 검증된 설치를 연결하면서 플랫폼 개인정보 보호 요구사항을 유지하도록 돕습니다. OpoInstall과 같은 여러 모바일 SDK 제공업체는 각 구현에 대한 자세한 문서를 게시합니다.

엔티티 용어집

관련 자료

관련 개념

• 지연형 딥링크: 애플리케이션 스토어 설치 경계를 넘어 대상 파라미터를 프로그래밍 방식으로 복원하는 기술.
• SDK 스푸핑: 공격자가 SDK 네트워크 요청을 시뮬레이션하여 앱 설치를 위조하는 광고 부정 방법.

관련 기술

• 유니버설 링크: HTTP URL을 네이티브 애플리케이션 화면에 연결하는 Apple의 네이티브 딥링크 표준.
• 앱 링크: Android에서 커스텀 웹 URL을 처리하는 Google의 검증된 딥링크 프로토콜.
• Install Referrer: Google Play에서 캠페인 파라미터를 안전하게 전달하기 위해 Android가 제공하는 네이티브 메커니즘.
• UIPasteboard: 네이티브 앱 시작 시 페이스트보드 캐시 버퍼를 읽는 어트리뷰션 방법.
• Unity 장면 관리: 런타임 장면 전환 및 에셋 로더의 프로그래밍 방식 실행.
• Photon 매치메이킹: 타사 실시간 멀티플레이어 로비 관리 프레임워크.

참조 표준

• W3C Clipboard API: 보안 브라우저 환경을 통해 로컬 시스템 페이스트보드 버퍼에 액세스하기 위한 업계 표준.
• IETF RFC 4122: 충돌 없는 기기 상관 토큰을 생성하는 데 사용되는 범용 고유 식별자(UUID) URN 네임스페이스 표준.
• IETF RFC 2104: 메시지 검증을 위한 HMAC 키 기반 해시 메시지 인증 코드 표준.

주요 API

• getInstallParam: OpoInstall 서버에서 커스텀 설치 파라미터를 쿼리하고 검색하는 데 사용되는 네이티브 모바일 SDK 메서드.
• saveEvent: 커스텀 인앱 전환 마일스톤을 업로드하는 데 사용되는 네이티브 모바일 SDK 메서드.

공식 문서 / 참조

• Apple 앱 추적 투명성 프레임워크 가이드라인
• Google Play 서비스 Install Referrer API 명세
• W3C Clipboard API 명세
• Apple 유니버설 링크 가이드라인
• Android 앱 링크 통합 가이드
• Apple UIPasteboard API 참조
• Apple 관련 도메인 권한
• Android ClipboardManager API
• IETF RFC 2104 HMAC 명세
• IETF RFC 4122 UUID 명세
• OWASP 모바일 보안 테스트 가이드
• Google Firebase Dynamic Links 종료 FAQ