딥 링킹

​

개요

• 딥 링크 유형과 각각의 사용 시기
• Android와 iOS의 플랫폼 설정
• OneSignal SDK를 사용한 앱에서의 딥 링크 처리
• 푸시, 이메일, 인앱 메시지의 채널별 동작

​

사전 요구 사항

• 앱이 구성된 OneSignal 계정
• 모바일 앱에 설치된 OneSignal SDK
• Universal Links 또는 App Links를 위해 HTTPS로 호스팅된 본인 소유의 도메인
• 앱의 소스 코드 및 빌드 구성에 대한 액세스 권한(iOS는 Xcode, Android는 Android Studio)

​

딥 링크 유형

​

Android 설정 (App Links)

​

인텐트 필터 구성

<activity android:name=".DeepLinkActivity" android:exported="true">
  <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="https" android:host="yourdomain.com" />
  </intent-filter>
</activity>

​

수신 인텐트 처리

Intent appLinkIntent = getIntent();
String appLinkAction = appLinkIntent.getAction();
Uri appLinkData = appLinkIntent.getData();

​

Digital Asset Links 파일 호스팅

https://yourdomain.com/.well-known/assetlinks.json

​

iOS 설정 (Universal Links)

​

Associated Domains 활성화

1. Xcode에서 타겟 선택 → Signing & Capabilities → Associated Domains 추가
2. 도메인 추가: applinks:yourdomain.com

​

앱에서 Universal Link 처리

func application(_ application: UIApplication,
                 continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
  guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
        let url = userActivity.webpageURL else {
    return false
  }
  // Route to the correct screen based on the URL path
  return true
}

​

Apple App Site Association 파일 호스팅

https://yourdomain.com/.well-known/apple-app-site-association

{
  "applinks": {
    "apps": [],
    "details": [{
      "appID": "TEAMID.com.example.app",
      "paths": ["/path/*", "/another-path"]
    }]
  }
}

​

iOS 실행 URL 동작

1. API 페이로드에서 url 대신 data 사용하고 푸시 알림 클릭 리스너에서 딥 링크 처리
2. Info.plist에 Boolean 값 YES로 OneSignal_suppress_launch_urls를 추가하여 실행 URL 억제하고, 클릭 리스너에서 모든 내비게이션 처리

​

OneSignal SDK로 딥 링크 처리

​

푸시 알림 클릭 리스너

OneSignal.Notifications.addClickListener { event ->
  val url = event.notification.launchURL
  val data = event.notification.additionalData
  // Route to the correct screen based on url or data
}

​

인앱 메시지 클릭 리스너

OneSignal.InAppMessages.addClickListener { event ->
  val actionId = event.result.actionId
  // Route based on the action ID (your deep link URI)
}

​

푸시 알림

​

플랫폼 동작

• Android: App Links를 통해 일치하는 Activity를 직접 엽니다
• iOS: Safari를 열고 그 다음 앱을 엽니다(실행 URL을 억제하고 클릭 리스너에서 내비게이션을 처리하지 않는 경우)

​

이메일

​

이메일에서 딥 링크 활성화

• 대시보드: 이메일 편집기에서 Track link clicks 체크 해제
• API: disable_email_click_tracking: true 설정
• 링크별: Liquid 필터 {{ 'https://yourdomain.com/path' | do_not_track_link }}를 사용하여 다른 링크의 추적은 유지하면서 개별 링크의 추적 비활성화

​

이메일 딥 링크 동작

​

인앱 메시지

​

드래그 앤 드롭 편집기

1. 버튼 또는 클릭 가능한 요소 추가
2. 클릭 액션을 Custom Action ID로 설정
3. Action Name으로 딥 링크 URI 입력 (예: https://yourdomain.com/promo 또는 myapp://promo)

​

HTML 편집기

​

클릭 처리

​

딥 링크 테스트

​

Android

adb shell am start -a android.intent.action.VIEW \
  -d "https://yourdomain.com/path" \
  com.your.package

curl -I https://yourdomain.com/.well-known/assetlinks.json

​

iOS

1. 메모 앱에 링크 붙여넣기
2. 링크를 길게 눌러 “[앱]에서 열기” 옵션이 나타나는지 확인
3. 링크를 탭하여 앱이 열리는지 확인

​

OneSignal 테스트 메시지

1. OneSignal 대시보드에서 딥 링크 URL을 실행 URL 또는 추가 데이터로 설정하여 테스트 푸시 전송
2. 알림이 앱에서 올바른 화면을 여는지 확인
3. 클릭 리스너 로그를 확인하여 URL 또는 데이터가 수신되었는지 확인

​

문제 해결

​

iOS 딥 링크가 앱 대신 Safari를 열 때

• AASA 파일이 올바르게 호스팅되지 않음 — https://yourdomain.com/.well-known/apple-app-site-association에 Content-Type: application/json으로 리다이렉트 없이 있는지 확인
• Associated Domains 미구성 — Xcode → Signing & Capabilities → Associated Domains에 applinks:yourdomain.com이 포함되어 있는지 확인
• 실행 URL 동작 — OneSignal의 iOS SDK는 url 속성에 openURL을 사용하여 브라우저 우선 동작을 트리거합니다. 대신 data + 클릭 리스너를 사용하거나 실행 URL을 억제하세요
• Safari에서 테스트 — Universal Links는 Safari 주소창에서 활성화되지 않습니다. 메모, 메일 또는 다른 앱에서 테스트하세요.

​

Android 딥 링크가 브라우저를 열 때

• autoVerify 누락 — 인텐트 필터에 android:autoVerify="true"가 포함되어 있는지 확인
• assetlinks.json 미발견 — 파일이 https://yourdomain.com/.well-known/assetlinks.json에 있고 HTTP 200을 반환하는지 확인
• SHA256 지문 불일치 — assetlinks.json의 지문은 앱 서명 인증서와 일치해야 합니다. 디버그 빌드와 릴리스 빌드는 다른 인증서를 사용합니다.

​

딥 링크가 푸시에서는 작동하지만 이메일에서는 작동하지 않을 때

​

딥 링크는 수신되지만 앱이 이동하지 않을 때

• 클릭 리스너가 앱 생명주기 초반에 등록되었는지 확인 (예: Application.onCreate() 또는 AppDelegate.didFinishLaunchingWithOptions)
• URL 또는 액션 ID가 라우팅 로직이 예상하는 것과 일치하는지 확인
• iOS에서 실행 URL을 억제하지 않고 url에 의존하지 않는지 확인——리스너가 실행되기 전에 브라우저가 링크를 소비할 수 있습니다

​

자주 묻는 질문

​

앱이 설치되지 않은 경우 어떻게 됩니까?

​

딥 링킹에 실행 URL과 추가 데이터 중 어느 것을 사용해야 합니까?

​

사용자 데이터로 딥 링크를 개인화할 수 있습니까?

​

커스텀 URI 스킴으로 딥 링크를 사용할 수 있습니까?

​

OneSignal Journeys에서 딥 링크가 작동합니까?