Cordova SDK - 딥 링크 지원

문서

딥링킹 지원 추가

딥링크는사용자를 앱 내의 특정 콘텐츠로 연결합니다. 사용자가 앱이 설치된 기기에서 딥링크를 탭하면 앱이 제품 페이지나 특정 경험 등 의도한 콘텐츠로 바로 연결됩니다.

Singular 추적 링크는 표준 딥링킹(설치된 앱의 경우)과 디퍼드 딥링킹(신규 설치의 경우)을 모두 지원합니다. 자세한 내용은 딥링킹 FAQSingular 링크 FAQ를 참조하세요.


요구 사항

전제 조건

앱에 딥링킹을 사용하려면 Singular 링크 사전 요구 사항을완료하세요.

참고:

  • 이 문서에서는 귀하의 조직이 Singular의 추적 링크 기술인 Singular 링크를사용하고 있다고 가정합니다. 기존 고객은 레거시 트래킹 링크를 사용하고 있을 수 있습니다.
  • 앱의 딥링크 대상은 Singular의 페이지에서 구성해야 합니다( 어트리뷰션 추적을 위한 앱 구성하기 참조).

Singular 링크 핸들러 구현

Singular링크 핸들러는 앱이 열릴 때 Singular 추적 링크에서 딥링크, 디퍼드 딥링크 및 패스스루 파라미터를 검색하는 콜백 메커니즘을 제공합니다.

사용 가능한 파라미터

  • 딥링크(_dl): 링크를 클릭하는 사용자의 앱 내 목적지 URL입니다.
  • 디퍼드 딥링크(_ddl): 링크를 클릭한 후 앱을 설치하는 사용자를 위한 목적지 URL
  • 패스스루(_p): 추가 컨텍스트를 위해 추적 링크를 통해 전달되는 사용자 지정 데이터

플랫폼 구성

어트리뷰션 추적 및 탐색을 위해 딥링크 데이터를 Singular SDK에 전달하도록 네이티브 플랫폼 코드를 구성합니다.

안드로이드 구성

메인 액티비티 업데이트

MainActivity 파일을 수정하여 Intent 오브젝트를 Singular SDK에 전달함으로써 Singular SDK가 실행 관련 데이터를 처리하고 딥링크를 처리할 수 있도록 합니다.

Java
import singular_cordova_sdk.SingularCordovaSdk;

@Override
public void onNewIntent(Intent intent) {
    SingularCordovaSdk.handleNewIntent(intent);
}

Intent 개체에는 앱이 실행된 방법과 이유에 대한 정보가 포함되어 있으며, Singular는 이를 어트리뷰션 추적 및 딥링크 탐색에 사용합니다.

위치: 일반적으로 platforms/android/app/src/main/java/[your-package]/MainActivity.java에 있는 기본 활동 파일에 이 코드를 추가합니다.


iOS 구성

앱 델리게이트 업데이트

앱디렉티브 파일에서 launchOptionsuserActivity 객체를 Singular SDK에 전달하여 실행 관련 데이터를 처리하고 딥링크를 처리할 수 있도록 설정합니다.

Swift
import UIKit
import SingularCordovaSdk

class AppDelegate: UIResponder, UIApplicationDelegate {
    
    var window: UIWindow?
    var viewController: MainViewController?
    
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        // Initialize window
        window = UIWindow(frame: UIScreen.main.bounds)
        
        // Configure view controller
        viewController = MainViewController()
        window?.rootViewController = viewController
        
        // Initialize Singular SDK with launch options
        SingularCordovaSdk.setLaunchOptions(launchOptions)
        
        // Make window visible
        window?.makeKeyAndVisible()
        
        return true
    }
    
    func application(
        _ application: UIApplication,
        continue userActivity: NSUserActivity,
        restorationHandler: @escaping ([Any]?) -> Void
    ) -> Bool {
        return SingularCordovaSdk.startSession(with: userActivity)
    }
}

