Suporte a deep links

Os deep links direcionam os usuários para conteúdo específico dentro do seu app. Quando os usuários tocam em um deep link em um dispositivo com seu app instalado, o app abre diretamente no conteúdo desejado, como uma página de produto ou uma experiência específica.

Os tracking links da Singular oferecem suporte tanto a deep linking padrão (para apps instalados) quanto a deep linking diferido (para novas instalações). Para informações completas, consulte Perguntas frequentes sobre deep linking e Singular Links FAQ .

Requisitos

Pré-requisitos

Conclua os Pré-requisitos do Singular Links para habilitar o deep linking no seu app.

Etapas de configuração obrigatórias:

• Associated Domains: No Xcode, adicione um subdomínio personalizado da Singular em Signing & Capabilities > Associated Domains
• URL Types: Adicione o esquema do app aos seus URL Types em Info > URL Types
• Plataforma Singular: Adicione seu Team ID e Scheme do Apple Developer na página Apps na plataforma Singular

Implementar o handler do Singular Links

O SingularLinkHandler fornece um mecanismo de callback para recuperar os parâmetros de deep link, deep link diferido e passthrough dos tracking links da Singular quando o app é aberto.

Parâmetros disponíveis:

• Deep Link: A URL de destino dentro do seu app para os usuários que clicam no link
• Deferred Deep Link: A URL de destino para os usuários que instalam o app após clicar no link
• Passthrough: Dados personalizados passados através do tracking link para contexto adicional
• URL Parameters: Todos os parâmetros de consulta da URL do tracking link

Configuração do SDK

Adicionar SingularLinkHandler ao Config

Configure o SingularLinkHandler durante a inicialização do SDK para processar os dados de deep link e deep link diferido recebidos.

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];
    }
}

Comportamento do handler

Entendendo a execução do SingularLinkHandler

O SingularLinkHandler se comporta de forma diferente dependendo se o app acabou de ser instalado ou se já está instalado.

Nova instalação (deep link diferido)

Em uma nova instalação, não existe nenhuma Open URL quando o app é iniciado. A Singular conclui a atribuição para determinar se o tracking link continha um valor de deep link ou deep link diferido.

Fluxo de deep link diferido:

1. O usuário clica em um tracking link da Singular configurado com um valor de deep link
2. O usuário instala e abre o app pela primeira vez
3. O SDK da Singular envia a primeira sessão para os servidores da Singular
4. A atribuição é concluída e identifica o deep link a partir do tracking link
5. O valor do deep link retorna ao SingularLinkHandler com isDeferred = true

Já instalado (deep link imediato)

Quando o app já está instalado, clicar em um Singular Link abre o app imediatamente usando a tecnologia iOS Universal Links.

Fluxo de deep link imediato:

1. O usuário clica em um tracking link da Singular
2. O iOS fornece uma Open URL contendo todo o tracking link da Singular
3. Durante a inicialização do SDK, a Singular analisa o NSUserActivity ou a URL
4. A Singular extrai os valores de deep link e passthrough
5. Os valores retornam através do SingularLinkHandler com isDeferred = false

Parâmetros de Passthrough

Capture dados adicionais do clique no tracking link usando parâmetros passthrough.

Se um parâmetro passthrough estiver incluído no tracking link, o parâmetro passthrough do SingularLinkHandler conterá os dados correspondentes. Use isso para capturar metadados de campanha, dados de segmentação de usuários ou qualquer informação personalizada que você precise no app.

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");
        }
    }
}

Parâmetros de URL

Capture todos os parâmetros de consulta da URL do tracking link usando o método getUrlParameters() .

O SingularLinkHandler fornece acesso a todos os parâmetros de URL do tracking link, dando a você acesso completo aos parâmetros personalizados e às tags 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);
        }
    }
}

Configuração avançada

Tratamento de Universal Links não Singular

Ofereça suporte a Universal Links de parceiros terceiros, como Google Ads e Facebook, para rastreamento de atribuição.

Para as versões 12.0.3 e superiores do SDK do iOS da Singular, Universal Links não Singular são suportados por padrão.

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;
}

Suporte a domínios personalizados de tracking link de ESP

Habilite Universal Links servidos por provedores de serviços de e-mail (ESPs) para atribuição de campanhas de e-mail.

O domínio do ESP deve estar habilitado para HTTPS. A Apple exige que os apps iOS obtenham os arquivos apple-app-site-association de um endpoint habilitado para HTTPS sem redirecionamentos. Verifique com seu ESP como ele hospeda esse arquivo para o seu app, pois pode exigir configuração de DNS no DNS do seu site.

Para oferecer suporte a um domínio de ESP, adicione o domínio de tracking personalizado à opção de configuração espDomains no objeto config sempre que o SDK da Singular for inicializado.

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;
}