AppsFlyer OneLink를 이용한 DeepLinking

David·2025년 2월 7일

android appsflyer

[Android] 실무에서는 어떻게

목록 보기

10/11

🔎 딥링크에 대한 정의

웹에서는 url 를 통해 원하는 페이지로 연결되게 가능한데
모바일이 발전되면서 앱에서도 이러한 필요 사항이 생겼고

이에 딥링크라는 모바일 앱 내부의
특정 화면이나 기능으로 바로 이동할 수 있도록 설계되었습니다.

🌱 딥링크 종류와 발전

📌 Scheme URI를 이용한 딥링크

Scheme URI는 딥링크를 구현하는 가장 기본적인 방법 중 하나입니다.
Scheme URI는 앱에 고유한 ✌🏻커스텀 스키마✌를 사용하여
앱 내부의 특정 페이지로 이동할 수 있도록 합니다.
ex) myapp://product/123과 같은 형태

🧐 한계점

여기서 앱 스킴은 무조건 내가 사용하는 앱 스킴이 아닌
다른 어떤 스킴도 정의해서 사용할 수 있습니다.
즉 ✌🏻고유값이 아니라서✌🏻 다른 누구도 사용할 수 있다는 의미가 되는데요
이에 AppLink와 Universal Link가 등장 합니다.

📌 AppLink와 Universal Link

AppLink (안드로이드):

AppLink는 HTTP/HTTPS URL을 사용하여 앱 내부의 특정 콘텐츠로 연결합니다.
앱이 설치되어 있지 않을 경우, 웹 페이지로 리다이렉트될 수 있습니다.
intent-filter를 통해 앱이 특정 URL을 처리할 수 있도록 설정합니다.

Universal Link (iOS):

Universal Link도 HTTP/HTTPS URL을 사용하며, iOS에서 앱과 웹 사이트를 연결하는 방식입니다.
앱이 설치되어 있으면 앱으로, 설치되어 있지 않으면 웹 페이지로 이동합니다.

"핵심은 http/https 를 사용하여 고유의 URL를 할당받아
설치유무에 따라 적절한 페이지로 이동하게 만들어주는 것 입니다"

🧐 한계점
유저가 광고를 보고 혹 하여
해당 링크를 클릭하여 상품을 구매하려고 했을 때
링크를 클릭하여 설치했지만 해당 페이지가 나오지 않았을 때
사용자 경험이 저하됩니다🥲
이에 Deferred Deep Link가 등장합니다.

📌 Deferred Deep Link

Deferred Deep Link는 앱이 ✌🏻설치되어 있지 않은 상태에서도✌🏻
사용자가 앱을 설치한 후 특정 콘텐츠로 바로 이동할 수 있도록 하는 기술입니다.
이는 마케팅 캠페인에서 유용하게 사용됩니다.

🔎 OneLink 에 대한 이해

OneLink 란?

앱스플라이어 원링크를 사용하면 어트리뷰션, 리디렉션, 딥링킹 기능을 통해 캠페인용 링크를 생성하여
기기, 운영 체제, 채널, 플랫폼에 관계없이 소유 미디어 사용자를
앱 사용자로 전환하고 기존 사용자의 원활한 컨텍스트 여정을 통해 참여를 유도할 수 있습니다.
원링크 가이드

📌 링크에 대한 기본 구조

https://[subdomain].onelink.me/[template_id]/[campaign_id]?pid=[media_source]&[custom_params]

앱에서 다음과 같은 파라미터는 알고 있으면
커뮤니케이션에 도움이 됩니다.
(전체 원링크 파라미터 정보)

[subdomain]
: OneLink의 고유한 서브도메인
: 회사나 앱을 식별하는 용도 (예: myapp.onelink.me)
[template_id]
: OneLink 템플릿의 고유 ID (예: H5hv)
: 앱 내에서는 onelinkID 라고 사용하는 부분이기도 함
[pid]
: media source
: 트래픽 소스 식별자 (예: facebook, google, newsletter)
[c]
: campaign
: 캠페인 이름

