딥링크 지원 추가

딥링크 는 사용자를 앱 내의 특정 콘텐츠로 안내합니다. 앱이 설치된 디바이스에서 사용자가 딥링크를 탭하면 앱이 직접 열리며, 제품 페이지나 특정 경험과 같은 의도한 콘텐츠로 이동합니다.

Singular 트래킹 링크는 표준 딥링크(설치된 앱용)와 지연된 딥링크(신규 설치용)를 모두 지원합니다. 자세한 내용은 딥링크 FAQ 와 Singular Links FAQ 를 참조하세요.

요구 사항

사전 준비

앱에서 딥링크를 활성화하려면 Singular Links 사전 준비 를 완료하세요.

필수 구성 단계:

• Associated Domains: Xcode에서 Signing & Capabilities > Associated Domains 에 Singular 커스텀 서브도메인을 추가합니다
• URL Types: Info > URL Types 에서 앱 스킴을 URL Types에 추가합니다
• Singular 플랫폼: Singular 플랫폼의 Apps 페이지에서 Apple Developer Team ID 와 Scheme 을 추가합니다

Singular Links 핸들러 구현

SingularLinkHandler는 앱이 열릴 때 Singular 트래킹 링크에서 딥링크, 지연된 딥링크, 패스스루 파라미터를 가져오는 콜백 메커니즘을 제공합니다.

사용 가능한 파라미터:

• Deep Link: 링크를 클릭한 사용자를 위한 앱 내 대상 URL
• Deferred Deep Link: 링크를 클릭한 후 앱을 설치한 사용자를 위한 대상 URL
• Passthrough: 추가 컨텍스트를 위해 트래킹 링크를 통해 전달되는 사용자 정의 데이터
• URL Parameters: 트래킹 링크 URL의 모든 쿼리 파라미터

SDK 구성

SingularLinkHandler를 Config에 추가

SDK 초기화 중에 SingularLinkHandler를 구성하여 들어오는 딥링크 및 지연된 딥링크 데이터를 처리합니다.

func getConfig() -> SingularConfig? {
    // Create config with API credentials
    guard let config = SingularConfig(apiKey: "SDK_KEY", andSecret: "SDK_SECRET") else {
        return nil
    }
    
    // Set deep link handler
    config.singularLinksHandler = { params in
        self.handleDeeplink(params: params)
    }
    
    return config
}

func handleDeeplink(params: SingularLinkParams?) {
    // Get Deeplink data from Singular Link
    let deeplink = params?.getDeepLink()
    let passthrough = params?.getPassthrough()
    let isDeferred = params?.isDeferred()
    let urlParams = params?.getUrlParameters()
    
    print("Deeplink: \(deeplink ?? "null")")
    print("Passthrough: \(passthrough ?? "null")")
    print("Is Deferred: \(isDeferred ?? false)")
    
    // Handle deep link routing
    if let url = deeplink {
        handleDeepLinkRouting(url: url, isDeferred: isDeferred ?? false)
    }
}

- (SingularConfig *)getConfig {
    // Create config with API credentials
    SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"SDK_KEY" 
        andSecret:@"SDK_SECRET"];
    
    // Set deep link handler
    config.singularLinksHandler = ^(SingularLinkParams *params) {
        [self handleDeeplink:params];
    };
    
    return config;
}

- (void)handleDeeplink:(SingularLinkParams *)params {
    // Get Deeplink data from Singular Link
    NSString *deeplink = [params getDeepLink];
    NSString *passthrough = [params getPassthrough];
    BOOL isDeferred = [params isDeferred];
    NSDictionary *urlParams = [params getUrlParameters];
    
    NSLog(@"Deeplink: %@", deeplink ?: @"null");
    NSLog(@"Passthrough: %@", passthrough ?: @"null");
    NSLog(@"Is Deferred: %d", isDeferred);
    
    // Handle deep link routing
    if (deeplink) {
        [self handleDeepLinkRouting:deeplink isDeferred:isDeferred];
    }
}

핸들러 동작

SingularLinkHandler 실행 이해하기

SingularLinkHandler는 앱이 새로 설치되었는지 또는 이미 설치되어 있는지에 따라 다르게 동작합니다.

신규 설치 (지연된 딥링크)

신규 설치 시, 앱이 실행될 때 Open URL이 존재하지 않습니다. Singular는 어트리뷰션을 완료하여 트래킹 링크에 딥링크 또는 지연된 딥링크 값이 포함되어 있는지 확인합니다.

지연된 딥링크 흐름:

1. 사용자가 딥링크 값으로 구성된 Singular 트래킹 링크를 클릭합니다
2. 사용자가 앱을 설치하고 처음으로 엽니다
3. Singular SDK가 첫 세션을 Singular 서버로 전송합니다
4. 어트리뷰션이 완료되고 트래킹 링크에서 딥링크를 식별합니다
5. 딥링크 값이 isDeferred = true 와 함께 SingularLinkHandler로 반환됩니다

이미 설치된 경우 (즉시 딥링크)

앱이 이미 설치된 경우, Singular Link를 클릭하면 iOS Universal Links 기술을 사용하여 앱이 즉시 열립니다.

즉시 딥링크 흐름:

1. 사용자가 Singular 트래킹 링크를 클릭합니다
2. iOS가 전체 Singular 트래킹 링크를 포함하는 Open URL을 제공합니다
3. SDK 초기화 중에 Singular가 NSUserActivity 또는 URL을 파싱합니다
4. Singular가 딥링크와 패스스루 값을 추출합니다
5. 값이 isDeferred = false 와 함께 SingularLinkHandler를 통해 반환됩니다

Passthrough 파라미터