이러한 메서드를 사용하면 Singular SDK가 앱이 실행된 방법과 이유에 대한 중요한 정보를 수신하여 어트리뷰션 추적 및 딥링크 탐색에 사용할 수 있습니다.

위치: platforms/ios/[YourAppName]/Classes/AppDelegate.swift 또는 Objective-C 프로젝트의 경우 AppDelegate.m 에 있는 AppDelegate 파일을 수정합니다.


SDK 구성

초기화 중에 withSingularLink 콜백을 구현하여 딥링크 및 디퍼드 딥링크를 처리하도록 Singular SDK를 구성합니다.

Singular링크 콜백 추가

기본 구현

SDK 초기화 중에 들어오는 딥링크 및 디퍼드 딥링크 데이터를 처리하도록 withSingularLink 콜백을 구성합니다.

JavaScript
// Create configuration
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
);

// Define link handler function
var linkHandler = function(data) {
  var deeplink = data.deeplink;
  var passthrough = data.passthrough;
  var isDeferred = data.isDeferred;
  
  console.log('Deep link:', deeplink);
  console.log('Passthrough:', passthrough);
  console.log('Is deferred:', isDeferred);
  
  // Add link handling logic here
  if (deeplink) {
    handleDeepLink(deeplink, isDeferred);
  }
};

// Attach link handler to configuration
singularConfig.withSingularLink(linkHandler);

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(singularConfig);

참고: withSingularLink 콜백은 앱이 Singular 링크를 통해 열릴 때만 트리거됩니다. 자세한 내용은 Singular 링크 FAQ를 참조하세요.


고급 구현

프로덕션 앱에 대한 탐색 로직, 패스스루 데이터 구문 분석 및 오류 처리를 통해 포괄적인 딥링크 처리를 구현하세요.

JavaScript
document.addEventListener('deviceready', initializeApp, false);

function initializeApp() {
  // Create configuration
  var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
    'YOUR_SDK_KEY',
    'YOUR_SDK_SECRET'
  );
  
  // Configure deep link handler
  config.withSingularLink(function(params) {
    console.log('=== Singular Link Resolved ===');
    console.log('Full params:', JSON.stringify(params));
    
    var deeplink = params.deeplink;
    var passthrough = params.passthrough;
    var isDeferred = params.isDeferred;
    
    // Log for debugging
    console.log('Deep link:', deeplink || 'null');
    console.log('Passthrough:', passthrough || 'null');
    console.log('Is deferred:', isDeferred);
    
    // Handle passthrough data
    if (passthrough) {
      handlePassthroughData(passthrough);
    }
    
    // Handle deep link navigation
    if (deeplink) {
      handleDeepLinkNavigation(deeplink, isDeferred);
    }
  });
  
  // Initialize SDK
  cordova.plugins.SingularCordovaSdk.init(config);
}

function handlePassthroughData(passthroughString) {
  try {
    var data = JSON.parse(passthroughString);
    
    // Apply promo code if present
    if (data.promo_code) {
      applyPromoCode(data.promo_code);
    }
    
    // Set user segment
    if (data.segment) {
      setUserSegment(data.segment);
    }
    
    // Track campaign
    if (data.campaign_id) {
      trackCampaign(data.campaign_id);
    }
  } catch (error) {
    console.error('Error parsing passthrough:', error);
  }
}

function handleDeepLinkNavigation(url, isDeferred) {
  // Parse URL to extract route and parameters
  var urlObj = parseDeepLink(url);
  
  console.log('Navigating to: ' + urlObj.route);
  console.log('Parameters:', urlObj.params);
  console.log('Deferred install:', isDeferred);
  
  // Route based on deep link structure
  switch (urlObj.route) {
    case 'product':
      navigateToProduct(urlObj.params.id);
      break;
    case 'promo':
      navigateToPromo(urlObj.params.code);
      break;
    case 'category':
      navigateToCategory(urlObj.params.name);
      break;
    default:
      navigateToHome();
  }
}