💡 딥링크 관련 파라미터

[deep_link_value]
: 앱에 전달할 딥링크 값

📌 OneLink 만드는 방법

만드는 경로

https://hq1.appsflyer.com/onelink
appsFlyer 대시보드 > Engagement > OneLink Management 탭 > + New link 버튼 클릭

Attribution (어트리뷰션) 섹션:

Media source name
- 트래픽 소스를 구분하는 이름
Campaign name
- 마케팅 캠페인의 이름, 트래킹과 분석을 위한 구분자로 사용
- 예: summer_sale_2024, new_user_promotion

Retargeting (리타게팅) 섹션:

기존 사용자 재유입을 위한 캠페인인 경우 활성화
ON/OFF 토글로 간단히 설정

Link branding (링크 브랜딩) 섹션:

Domain
- OneLink 도메인 선택
- 회사/브랜드의 커스텀 도메인 사용 가능
- 예시처럼 petnow.onelink.me 형태
Template ID
- OneLink 템플릿의 고유 식별자
- 보통 짧은 문자열로 구성
- 예시의 'AWiE'처럼 설정
URL ID
- 개별 링크의 고유 식별자
- 예시의 '1sn86af7'처럼 자동 생성되거나 커스텀 설정 가능
- 링크 생성 전에만 수정 가능

이러한 설정들은 트래킹과 분석을 위한 구조화된 데이터를 제공하며, 마케팅 효과 측정에 활용됩니다.

URL ID는 OneLink의 최종 URL을 구성할 때 사용되는 고유 식별자입니다.

https://petnow.onelink.me/AWiE/1sn86af7
                        /[Template ID]/[URL ID]

Social media preview (소셜미디어 프리뷰)
- 두 가지 옵션 중 선택:
  1. Use OG tags from desktop web URL or store
    - 앱 스토어나 웹사이트의 기존 OG 태그 사용
    - 별도 설정 없이 자동으로 해당 정보 활용
  2. Create your own preview image and tags
    - 직접 프리뷰 이미지와 태그 생성
    - 제목, 설명, 이미지를 커스텀하게 설정 가능
Social app landing page (소셜 앱 랜딩 페이지)
- Create social app landing page 버튼 클릭시:
  - 소셜 미디어 앱(Instagram, Facebook 등)에서 링크 클릭 시 보여질 중간 페이지 생성
  - 앱 설치/실행 관련 안내 메시지
  - 브랜드 이미지나 로고
  - 사용자 행동 유도 버튼(CTA)

Deep linking
- Deep link value
  - 앱 내 특정 화면으로 이동할 때 사용할 값
  - 앱에서 라우팅 하는 방식으로 값을 넣어주면 됩니다.
- Additional deep link value
  - 추가적인 딥링크 파라미터
  - 예: "discount=10" 또는 "ref=event"
Redirection (앱 미설치 시)
- iOS:
  - Redirect to: App Store (기본값)
  - Custom product page: 특정 앱스토어 페이지 URL (선택사항)
- Android:
  - Redirect to: Google Play (기본값)
  - Custom store listing: 특정 플레이스토어 URL (선택사항)