패스스루 파라미터를 사용하여 트래킹 링크 클릭에서 추가 데이터를 캡처합니다.

트래킹 링크에 패스스루 파라미터가 포함된 경우, SingularLinkHandler의 passthrough 파라미터에 해당 데이터가 포함됩니다. 이를 사용하여 캠페인 메타데이터, 사용자 세분화 데이터 또는 앱에서 필요한 모든 사용자 정의 정보를 캡처할 수 있습니다.

func handleDeeplink(params: SingularLinkParams?) {
    // Extract passthrough data
    if let passthroughData = params?.getPassthrough() {
        // Parse JSON passthrough data
        if let data = passthroughData.data(using: .utf8),
           let jsonData = try? JSONSerialization.jsonObject(with: data) as? [String: Any] {
            
            let campaignId = jsonData["campaign_id"] as? String
            let userSegment = jsonData["segment"] as? String
            
            print("Campaign ID: \(campaignId ?? "unknown")")
            print("User Segment: \(userSegment ?? "unknown")")
        }
    }
}

- (void)handleDeeplink:(SingularLinkParams *)params {
    // Extract passthrough data
    NSString *passthroughData = [params getPassthrough];
    if (passthroughData) {
        // Parse JSON passthrough data
        NSData *data = [passthroughData dataUsingEncoding:NSUTF8StringEncoding];
        NSError *error;
        NSDictionary *jsonData = [NSJSONSerialization JSONObjectWithData:data 
            options:0 
            error:&error];
        
        if (!error && jsonData) {
            NSString *campaignId = jsonData[@"campaign_id"];
            NSString *userSegment = jsonData[@"segment"];
            
            NSLog(@"Campaign ID: %@", campaignId ?: @"unknown");
            NSLog(@"User Segment: %@", userSegment ?: @"unknown");
        }
    }
}

URL 파라미터

getUrlParameters() 메서드를 사용하여 트래킹 링크 URL의 모든 쿼리 파라미터를 캡처합니다.

SingularLinkHandler는 트래킹 링크의 모든 URL 파라미터에 대한 액세스를 제공하여, 사용자 정의 파라미터와 UTM 태그에 완전히 액세스할 수 있게 합니다.

func handleDeeplink(params: SingularLinkParams?) {
    // Get all URL parameters
    if let urlParams = params?.getUrlParameters() {
        for (key, value) in urlParams {
            print("Parameter: \(key) = \(value)")
        }
        
        // Access specific parameters
        if let utmSource = urlParams["utm_source"] as? String {
            print("UTM Source: \(utmSource)")
        }
        
        if let promoCode = urlParams["promo"] as? String {
            print("Promo Code: \(promoCode)")
        }
    }
}

- (void)handleDeeplink:(SingularLinkParams *)params {
    // Get all URL parameters
    NSDictionary *urlParams = [params getUrlParameters];
    if (urlParams) {
        for (NSString *key in urlParams) {
            NSLog(@"Parameter: %@ = %@", key, urlParams[key]);
        }
        
        // Access specific parameters
        NSString *utmSource = urlParams[@"utm_source"];
        if (utmSource) {
            NSLog(@"UTM Source: %@", utmSource);
        }
        
        NSString *promoCode = urlParams[@"promo"];
        if (promoCode) {
            NSLog(@"Promo Code: %@", promoCode);
        }
    }
}

고급 구성

Singular 외 Universal Links 처리

어트리뷰션 추적을 위해 Google Ads, Facebook과 같은 외부 파트너의 Universal Links를 지원합니다.

Singular iOS SDK 버전 12.0.3 이상에서는 Singular 외 Universal Links가 기본적으로 지원됩니다.

func getConfig() -> SingularConfig? {
    guard let config = SingularConfig(apiKey: "SDK_KEY", andSecret: "SDK_SECRET") else {
        return nil
    }
    
    // Add supported domains for third-party Universal Links
    config.supportedDomains = [
        "subdomain.mywebsite.com",
        "anothersubdomain.myotherwebsite.com"
    ]
    
    return config
}

- (SingularConfig *)getConfig {
    SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"SDK_KEY" 
        andSecret:@"SDK_SECRET"];
    
    // Add supported domains for third-party Universal Links
    config.supportedDomains = @[
        @"subdomain.mywebsite.com",
        @"anothersubdomain.myotherwebsite.com"
    ];
    
    return config;
}

ESP 커스텀 트래킹 링크 도메인 지원

이메일 캠페인 어트리뷰션을 위해 이메일 서비스 제공자(ESP)가 제공하는 Universal Links를 활성화합니다.

ESP 도메인은 HTTPS가 활성화되어 있어야 합니다. Apple은 iOS 앱이 리디렉션 없이 HTTPS가 활성화된 엔드포인트에서 apple-app-site-association 파일을 가져오도록 요구 합니다. ESP가 앱에 대해 이 파일을 어떻게 호스팅하는지 확인하세요. 사이트의 DNS 구성이 필요할 수 있습니다.

ESP 도메인을 지원하려면 Singular SDK가 초기화될 때마다 config 객체의 espDomains 구성 옵션에 커스텀 트래킹 도메인을 추가합니다.

func getConfig() -> SingularConfig? {
    guard let config = SingularConfig(apiKey: "SDK_KEY", andSecret: "SDK_SECRET") else {
        return nil
    }
    
    // Add ESP domains for email campaign tracking
    config.espDomains = ["links.mywebsite.com"]
    
    return config
}

- (SingularConfig *)getConfig {
    SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"SDK_KEY" 
        andSecret:@"SDK_SECRET"];
    
    // Add ESP domains for email campaign tracking
    config.espDomains = @[@"links.mywebsite.com"];
    
    return config;
}