function parseDeepLink(url) {
  // Parse myapp://product/123?variant=blue
  var parts = url.split('?');
  var path = parts[0];
  var queryString = parts[1];
  
  var pathParts = path.replace(/^[^:]+:\/\//, '').split('/');
  var route = pathParts[0];
  
  // Parse parameters
  var params = {};
  
  // Add path parameters
  if (pathParts.length > 1) {
    params.id = pathParts[1];
  }
  
  // Add query parameters
  if (queryString) {
    queryString.split('&').forEach(function(pair) {
      var keyValue = pair.split('=');
      params[keyValue[0]] = decodeURIComponent(keyValue[1]);
    });
  }
  
  return { route: route, params: params };
}

// Navigation functions
function navigateToProduct(productId) {
  console.log('Navigating to product:', productId);
  // Your navigation logic
}

function navigateToPromo(promoCode) {
  console.log('Navigating to promo:', promoCode);
  // Your navigation logic
}

function navigateToCategory(categoryName) {
  console.log('Navigating to category:', categoryName);
  // Your navigation logic
}

function navigateToHome() {
  console.log('Navigating to home');
  // Your navigation logic
}

// Utility functions
function applyPromoCode(code) {
  console.log('Applying promo code:', code);
}

function setUserSegment(segment) {
  console.log('Setting user segment:', segment);
}

function trackCampaign(campaignId) {
  console.log('Tracking campaign:', campaignId);
}

매개변수 세부 정보

Singular 링크 콜백에 제공되는 매개변수를 이해하면 강력한 딥링킹 로직을 구축하는 데 도움이 됩니다.

파라미터 유형 설명
deeplink 문자열 링크를 클릭하는 사용자의 앱 내 대상 URL(예: myapp://product/123)
passthrough 문자열 추적 링크를 통해 전달되는 사용자 지정 데이터로, 일반적으로 추가 컨텍스트를 위해 JSON으로 인코딩됩니다.
isDeferred Boolean 디퍼드 딥링크인지 여부(사용자가 링크를 클릭한 후 앱을 설치했는지 여부)를 나타냅니다.

모범 사례

  • URL을 안전하게 파싱하세요: 악의적인 리디렉션을 방지하기 위해 딥링크 URL을 탐색에 사용하기 전에 항상 유효성을 검사하고 위생 처리합니다.
  • 누락된 데이터 처리: 딥링크 파라미터에 액세스하기 전에 null 또는 정의되지 않은 값이 있는지 확인합니다.
  • 디퍼드 링크 테스트: 즉시 및 디퍼드 딥링크 시나리오를 모두 테스트하여 새로 설치한 후 적절한 탐색을 보장합니다.
  • 디버깅을 위한 로그: 개발 중에 상세 로깅을 활성화하여 딥링크가 올바르게 수신되고 파싱되는지 확인합니다.
  • 컨텍스트에 패스스루 사용: 패스스루 매개변수를 활용하여 캠페인 ID, 프로모션 코드 또는 사용자 세그먼트와 같은 추가 컨텍스트를 전송할 수 있습니다.
  • 마케팅 팀과 협력: 마케팅 팀과 협력하여 앱의 딥링크 URL 구조를 정의하고 문서화하세요.

전체 메서드 문서는 Singular링크 참조를 참조하세요.


핸들러 동작

콜백 트리거 이해

withSingularLink 콜백 동작은 앱이 새로 설치되었는지 또는 기기에 이미 존재하는지에 따라 달라집니다.

새로 설치 시나리오

새로 설치한 경우 앱이 실행될 때 열기 URL이 없습니다. Singular는 마지막 터치포인트에 대한 어트리뷰션을 완료하고 추적 링크에 구성된 딥링크 또는 디퍼드 딥링크(DDL) 값이 포함되어 있는지 확인해야 합니다.

작동 방식:

  • 어트리뷰션 프로세스는 Singular SDK가 첫 번째 세션을 Singular 서버로 전송할 때 발생합니다.
  • 해당되는 경우 딥링크 값은 SDK의 withSingularLink 핸들러로 반환됩니다.
  • 딥링크는 deeplink 파라미터에 isDeferredtrue로 설정된 상태로 나타납니다.
  • 이 프로세스는 서버 통신이 필요하므로 몇 초 정도 걸릴 수 있습니다.

이미 설치된 시나리오

앱이 이미 설치되어 있는 경우, Singular 링크를 클릭하면 앱이 즉시 열립니다. 운영 체제는 전체 추적 링크 URL을 제공하며, Singular SDK는 초기화 중에 이를 파싱하여 deeplinkpassthrough 값을 추출합니다.

작동 방식:

  • 핸들러가 트리거되면 딥링크를 즉시 사용할 수 있습니다.
  • isDeferred 파라미터는 false으로 설정됩니다.
  • 서버 통신이 필요하지 않으므로 콜백 실행 속도가 빨라집니다.

딥 링크 테스트하기

개발 환경에서 디퍼드 딥링킹 동작을 테스트하려면 다음 단계를 따르세요.

테스트 요구 사항:

  1. 테스트 기기에서 앱을 제거합니다(현재 설치되어 있는 경우).
  2. 광고 식별자를 재설정합니다(iOS의 경우 IDFA, Android의 경우 GAID).
  3. 기기에서 Singular 추적 링크를 클릭합니다. 링크가 딥링크 값으로 구성되어 있는지 확인합니다.
  4. 앱을 설치하고 엽니다.
  5. 어트리뷰션이 완료되고 DDL 값이 핸들러에 전달되었는지 확인합니다.

개발 빌드 테스트: 패키지 이름이 다른 앱의 개발 버전으로 테스트하는 경우(예: com.example.prod 대신 com.example.dev ), 추적 링크가 개발 앱의 패키지 이름에 맞게 특별히 구성되었는지 확인하세요. 테스트 링크를 클릭한 후 앱 스토어에서 다운로드하지 않고 CLI 또는 IDE를 통해 개발 빌드를 테스트 기기에 직접 설치합니다.


고급 기능

패스스루 데이터

트래킹 링크에 패스스루(_p) 파라미터가 포함된 경우, 핸들러의 passthrough 파라미터에 해당 데이터가 포함됩니다. 캠페인 메타데이터, 사용자 세분화 데이터 또는 앱에 필요한 사용자 지정 정보를 캡처하는 데 사용합니다.

JavaScript
// Example tracking link with passthrough:
// https://example.sng.link/A?_dl=myapp://product/123&_p={"campaign":"summer","promo":"SAVE20"}

singularConfig.withSingularLink(function(data) {
  var deeplink = data.deeplink;
  var passthrough = data.passthrough;
  
  if (passthrough) {
    // Parse JSON passthrough data
    var passthroughData = JSON.parse(passthrough);
    console.log('Campaign:', passthroughData.campaign);
    console.log('Promo code:', passthroughData.promo);
  }
});

쿼리 파라미터 전달

추적 링크 URL에서 모든 쿼리 파라미터를 캡처하려면 _forward_params=2 파라미터를 Singular 추적 링크에 추가합니다. 모든 쿼리 파라미터는 핸들러의 deeplink 파라미터에 포함됩니다.

JavaScript
// Example tracking link with parameter forwarding:
// https://example.sng.link/A?_dl=myapp://product&_forward_params=2&category=electronics&sort=price

singularConfig.withSingularLink(function(data) {
  var deeplink = data.deeplink;
  // deeplink will contain: myapp://product?category=electronics&sort=price
  
  console.log('Deep link with parameters:', deeplink);
  // Parse and use the forwarded parameters
});

중요: withSingularLink 콜백은 앱이 Singular 링크를 통해 열릴 때만 트리거됩니다. 딥링크가 없는 일반 앱 실행은 핸들러를 트리거하지 않습니다.