딥링킹 & 디퍼드 딥링킹(DDL) 문제 해결 가이드 - FAQ

가능한 원인:

• 딥링크 핸들러가 앱에 완전히 구현되지 않았습니다
• 앱이 Singular SDK에서 확인된 딥링크를 읽지 않고 있습니다
• DDL 사전 요구사항이 완전히 충족되지 않았습니다

확인할 사항:

1. 딥링크를 (Singular 링크를 거치지 않고) 직접 테스트합니다.
2. SingularLinkHandler 가 구현되어 있고 다음을 올바르게 읽고 있는지 확인합니다:
   • getDeeplink()
   • isDeferred()
   • getPassthrough()
3. DDL이 활성화되어 있는지 확인합니다 ( should_index_ddl = true ).

직접 테스트했을 때는 딥링크가 작동하지만 Singular 링크를 통해서는 작동하지 않는 경우, 문제는 거의 항상 링크 자체가 아니라 앱의 내비게이션 로직에 있습니다.

iOS(Universal Links)의 경우: 이는 일반적으로 Universal Link 구성이 불완전함을 의미합니다. 다음을 확인하세요:

• Team ID와 iOS App Scheme이 Singular에 올바르게 설정되어 있습니다
• Associated Domains가 Xcode에 추가되어 있습니다
• AASA 파일이 존재하고 올바른 링크 ID를 포함하고 있습니다

개발/QA 빌드를 위한 팁: 개발 또는 QA 빌드에서 테스트하는 경우, 기기에 아직 최신 AASA 파일이 없을 수 있습니다. 기기를 재부팅한 후 앱을 재설치해 보세요.

Android의 경우: 이는 일반적으로 잘못 구성된 인텐트 필터를 가리킵니다. 다음을 확인하세요:

• App Links SHA256 지문이 올바르게 설정되어 있습니다(App Links를 사용하는 경우)
• assetlinks.json 이 Singular 도메인에서 접근 가능합니다
• 인텐트 필터가 Singular Apps 페이지에 구성된 것과 일치합니다

위의 모든 사항이 확인되었는데도 문제가 계속되면, 문제는 딥링크 핸들러 로직에 있을 가능성이 높습니다.

일반적인 오류: "주소가 유효하지 않아 Safari가 페이지를 열 수 없습니다."

이런 일이 발생하는 이유:

• Safari는 신규 사용자에 대한 특정 Universal Links 처리에 알려진 제한사항이 있습니다
• _force_redirect=1 이 링크에 있습니다

이것은 예상된 동작이며 , 흐름은 다음과 같이 계속되어야 합니다: 사용자가 오류를 봄 → 확인을 탭함 → App Store를 열도록 안내됨.

가능한 원인: 패스스루 파라미터( _p )가 제대로 추가되지 않았거나 URL 인코딩되지 않았습니다.

모범 사례:

• 링크에 추가하기 전에 항상 JSON 값을 URL 인코딩하세요
• 다음에서 패스스루 데이터를 읽으세요: singularLinkParams.passthrough

패스스루 데이터는 딥링크와 디퍼드 딥링크 모두 에서 사용할 수 있으므로, 누락된 경우 문제는 거의 항상 인코딩 또는 검색에 있습니다.

이런 일이 발생하는 이유: Singular 링크가 딥링크로 생성되면, 앱이 설치되어 있는 경우 항상 앱을 열려고 시도합니다. 이는 OS 수준에서 제어됩니다:

• iOS: AASA 파일에 의해 관리됨
• Android: SHA256 인증서 연결에 의해 관리됨

나중에 이를 재정의할 방법은 없습니다. 항상 사용자를 스토어로 보내는 링크를 원한다면, 처음부터 딥링크 없이 생성해야 합니다.

근본 원인: 기기에서 Apple의 iCloud Private Relay가 활성화되어 있습니다.

DDL이 손상되는 이유: Private Relay는 클릭과 설치 사이에 IP 주소를 변경하므로, 클릭 IP와 설치 IP가 일치하지 않습니다 — 이는 확률적 어트리뷰션을 손상시킵니다.

권장 사항:

• 테스트하는 동안 iCloud Private Relay를 비활성화하세요
• 대신 Chrome 또는 다른 비-Safari 브라우저를 사용하여 테스트하세요

이런 일이 발생하는 이유: 링크가 딥링크로 구성되어 있으며, 앱이 설치되어 있을 때는 항상 랜딩 페이지보다 우선합니다.

핵심 규칙: 앱 + 딥링크는 항상 랜딩 페이지보다 우선합니다. 소셜 랜딩 페이지는 앱을 실제로 열 수 없는 경우에만 나타납니다.

가능한 원인: 테스트에 사용하는 트래킹 링크가 이중 URL 인코딩되어 있어 기기나 Singular가 확인할 수 없습니다.

이런 일이 발생하는 이유: 딥링크 파라미터(예: _dl 또는 _p )가 포함된 Singular Link가 특정 환경(예: Slack, 이메일 클라이언트 또는 메시징 도구)에서 복사되면 URL이 두 번 인코딩될 수 있습니다. 예를 들어:

• 올바름(단일 인코딩): https://yourapp.sng.link/Xxxxx/yyyy?_dl=myapp%3A%2F%2Fstory&_p=%7B%22story_id%22%3A%22BananaStory%22%7D
• 유효하지 않음(이중 인코딩): https%3A%2F%2Fyourapp.sng.link%2FXxxxx%2Fyyyy%3F_dl%3Dmyapp%3A%2F%2Fstory%26_p%3D%7B%22story_id%22%3A%22BananaStory%22%7D

이중 인코딩된 링크는 제대로 리디렉션되지 않으며, 그 결과 설치 또는 클릭이 Singular의 어트리뷰션 로그에 나타나지 않을 수 있습니다.

확인할 사항:

1. 항상 Singular Manage Links 페이지에서 직접 트래킹 링크를 복사하세요 — URL을 다시 인코딩했을 수 있는 Slack 메시지나 다른 도구에서 복사하지 마세요.
2. 링크가 https:// 로 시작하는지 확인하세요( https%3A%2F%2F 가 아님). URL의 맨 처음에 퍼센트 인코딩된 문자가 보이면 전체 링크가 이중 인코딩된 것입니다.
3. URL 디코더 도구(예: urldecoder.org )를 사용하여 링크가 유효한 Singular Link 형식으로 디코딩되는지 확인하세요.
4. 링크를 한 번 디코딩하고 그 결과 URL을 테스트에 사용하세요.

문제: Samsung Internet 브라우저에서 Singular 링크를 클릭하는 사용자는 앱이 이미 설치되어 있고 링크가 올바르게 구성되어 있어도 Google Play Store로 리디렉션될 수 있습니다.

확인된 사항:

• Google Chrome: 링크가 예상대로 앱을 엽니다
• Samsung Internet: 동일한 링크가 대신 Play Store로 리디렉션됩니다

이는 링크를 Samsung Internet에서 직접 열든, 웹 페이지에 삽입하여 거기서 클릭하든 발생할 수 있습니다.

근본 원인: Samsung Internet에는 기본적으로 앱이 외부에서 열리는 것을 차단하는 내장 개인정보 설정이 있습니다.

• 활성화된 경우: 브라우저가 딥링크를 차단하고 Play Store로 폴백합니다
• 비활성화된 경우: 링크가 앱을 올바르게 열어 Chrome의 동작과 일치합니다

이것이 Singular 구성 문제가 아니라 브라우저 설정 문제 임을 확인했습니다 — Android App Links와 SHA-256 지문이 올바르게 설정되어 있으며, 이 설정을 끄면 링크 동작이 모든 곳에서 일관됩니다.

이것이 의미하는 바: 일부 Samsung 사용자는 개별 브라우저 개인정보 설정에 따라 앱이 설치되어 있어도 Play Store에 도착할 수 있습니다. 이는 저희 측에서 프로그래밍 방식으로 제어할 수 없습니다.

영향을 받는 사용자를 안내하려면: Samsung Internet이 기본적으로 앱 열기 링크를 차단할 수 있으며, Samsung Internet의 개인정보 설정에서 "외부 앱 열기"(또는 유사한 항목)를 활성화하면 예상되는 인앱 경험이 복원된다고 알려줄 수 있습니다.

이런 일이 발생하는 이유: 사용자가 특정 소셜 미디어 인앱 브라우저 내부에서 Singular Link를 클릭하면, 브라우저가 표준 iOS Universal Links 또는 Android App Links를 차단할 수 있습니다. 그 결과 앱은 정상적으로 열리지만 딥링크가 앱에 전달되지 않아, 사용자가 의도한 목적지 대신 기본 홈 화면에 도착하게 됩니다.

이를 해결하기 위해 Singular는 소셜 랜딩 페이지 를 제공합니다. 이는 딥링크를 보존하고 사용자를 올바른 인앱 목적지로 안정적으로 라우팅하는 데 도움이 되는 중간 랜딩 페이지입니다.

어떤 플랫폼이 지원되나요?

소셜 랜딩 페이지는 다음을 지원합니다:

• iOS
• Android(Facebook, Facebook Messenger, Facebook Messenger Lite, Instagram 인앱 브라우저)
• 파트너 링크, 포함:
  • Facebook Web
  • TikTok Ads Web
  • X (Twitter) Web
  • Snapchat Web

소셜 랜딩 페이지를 어떻게 활성화하나요?

Singular Link를 생성하거나 편집할 때, Social Link Settings 아래에서 Landing Page 를 활성화하세요.

이 옵션은 다음에 사용할 수 있습니다:

• Custom Source 링크
• Mobile Web-to-App 링크
• 파트너 링크

소셜 랜딩 페이지를 언제 사용해야 하나요?

지원되는 소셜 플랫폼을 통해 웹-투-앱 캠페인을 실행할 때마다 소셜 랜딩 페이지를 활성화하세요. 이는 사용자가 앱의 홈 화면이 아니라 의도한 인앱 콘텐츠로 안내되도록 하여, 딥링킹 경험을 개선하고 소셜 미디어 인앱 브라우저로 인한 실패한 딥링크를 줄이는 데 도움이 됩니다.