개요

Singular 트래킹 링크에 대해 딥 링크와 디퍼드 딥 링크를 구현하여 사용자가 캠페인에서 앱 내 특정 화면으로 자연스럽게 이동할 수 있도록 하세요.

딥 링크는 앱 내부의 특정 콘텐츠를 여는 클릭 가능한 링크입니다. 지원해야 하는 두 가지 시나리오가 있습니다:

• 딥 링크 (다이렉트): 사용자가 이미 앱을 설치한 경우입니다. 사용자가 Singular Link를 탭하면 앱이 바로 해당 콘텐츠에서 열립니다.
• 디퍼드 딥 링크 (DDL): 사용자가 아직 앱을 설치하지 않은 경우입니다. 사용자가 링크를 탭하고 스토어에서 설치한 뒤, 첫 실행 시에도 앱이 의도한 콘텐츠로 라우팅합니다.

SDK 연동을 사용하면 Singular가 이 대부분을 자동으로 처리합니다. server-to-server(S2S) 연동에서는 기기에 SDK가 없으므로, 여러분의 팀이 두 가지 추가 작업을 담당해야 합니다: 앱이 수신한 딥 링크를 Singular로 전달하는 것과, Singular가 반환하는 디퍼드 딥 링크를 읽어 사용자를 라우팅하는 것입니다. 두 작업 모두 SESSION 엔드포인트를 통해 이루어집니다:

GET https://s2s.singular.net/api/v1/launch

리소스: Deep Linking FAQ | Singular Links FAQ

세 가지 설정 한눈에 보기

1단계: 앱 레벨 설정

딥 링크가 작동하려면, 링크를 탭했을 때 브라우저 대신 앱이 열리도록 Singular Links가 OS에 의해 iOS Universal Links 및 Android App Links로 인식되어야 합니다. 기존의 URI 앱 스킴은 폴백으로 지원됩니다.

상세한 플랫폼별 단계는 표준 설정 가이드를 따른 다음, 아래 각 항목이 완료되었는지 확인하세요. 상세 단계는 Singular Links Prerequisites 및 How to Configure Deep Links 에 나와 있습니다. 여기에 있는 체크리스트는 필요한 순서와 팀에서 가장 흔히 놓치는 지점을 알려줍니다.

설정 체크리스트:

1. 링크 서브도메인 추가 : Attribution > Manage Links > Manage Link Domains 에서 추가합니다(예: yourbrand.sng.link ). 이것이 Singular Links가 사용하는 호스트입니다.
2. iOS — Universal Links: applinks:yourbrand.sng.link 에 대해 Associated Domains capability를 활성화한 다음, Apple Developer Portal에서 App Prefix / Team ID를 복사하여 Settings > Apps > [iOS app] > Show Advanced Settings 에 입력합니다. 선택적으로 Xcode에서 URL Type으로 앱 스킴 폴백을 등록할 수 있습니다.
3. Android — App Links: SHA-256 서명 지문을 생성하고(프로덕션의 경우 Play Console, 디버그의 경우 keytool ), AndroidManifest.xml 에 Singular 도메인에 대한 autoVerify 인텐트 필터를 추가한 다음, 지문을 Settings > Apps > [Android app] > Show Advanced Settings > App Links SHA256 fingerprints 에 붙여넣습니다.
4. 딥 링크 정의 : Attribution > Manage Links > Create Link 에서 정의합니다(아래 필드 매핑 참조).

Manage Links 리디렉션 필드 매핑하기

링크를 생성할 때, 세 개의 리디렉션 필드가 이후 API에서 사용되는 세 가지 딥 링크 개념에 직접 매핑됩니다:

개발자 인계: 엔지니어링 팀은 플랫폼별 딥 링크 스킴과 목적지 URL 목록을 제공해야 합니다(예: myapp://autumnfashion ).

2단계: SESSION (인바운드) — 딥 링크를 Singular로 전송

앱이 Singular Link를 통해 열리면, 전체 오프닝 URL을 캡처하여 SESSION 요청의 openuri 파라미터(URL 인코딩)로 Singular에 전송합니다. 이것이 Singular가 세션을 해당 링크에 어트리뷰션하고 딥 링크 결과를 보고하는 방식입니다. Singular Links를 사용할 때 필수입니다.

URL에 실려 전달되는 Singular Link 파라미터

앱에서 오프닝 URL 캡처하기

앱에는 오프닝 URL을 수신하여 SESSION 요청에 포함하도록 서버로 전달하는 핸들러 코드가 필요합니다.

iOS (Swift):

// Custom scheme / direct opens
func scene(_ scene: UIScene,
           openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else { return }
    SessionReporter.report(openURL: url.absoluteString)
}

// Universal Links arrive via:
func scene(_ scene: UIScene,
           continue userActivity: NSUserActivity) {
    if let url = userActivity.webpageURL {
        SessionReporter.report(openURL: url.absoluteString)
    }
}

Android (Kotlin):

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    intent?.data?.let { uri ->
        SessionReporter.report(uri.toString())
    }
}

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    intent?.data?.let { SessionReporter.report(it.toString()) }
}

