Skip to content

딥링킹 문제 해결

이 페이지는 iOS에서 발생하는 일반적인 딥링킹 문제와 그 진단 방법을 다룹니다. 적합한 링크 유형 선택에 대한 도움말은 iOS 딥링킹 가이드를 참조하세요. 구현 세부 사항은 딥링킹을 참조하세요.

커스텀 스킴 딥링크(예: myapp://products/123)가 앱을 열지만 의도한 화면으로 이동하지 않는 경우:

  1. 스킴이 등록되어 있는지 확인하세요. Xcode에서 Info.plist의 CFBundleURLTypes 아래에 스킴이 나열되어 있는지 확인하세요.
  2. 핸들러를 확인하세요. application(_:open:options:)에 중단점을 설정하여 호출되는지 확인하고 url 매개변수를 검사하세요.
  3. 링크를 독립적으로 테스트하세요. 터미널에서 다음 명령어를 실행하여 Braze 외부에서 딥링크를 테스트하세요: 
    1

    xcrun simctl openurl booted "myapp://products/123"

    해당 링크가 여기서 작동하지 않는다면, 문제는 Braze가 아닌 앱의 URL 처리 방식에 있습니다.

  4. URL 형식을 확인하세요. Campaign에 포함된 URL이 핸들러가 예상하는 것과 일치하는지 확인하세요. 흔히 발생하는 실수로는 경로 구성 요소가 누락되거나 대소문자가 잘못된 경우가 있습니다.

유니버설 링크(예: https://myapp.com/products/123)가 앱 대신 Safari에서 열리는 경우:

Associated Domains 권한 확인

Xcode에서 앱 타겟 > Signing & Capabilities로 이동하여 Associated Domains 아래에 applinks:yourdomain.com이 나열되어 있는지 확인하세요.

AASA 파일 유효성 검사

Apple App Site Association(AASA) 파일은 다음 위치 중 하나에 호스팅되어야 합니다:

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

다음 사항을 확인하세요:

  • 파일이 유효한 인증서를 사용하여 HTTPS로 제공됩니다.
  • Content-Type이 application/json입니다.
  • 파일 크기가 128KB 미만입니다.
  • appID가 팀 ID 및 번들 ID와 일치합니다(예: ABCDE12345.com.example.myapp).
  • paths 또는 components 배열에 예상하는 URL 패턴이 포함되어 있습니다.

AASA를 검증하려면 Apple의 검색 검증 도구를 사용하거나 다음 명령어를 실행하세요:

1

swcutil dl -d yourdomain.com

AppDelegate 확인

AppDelegate에 application(_:continue:restorationHandler:)가 구현되어 있고 NSUserActivity를 올바르게 처리하는지 확인하세요:

1
2
3
4
5
6
7
8
9
10

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

Braze SDK 구성 확인

Braze에서 전송된 푸시 알림, 인앱 메시지 또는 Content Cards에서 유니버설 링크를 사용하는 경우 forwardUniversalLinks가 활성화되어 있는지 확인하세요:

1
2

let configuration = Braze.Configuration(apiKey: "<BRAZE_API_KEY>", endpoint: "<BRAZE_ENDPOINT>")
configuration.forwardUniversalLinks = true

길게 누르기 문제 확인

유니버설 링크를 길게 눌러 열기를 선택하면 iOS가 해당 도메인의 유니버설 링크 연결을 “해제”할 수 있습니다. 이는 iOS의 알려진 동작입니다. 재설정하려면 링크를 다시 길게 누르고 [앱 이름]에서 열기를 선택하세요.

이메일 링크는 이메일 서비스 공급자의 클릭 추적 시스템을 거치며, 이 시스템은 링크를 추적 도메인(예: https://click.yourdomain.com/...)으로 래핑합니다. 이메일에서 유니버설 링크가 작동하려면 기본 도메인뿐만 아니라 클릭 추적 도메인에도 AASA 파일을 구성해야 합니다.

클릭 추적 도메인 AASA 확인

  1. 이메일 서비스 공급자 설정(SendGrid, SparkPost 또는 Amazon SES)에서 클릭 추적 도메인을 확인하세요.
  2. https://your-click-tracking-domain/.well-known/apple-app-site-association에 AASA 파일을 호스팅하세요.
  3. 클릭 추적 도메인의 AASA 파일에 동일한 appID와 유효한 경로 패턴이 포함되어 있는지 확인하세요.

이메일 서비스 공급자별 설정 지침은 유니버설 링크 및 앱 링크를 참조하세요.

리디렉션 체인 확인

일부 이메일 서비스 공급자는 클릭 추적 URL에서 최종 URL로 리디렉션을 수행합니다. 유니버설 링크는 iOS가 초기 도메인(클릭 추적 도메인)을 앱과 연결된 것으로 인식할 때만 작동합니다. 리디렉션이 AASA 검사를 우회하면 링크가 Safari에서 열립니다.

테스트 방법:

  1. 자신에게 테스트 이메일을 보내세요.
  2. 링크를 길게 누르고 URL을 확인하세요 — 이것이 클릭 추적 URL입니다.
  3. 이 도메인에 유효한 AASA 파일이 있는지 확인하세요.

BrazeDelegate 확인

BrazeDelegate.braze(_:shouldOpenURL:)를 구현하는 경우, 채널 전반에 걸쳐 링크를 일관되게 처리하는지 확인하세요. context 매개변수에는 소스 채널이 포함됩니다. 특정 채널의 링크를 실수로 필터링할 수 있는 조건 로직이 있는지 확인하세요.

상세 로깅 활성화

상세 로깅을 활성화하고 문제를 재현하세요. Opening 로그 항목을 찾으세요:

1
2
3
4

Opening '<URL>':
- channel: <SOURCE_CHANNEL>
- useWebView: <true/false>
- isUniversalLink: <true/false>

작동하는 채널과 작동하지 않는 채널의 로그 출력을 비교하세요. useWebView 또는 isUniversalLink의 차이는 SDK가 링크를 다르게 해석하고 있음을 나타냅니다.

커스텀 디스플레이 델리게이트 확인

커스텀 인앱 메시지 디스플레이 델리게이트 또는 Content Card 클릭 핸들러를 사용하는 경우, 링크 이벤트가 처리를 위해 Braze SDK로 올바르게 전달되는지 확인하세요.

“앱 내에서 웹 URL 열기” 시 빈 페이지 또는 깨진 페이지가 표시되는 경우

앱 내에서 웹 URL 열기를 선택했을 때 빈 페이지 또는 깨진 WebView가 표시되는 경우:

  1. URL이 HTTPS를 사용하는지 확인하세요. SDK의 WebView는 ATS 호환 URL을 요구합니다. HTTP 링크는 오류 없이 조용히 실패합니다.
  2. Content Security Policy 헤더를 확인하세요. 대상 웹 페이지가 X-Frame-Options: DENY 또는 제한적인 Content-Security-Policy를 설정하면 WebView에서 렌더링이 차단됩니다.
  3. 커스텀 스킴으로의 리디렉션을 확인하세요. 웹 페이지가 커스텀 스킴(예: myapp://)으로 리디렉션되는 경우 WebView는 이를 처리할 수 없습니다.
  4. Safari에서 URL을 테스트하세요. 해당 기기의 Safari에서 페이지가 로드되지 않는다면, WebView에서도 로드되지 않습니다.

Braze에서 Branch 문제 해결

Branch를 링크 제공업체로 사용하는 경우:

BrazeDelegate가 Branch로 라우팅하는지 확인

BrazeDelegate가 Branch 링크를 가로채서 Branch SDK로 전달해야 합니다. 다음 사항을 확인하세요:

1
2
3
4
5
6
7
8
9

func braze(_ braze: Braze, shouldOpenURL context: Braze.URLContext) -> Bool {
  if let host = context.url.host, host.contains("app.link") {
    // Route to Branch SDK
    Branch.getInstance.handleDeepLink(context.url)
    return false
  }
  // Let Braze handle other links
  return true
}

shouldOpenURL이 Branch 링크에 대해 true를 반환하면, Braze가 Branch로 라우팅하지 않고 직접 처리합니다.

BrazeDelegate의 Branch 도메인이 실제 Branch 링크 도메인과 일치하는지 확인하세요. Branch는 여러 도메인 형식을 사용합니다:

  • yourapp.app.link (기본값)
  • yourapp-alternate.app.link (대체)
  • 커스텀 도메인 (Branch 대시보드에서 설정한 경우)

두 SDK의 로깅 모두 활성화

링크가 체인에서 끊어지는 지점을 진단하려면:

  1. Braze 상세 로깅을 활성화하세요. SDK가 링크를 수신했는지 확인하기 위해 Opening '<URL>': 항목을 찾으세요.
  2. Branch 테스트 모드를 활성화하세요. Branch 대시보드에서 링크 클릭 이벤트를 확인하세요.
  3. Braze가 링크를 기록했지만 Branch에서 클릭이 감지되지 않는다면, BrazeDelegate 라우팅 로직에 문제가 있을 가능성이 높습니다.

Branch 대시보드 구성 확인

Branch 대시보드에서 다음을 확인하세요:

  • 앱의 번들 ID와 팀 ID가 Xcode 프로젝트와 일치합니다.
  • Associated Domains에 Branch 링크 도메인이 포함되어 있습니다.
  • Branch AASA 파일이 유효합니다(Branch는 app.link 도메인에서 자동으로 호스팅합니다).

문제를 격리하기 위해 Braze 외부에서 Branch 링크를 테스트하세요:

  1. 기기에서 Safari로 Branch 링크를 여세요. 앱이 열리지 않는다면, 문제는 Braze가 아닌 Branch 또는 AASA 구성에 있습니다.
  2. Branch 링크를 메모 앱에 붙여넣고 탭하세요. 유니버설 링크는 Safari 주소창보다 메모 앱에서 더 안정적으로 작동합니다.

일반적인 디버깅 팁

상세 로깅 사용

상세 로깅을 활성화하여 SDK가 링크를 처리하는 방식을 정확히 확인하세요. 확인해야 할 주요 항목:

이러한 로그를 읽는 방법에 대한 자세한 내용은 상세 로그 읽기를 참조하세요.

Braze를 통해 테스트하기 전에, 딥링크 또는 유니버설 링크가 단독으로 작동하는지 확인하세요:

  • 커스텀 스킴: 터미널에서 xcrun simctl openurl booted "myapp://path"를 실행하세요.
  • 유니버설 링크: 실제 기기의 메모 앱에 URL을 붙여넣고 탭하세요. Safari 주소창에서 테스트하지 마세요. iOS는 입력된 URL과 탭한 링크를 다르게 처리합니다.
  • Branch 링크: 기기의 메모 앱에서 Branch 링크를 여세요.

실제 기기에서 테스트

유니버설 링크는 iOS 시뮬레이터에서 제한적으로 지원됩니다. 정확한 결과를 위해 항상 실제 기기에서 테스트하세요. 시뮬레이터에서 테스트해야 하는 경우, Copy Bundle Resources 빌드 단계에 .entitlements 파일을 추가하세요.
New Stuff!