Añadir soporte para enlaces profundos

Los enlaces profundosdirigen a los usuarios a contenidos específicos dentro de su aplicación. Cuando los usuarios tocan un enlace profundo en un dispositivo con su aplicación instalada, la aplicación se abre directamente al contenido deseado, como una página de producto o una experiencia específica.

Los enlaces de seguimiento singulares admiten tanto enlaces profundos estándar (para aplicaciones instaladas) como enlaces profundos diferidos (para nuevas instalaciones). Para más información, consulte las preguntas frecuentes sobre deep linkingy las preguntas frecuentes sobre Singular Links.

Requisitos

Requisitos previos

Complete los requisitosprevios de Singular Linkspara habilitar la vinculación profunda para su aplicación.

Pasos de configuración necesarios:

• Dominios asociados: En Xcode, añada un subdominio personalizado Singular a Signing & Capabilities > Associated Domains.
• Tipos de URL: Añada el esquema de la aplicación a sus tipos de URL en Info > Tipos de URL.
• Plataforma Singular: Añade tu Apple Developer Team ID y Scheme en la página Apps en la plataforma Singular

Implementación de Singular Links Handler

SingularLinkHandler proporciona un mecanismo de devolución de llamada para recuperar los parámetros de enlace profundo, enlace profundo diferido y passthrough de los enlaces de seguimiento de Singular cuando se abre la aplicación.

Parámetros disponibles:

• Enlace profundo: La URL de destino dentro de su aplicación para los usuarios que hacen clic en el enlace
• Enlace profundo diferido: La URL de destino para los usuarios que instalan la app después de hacer clic en el enlace
• Passthrough: Datos personalizados pasados a través del enlace de seguimiento para un contexto adicional
• Parámetros URL: Todos los parámetros de consulta de la URL del enlace de seguimiento

Configuración del SDK

Añadir SingularLinkHandler a Config

Configure el SingularLinkHandler durante la inicialización del SDK para procesar los datos entrantes del enlace profundo y del enlace profundo 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

Comprensión de la ejecución de SingularLinkHandler

El SingularLinkHandler se comporta de forma diferente dependiendo de si la aplicación está recién instalada o ya instalada.

Nueva instalación (enlace profundo diferido)

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

Flujode enlace profundo diferido:

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

Ya instalada (enlace profundo inmediato)

Cuando la aplicación ya está instalada, al hacer clic en un enlace singular se abre la aplicación inmediatamente mediante la tecnología de enlaces universales de iOS.

Flujo de enlace profundo inmediato:

1. El usuario hace clic en un enlace de seguimiento Singular
2. iOS proporciona una URL abierta que contiene todo el enlace de seguimiento Singular
3. Durante la inicialización del SDK, Singular analiza la NSUserActivity o URL
4. Singular extrae el enlace profundo y los valores passthrough
5. Los valores vuelven a través del SingularLinkHandler con isDeferred = false

Parámetros Passthrough

Capture datos adicionales del clic del enlace de seguimiento utilizando parámetros passthrough.

Si se incluye un parámetro passthrough en el enlace de seguimiento, el parámetro passthrough del SingularLinkHandler contiene los datos correspondientes. Utilícelo para capturar metadatos de campaña, datos de segmentación de usuarios o cualquier información personalizada que necesite 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 URL

Capture todos los parámetros de consulta de la URL del enlace de seguimiento utilizando el método getUrlParameters().

El SingularLinkHandler proporciona acceso a todos los parámetros de la URL del enlace de seguimiento, lo que le da acceso completo a parámetros personalizados y 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

Gestión de enlaces universales no singulares

Admite enlaces universales de socios de terceros como Google Ads y Facebook para el seguimiento de atribución.

Para las versiones 12.0.3 y superiores del SDK de Singular iOS, los enlaces universales no pertenecientes a Singular son compatibles por defecto.

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 de dominios de enlaces de seguimiento personalizados de ESP

Habilite 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 ESP debe estar habilitado para HTTPS. Apple exigeque las aplicaciones de iOS extraigan los archivos de asociación de sitios de aplicaciones de manzana desde un punto final habilitado para HTTPS sin redireccionamientos. Compruebe con su ESP cómo alojan este archivo para su aplicación, ya que puede requerir la configuración de DNS en el DNS de su sitio.

Para admitir un dominio ESP, añada el dominio de seguimiento personalizado a la opción de configuración espDomains del objeto config cada vez que se inicialice Singular SDK.

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