openuri를 포함하여 SESSION 요청 전송하기

서버에서 캡처한 URL(URL 인코딩)을 openuri 로 포함합니다:

curl -G https://s2s.singular.net/api/v1/launch \
  --data-urlencode "a=<SDK key>" \
  --data-urlencode "p=Android" \
  --data-urlencode "i=com.yourcompany.app" \
  --data-urlencode "aifa=<GAID>" \
  --data-urlencode "n=YourAppName" \
  --data-urlencode "openuri=myapp://home/page?queryparam1=value1"

숏 링크 리졸루션

사용자가 단축된 Singular Link를 연 경우, singular_link_resolve_required=true 도 함께 전송하세요. Singular가 확장된 롱 링크를 반환하므로 딥 링크와 패스스루 값을 파싱할 수 있습니다.

응답 예시:

{
  "status": "ok",
  "resolved_singular_link": "https://myapp.sng.link/A59c0/nha7?_dl=myapp%3A%2F%2Fdeeplink&_ddl=myapp%3A%2F%2Fdeferred-deeplink&_p=passthroughvalue"
}

다이내믹 패스스루 파라미터

조직에서 링크에 대해 다이내믹 패스스루를 설정한 경우, 딥 링크 URL에는 콘텐츠 라우팅을 위한 URL 인코딩된 JSON 문자열 또는 비정형 문자열이 담긴 _p 파라미터가 포함됩니다. Dynamic Passthrough Parameters 를 참조하세요.

참조: SESSION Endpoint API Reference (Deep Linking Parameters).

3단계: SESSION (아웃바운드) — 디퍼드 딥 링크를 앱에 전달

링크를 탭한 후 앱을 설치하는 사용자의 경우, 설치 후 첫 세션의 SESSION 응답에서 Singular가 디퍼드 딥 링크를 반환합니다. 여러분의 서버는 사용자를 라우팅할 수 있도록 그 값을 앱에 다시 전달해야 합니다.

첫 세션에서 DDL 요청하기

설치 후 첫 SESSION 요청에 다음 두 개의 파라미터를 추가하세요:

SESSION 요청 예시(install + DDL enabled):

curl -G https://s2s.singular.net/api/v1/launch \
  --data-urlencode "a=<SDK key>" \
  --data-urlencode "p=Android" \
  --data-urlencode "i=com.yourcompany.app" \
  --data-urlencode "aifa=<GAID>" \
  --data-urlencode "n=YourAppName" \
  --data-urlencode "install=true" \
  --data-urlencode "ddl_enabled=true"

응답을 읽고 앱에 전달하기

설치가 디퍼드 딥 링크를 포함한 트래킹 링크에서 발생한 경우, Singular는 다음을 반환합니다:

SESSION 응답 예시:

{
  "deferred_deeplink": "myapp://deferred-deeplink",
  "status": "ok",
  "deferred_passthrough": "passthroughvalue"
}

테스트 & 검증

• 디퍼드 딥 링크: 앱이 없는 기기에서 링크를 탭하고 스토어에 도달하는지 확인하세요. 설치 후 열면 앱이 의도한 콘텐츠를 표시해야 합니다.
• 다이렉트 딥 링크: 앱이 설치된 상태에서 링크를 탭하고 앱이 의도한 콘텐츠에서 바로 열리는지 확인하세요.
• SESSION 순서: 어떤 이벤트보다 먼저 하나의 SESSION이 수신되는지, 그리고 SESSION 응답이 파싱되어 클라이언트로 전달되는지 확인하세요(디퍼드 딥 링크에 매우 중요).
• openuri 채움: 타임아웃 윈도우와 관계없이 딥 링크 오픈 시 openuri 가 설정된 SESSION이 전송되는지 확인하세요.

테스트 가이드: Test Your Integration | Test a Tracking Link