Soporte para deep links

Los deep links dirigen a los usuarios a contenido específico dentro de tu aplicación. Cuando los usuarios tocan un deep link en un dispositivo con tu aplicación instalada, la aplicación se abre directamente en el contenido previsto, como una página de producto o una experiencia específica.

Los tracking links de Singular admiten tanto deep linking estándar (para aplicaciones instaladas) como deep linking diferido (para nuevas instalaciones). Para obtener información completa, consulta Preguntas frecuentes sobre deep linking y Singular Links FAQ .

Requisitos

Requisitos previos

Completa los Requisitos previos de Singular Links para habilitar el deep linking en tu aplicación.

Pasos de configuración requeridos:

• Associated Domains: En Xcode, agrega un subdominio personalizado de Singular en Signing & Capabilities > Associated Domains
• URL Types: Agrega el esquema de la aplicación a tus URL Types en Info > URL Types
• Plataforma de Singular: Agrega tu Team ID y Scheme de Apple Developer en la página Apps de la plataforma de Singular

Implementar el handler de Singular Links

El SingularLinkHandler proporciona un mecanismo de callback para obtener los parámetros de deep link, deep link diferido y passthrough de los tracking links de Singular cuando se abre la aplicación.

Parámetros disponibles:

• Deep Link: La URL de destino dentro de tu aplicación para los usuarios que hacen clic en el link
• Deferred Deep Link: La URL de destino para los usuarios que instalan la aplicación después de hacer clic en el link
• Passthrough: Datos personalizados pasados a través del tracking link para contexto adicional
• URL Parameters: Todos los parámetros de consulta de la URL del tracking link

Configuración del SDK

Agregar SingularLinkHandler a Config

Configura el SingularLinkHandler durante la inicialización del SDK para procesar los datos entrantes de deep link y deep link diferido.

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

Comportamiento del handler

Entender la ejecución del SingularLinkHandler

El SingularLinkHandler se comporta de manera diferente según si la aplicación se acaba de instalar o ya está instalada.

Instalación nueva (deep link diferido)

En una instalación nueva, no existe ninguna Open URL cuando se inicia la aplicación. Singular completa la atribución para determinar si el tracking link contenía un valor de deep link o deep link diferido.

Flujo de deep link diferido:

1. El usuario hace clic en un tracking link de Singular configurado con un valor de deep link
2. El usuario instala y abre la aplicación por primera vez
3. El SDK de Singular envía la primera sesión a los servidores de Singular
4. La atribución se completa e identifica el deep link del tracking link
5. El valor del deep link regresa al SingularLinkHandler con isDeferred = true

Ya instalada (deep link inmediato)

Cuando la aplicación ya está instalada, al hacer clic en un Singular Link la aplicación se abre inmediatamente usando la tecnología iOS Universal Links.

Flujo de deep link inmediato:

1. El usuario hace clic en un tracking link de Singular
2. iOS proporciona una Open URL que contiene el tracking link completo de Singular
3. Durante la inicialización del SDK, Singular analiza el NSUserActivity o la URL
4. Singular extrae los valores de deep link y passthrough
5. Los valores regresan a través del SingularLinkHandler con isDeferred = false

Parámetros de Passthrough

Captura datos adicionales del clic en el tracking link usando parámetros passthrough.

Si se incluye un parámetro passthrough en el tracking link, el parámetro passthrough del SingularLinkHandler contiene los datos correspondientes. Úsalo para capturar metadatos de la campaña, datos de segmentación de usuarios o cualquier información personalizada que necesites en la aplicación.

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

Captura todos los parámetros de consulta de la URL del tracking link usando el método getUrlParameters() .

El SingularLinkHandler proporciona acceso a todos los parámetros de URL del tracking link, dándote acceso completo a los parámetros personalizados y a las etiquetas 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);
        }
    }
}

Configuración avanzada

Manejo de Universal Links no Singular

Admite Universal Links de socios externos como Google Ads y Facebook para el seguimiento de atribución.

Para las versiones 12.0.3 y superiores del SDK de iOS de Singular, los Universal Links no Singular están soportados de forma predeterminada.

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

Soporte para dominios personalizados de tracking link de ESP

Habilita Universal Links servidos por proveedores de servicios de correo electrónico (ESP) para la atribución de campañas de correo electrónico.

El dominio del ESP debe estar habilitado para HTTPS. Apple requiere que las aplicaciones iOS obtengan los archivos apple-app-site-association desde un endpoint habilitado para HTTPS sin redireccionamientos. Verifica con tu ESP cómo aloja este archivo para tu aplicación, ya que puede requerir configuración de DNS en el DNS de tu sitio.

Para admitir un dominio de ESP, agrega el dominio de tracking personalizado a la opción de configuración espDomains en el objeto config cada vez que se inicializa el SDK de Singular.

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