Adição de suporte para Deep Linking

Os linksdirecionam os usuários para um conteúdo específico dentro do seu aplicativo. Quando os utilizadores tocam numa ligação direta num dispositivo com a sua aplicação instalada, a aplicação abre-se diretamente para o conteúdo pretendido, como uma página de produto ou uma experiência específica.

Os links de rastreamento singulares suportam links diretos padrão (para aplicativos instalados) e links diretos adiados (para novas instalações). Para obter informações abrangentes, consulte as Perguntas frequentes sobre links diretose as Perguntas frequentes sobre links singulares.

Requisitos

Pré-requisitos

Preencha os Pré-requisitos do Singular Linkspara habilitar o deep linking para seu aplicativo.

Etapas de configuração necessárias:

• Domínios associados: No Xcode, adicione um subdomínio personalizado Singular a Assinatura e recursos > Domínios associados
• Tipos de URL: Adicione o esquema do aplicativo aos seus Tipos de URL em Informações > Tipos de URL
• Plataforma Singular: Adicione seu ID e esquema da equipe de desenvolvedores da Apple na página Aplicativos na plataforma Singular

Implementar o manipulador de links do Singular

O SingularLinkHandler fornece um mecanismo de retorno de chamada para recuperar parâmetros de deep link, deferred deep link e passthrough dos links de rastreamento do Singular quando o aplicativo é aberto.

Parâmetros disponíveis:

• Deep Link: O URL de destino dentro do seu aplicativo para usuários que clicam no link
• Deep Link diferido: O URL de destino para os utilizadores que instalam a aplicação depois de clicarem no link
• Passthrough: Dados personalizados passados através do link de rastreamento para contexto adicional
• Parâmetros de URL: Todos os parâmetros de consulta do URL do link de rastreamento

Configuração do SDK

Adicionar SingularLinkHandler à configuração

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

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 manipulador

Entendendo a execução do SingularLinkHandler

O SingularLinkHandler se comporta de maneira diferente, dependendo se o aplicativo foi instalado recentemente ou se já está instalado.

Instalação recente (Deep Link diferido)

Em uma instalação recente, não existe uma URL aberta quando o aplicativo é iniciado. A Singular completa a atribuição para determinar se o link de rastreamento contém um valor de deep link ou de deferred deep link.

Fluxo do Deferred Deep Link:

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

Já instalado (ligação direta imediata)

Quando o aplicativo já está instalado, clicar em um link singular abre o aplicativo imediatamente usando a tecnologia iOS Universal Links.

Fluxo de Deep Link Imediato:

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

Parâmetros de passagem

Capture dados adicionais do clique no link de rastreamento usando parâmetros de passagem.

Se um parâmetro de passagem for incluído no link de rastreamento, o parâmetro passthrough do SingularLinkHandler conterá os dados correspondentes. Utilize-o para capturar metadados de campanha, dados de segmentação de utilizadores ou qualquer informação personalizada de que necessite na aplicação.

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 do URL do link de rastreamento usando o método getUrlParameters().

O SingularLinkHandler fornece acesso a todos os parâmetros de URL do link de rastreamento, dando-lhe acesso completo a parâmetros personalizados e 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

Manipulação de links universais não-singulares

Suporte a Links Universais de parceiros de terceiros, como Google Ads e Facebook, para rastreamento de atribuição.

Para as versões 12.0.3 e posteriores do SDK do Singular iOS, os Links universais que não são do 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 de links de rastreamento personalizados do ESP

Habilite os Universal Links fornecidos pelos provedores de serviços de email (ESPs) para atribuição de campanhas de email.

O domínio ESP deve ser habilitado para HTTPS. A Apple exigeque as aplicações iOS extraiam ficheiros apple-app-site-association de um ponto final ativado para HTTPS sem redireccionamentos. Verifique com seu ESP como eles hospedam esse arquivo para seu aplicativo, pois isso pode exigir a configuração de DNS no DNS do seu site.

Para dar suporte a um domínio ESP, adicione o domínio de rastreamento personalizado à opção de configuração espDomains no objeto config sempre que o SDK 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;
}