Redirection (앱 설치 시)
- iOS: Universal links 사용 (자동 설정)
- Android:
  - Android App Links 사용 (기본)
  - URI scheme: 앱의 커스텀 스킴 (예: petnowio://)
Desktop 웹페이지 클릭 시
- Redirect to: 데스크톱에서 링크 클릭 시 이동할 웹 URL
- 예: https://petnow.io

실제 사용 예시:

Deep link value: "앱 navigation url 값"
Android URI scheme: "petnowio://"
Desktop redirect: "https://petnow.io"

📲 Android 에서 OneLink

🧑🏻‍🔧 초기 SDK 설정 가이드(permission, proguard)
🧑🏻‍🔧 Application 클래스에 설정할 부분
🧑🏻‍🔧 딥링크 관련 intent-filter 설정

아래에 첨부한 코드는
일부 설정을 보기 쉽게 올렸을 뿐
전체 설정이 아닙니다.

🚨 꼭 위 가이드대로 전체 셋팅을 하시길 바랍니다.

📌 AndroidMenifest.xml

위 가이드에서 제시한 intent-filter 설정
scheme, host, templeteId 를 intent-filter data로 설정한 부분

📌 Application.kt

key 설정 및 리스너 슬정
가이드에서는 DeepLink 및 ConversionData Listener 설정을 Application 클래스에서 함
해당 앱의 Root Activity(MainActivity) 가 실행되고 있는지 확인하기 위한 설정

📌 Launcher Activity

Launcher Activity 에서 OneLinkBehavior Inject
리스너 실행 부분을 위임
- 해당 딥링크 리스너를 끝날 떄 까지 기다리면 앱 실행이 늦어짐
- 이에 OneLinkBehavior 에 위임하고 앱을 바로 실행하는 구조로 변경

📌 OneLinkBehavior

해당 class는 앱 전반에 하나의 객체로 유지 > @Singleton
이벤트 전송을 위한 객체 > ampltiudeManager
실행중인 MainActivity의 HashCode > currentMainActivityHashCode
- 새로운 MainActivity가 실행될 때 비교하기 위한
이미 실행되고 있는 상태인지 딥링크로 실행됐는지 유무 > isAlreadyRunningMainActivity
현재 앱이 MultiWindow 환경으로 인해 destory 되고 다시 생성됐는지 판단 유무 > isDestroyedMainActivity
OneLink 관찰 > oneLiningData
- 발행된 이후로 MainActivity 에서 관찰하기 떄문에 replay = 1 로 설정

딥링크 리스너 부분

리스너를 코루틴으로 처리하기 위해 suspendCancellableCoroutine으로 wrapping
일정 시간 타임아웃을 설정하여 종료되게 설정
링크에서 필요한 데이터를 OneLinkData로 wrapping하여 resume
📌 DeepLinkResult > DeepLink > isDeferred 를 통해 현재 deffered Link인지 확인 가능
- 디퍼드 딥링크가 맞다면 > 링크 값만 넘기고 ✌🏻나머지 정보는 ConversionData에서 얻어야 함✌🏻

컨벤션 데이터 리스너 부분

isFirstLaunch 를 통해 앱이 최초 실행인지 알 수 있음
af_status 를 통해 해당 유저가 Organic, Non-organic 유저인지 판별 가능
디퍼드 딥링크 일 때 > 컨벤션 데이터를 통해서 필요한 정보를 Wrapping 하여 넘김

Activity <-> OneLinkBehavior 연동

startSubscribeForDeepLink
- Launcher Activity(DeepLink 시작 시) 연동 함수
- 앱의 시작을 늦추지 않기 위해 리스너 로직을 담당하는 로직
- 디퍼드 딥링크 일 경우 conversionData에서 데이터를 가져와서 값을 방출
- 딥링크 일 경우 바로 값을 방출
collectOneLink
- MainActivity 연동 함수
- 플립과 폴드와 같은 멀티 윈도우 환경이 실행될 때 onDestory > onCreate 재구성 시 값을 방출해서 화면이 다시 딥링킹 되는 것을 방지
- receiver에 링크 정보를 넘겨 MainActivity 에서 딥링킹 로직 실행

📌 OneLink 데이터 관찰

OneLink 를 클릭 후
데이터는 AppsFlyer 서버에 저장되고
앱을 실행하면서 sdk가 데이터를 리스너로 받는다.

✅ 앱이 설치된 유저

딥링크 리스너로 필요한 데이터를 모두 확인할 수 있다.

❌ 앱이 설치되지 않은 유저

이 때 딥링크 리스너로 확인할 수 있는 정보는 ✌🏻deep_link_value만✌🏻 확인 가능함
다른 정보가 더 필요하면 ConversionData를 활용해야 함

💡 ConversionData 란?

사용자가 앱에 도달한 채널을 설명

SDK를 사용하면 모든 앱 세션에 대해
이 데이터에 실시간으로 액세스할 수 있습니다.

데이터를 사용할 수 있을 때

반환된 데이터를 기반으로 앱의 로직과 흐름을 사용자 지정합니다.
추가 처리를 위해 서버로 데이터 전송

📌 af_status = Organic 일 떄 확인 가능한 데이터

단 3개(설치 시간, 처음 설치했는지, af_status)만 확인 가능

📌 af_status = Non-organic 일 때 확인 가능한 데이터

앱을 링크를 통해 설치한 유저
리스너를 통해 확인한 데이터 셋 { key - value }

{
  "redirect_response_data": null,
  "adgroup_id": null,
  "engmnt_source": null,
  "is_incentivized": false,
  "retargeting_conversion_type": "none",
  "orig_cost": 0.0,
  "deep_link_value": "petnowio://post/?postId=6z4K6-zyQlSLbURIyuoJvA",
  "is_first_launch": false,
  "af_click_lookback": "7d",
  "CB_preload_equal_priority_enabled": false,
  "af_cpi": null,
  "iscache": true,
  "click_time": "2025-01-24 02:35:27.332",
  "is_branded_link": null,
  "adset": null,
  "match_type": "gp_referrer",
  "campaign_id": null,
  "shortlink": "pnu6u2vl",
  "af_pmod_lookback_window": "30m",
  "af_dp": "petnowio://",
  "install_time": "2025-01-24 02:36:09.747",
  "agency": null,
  "media_source": "SMS",
  "af_siteid": null,
  "af_status": "Non-organic",
  "af_sub1": null,
  "cost_cents_USD": 0,
  "af_sub5": null,
  "af_sub4": null,
  "af_sub3": null,
  "af_sub2": null,
  "adset_id": null,
  "esp_name": null,
  "http_referrer": null,
  "campaign": "test_enter_sms",
  "is_universal_link": null,
  "is_retargeting": false,
  "adgroup": null
}

🧐 재설치 시나리오

만약 유저가 앱을 딥링크로 처음 설치한 유저가 아닐 경우 (Organic) 인데
✌🏻앱을 지웠고✌🏻
이후에 딥링크를 통해서 재설치를 한 경우에는 데이터를 어떻게 보낼 수 있을까?

위 케이스에 앱을 실행하면
af_status 는 Organic으로 찍히고 그러면 당연히 ConversionData 에서 원하는 데이터는 확인할 수 없으며
디퍼드 딥링크로 들어올테니 딥링크 리스너에도 역시 데이터를 확인할 수 없다.

📌 위 케이스에 데이터를 관찰하고 싶다면
OneLink 설정을 Retargeting 을 설정해야 한다.

그러면 ConversionData 에서

af_status는 Non-Oranic 으로 확인되고
"retargeting_conversion_type": "re-attribution"

으로 확인할 수 있다.

🧑🏻‍🔧 앱에서 Deferred Deep Link 테스트

AppsFlyer 에서 링크를 테스트 하는 방법도 있겠지만
저는 실제와 비슷한 환경에서 테스트 해보고 싶어서

다음처럼 테스트 했습니다.

앱이 우선 없는 상태로 만들고

OneLink 클릭(스토어 노출 됨)

앱을 빌드하여 설치 or 내부 테스트 트랙에 올려져있는 앱 설치

링크를 누르는 시점에 데이터가
AppsFlyer Server에 저장되고 받아오는 형식이기에
위와 같이 테스트하면 각 케이스별로 데이터를 확인할 수 있습니다 🥹

David

공부하는 개발자

이전 포스트

Compose Google Map

다음 포스트