SDK de Cordova: compatibilidad con enlaces profundos

Seguir
Avatar
Jared Ornstead
Updated
Documento

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.

Notas:

  • Este artículo asume que su organización está utilizando Singular Links- la tecnología de enlaces de seguimiento de Singular. Los clientes más antiguos pueden estar utilizando enlaces de seguimiento heredados.
  • Los destinos de enlaces profundos de su aplicación deben configurarse en la página Aplicaciones de Singular (consulte Configuración de su aplicación para el seguimiento de atribución).

Implementación de Singular Links Handler

El controlador de SingularLink 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 (_dl): La URL de destino dentro de su aplicación para los usuarios que hacen clic en el enlace
  • Enlace profundo diferido (_ddl): La URL de destino para los usuarios que instalan la aplicación después de hacer clic en el enlace
  • Passthrough (_p): Datos personalizados pasados a través del enlace de seguimiento para un contexto adicional

Configuración de la plataforma

Configure el código nativo de la plataforma para pasar los datos del enlace profundo al SDK de Singular para el seguimiento de atribución y la navegación.

Configuración Android

Actualizar MainActivity

Habilite Singular SDK para procesar los datos relacionados con el lanzamiento y gestionar los enlaces profundos modificando el archivo MainActivity para pasar el objeto Intent a Singular SDK.

Java 
import singular_cordova_sdk.SingularCordovaSdk;

@Override
public void onNewIntent(Intent intent) {
    SingularCordovaSdk.handleNewIntent(intent);
}

El objeto Intent contiene información sobre cómo y por qué se lanzó su aplicación, que Singular utiliza para el seguimiento de atribución y la navegación de enlaces profundos.

Ubicación: Añada este código a su archivo de actividad principal, que normalmente se encuentra en platforms/android/app/src/main/java/[your-package]/MainActivity.java.

Configuración de iOS

Actualizar AppDelegate

Habilite Singular SDK para procesar los datos relacionados con el lanzamiento y gestionar los enlaces profundos pasando los objetos launchOptions y userActivity a Singular SDK en su archivo AppDelegate.

Swift 
import UIKit
import SingularCordovaSdk

class AppDelegate: UIResponder, UIApplicationDelegate {
    
    var window: UIWindow?
    var viewController: MainViewController?
    
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        // Initialize window
        window = UIWindow(frame: UIScreen.main.bounds)
        
        // Configure view controller
        viewController = MainViewController()
        window?.rootViewController = viewController
        
        // Initialize Singular SDK with launch options
        SingularCordovaSdk.setLaunchOptions(launchOptions)
        
        // Make window visible
        window?.makeKeyAndVisible()
        
        return true
    }
    
    func application(
        _ application: UIApplication,
        continue userActivity: NSUserActivity,
        restorationHandler: @escaping ([Any]?) -> Void
    ) -> Bool {
        return SingularCordovaSdk.startSession(with: userActivity)
    }
}

Estos métodos garantizan que Singular SDK reciba información crítica sobre cómo y por qué se lanzó su aplicación, que Singular utiliza para el seguimiento de atribución y la navegación de enlaces profundos.

Ubicación: Modifique su archivo AppDelegate ubicado en platforms/ios/[YourAppName]/Classes/AppDelegate.swifto AppDelegate.m para proyectos Objective-C.

Configuración del SDK

Configure el SDK de Singular para gestionar los enlaces profundos y los enlaces profundos diferidos implementando la devolución de llamada withSingularLink durante la inicialización.

Añadir callback withSingularLink

Implementación básica

Configure la llamada de retorno withSingularLink para gestionar los datos entrantes de enlaces profundos y enlaces profundos diferidos durante la inicialización del SDK.

JavaScript 
// Create configuration
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
);

// Define link handler function
var linkHandler = function(data) {
  var deeplink = data.deeplink;
  var passthrough = data.passthrough;
  var isDeferred = data.isDeferred;
  
  console.log('Deep link:', deeplink);
  console.log('Passthrough:', passthrough);
  console.log('Is deferred:', isDeferred);
  
  // Add link handling logic here
  if (deeplink) {
    handleDeepLink(deeplink, isDeferred);
  }
};

// Attach link handler to configuration
singularConfig.withSingularLink(linkHandler);

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(singularConfig);

Nota: La devolución de llamada withSingularLink sólo se activa cuando la aplicación se abre a través de un Singular Link. Para obtener más información, consulte las preguntas frecuentes sobre Singular Links.

Implementación avanzada

Implemente una gestión completa de los enlaces profundos con lógica de navegación, análisis de datos transferidos y gestión de errores para aplicaciones de producción.

JavaScript 
document.addEventListener('deviceready', initializeApp, false);

function initializeApp() {
  // Create configuration
  var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
    'YOUR_SDK_KEY',
    'YOUR_SDK_SECRET'
  );
  
  // Configure deep link handler
  config.withSingularLink(function(params) {
    console.log('=== Singular Link Resolved ===');
    console.log('Full params:', JSON.stringify(params));
    
    var deeplink = params.deeplink;
    var passthrough = params.passthrough;
    var isDeferred = params.isDeferred;
    
    // Log for debugging
    console.log('Deep link:', deeplink || 'null');
    console.log('Passthrough:', passthrough || 'null');
    console.log('Is deferred:', isDeferred);
    
    // Handle passthrough data
    if (passthrough) {
      handlePassthroughData(passthrough);
    }
    
    // Handle deep link navigation
    if (deeplink) {
      handleDeepLinkNavigation(deeplink, isDeferred);
    }
  });
  
  // Initialize SDK
  cordova.plugins.SingularCordovaSdk.init(config);
}

function handlePassthroughData(passthroughString) {
  try {
    var data = JSON.parse(passthroughString);
    
    // Apply promo code if present
    if (data.promo_code) {
      applyPromoCode(data.promo_code);
    }
    
    // Set user segment
    if (data.segment) {
      setUserSegment(data.segment);
    }
    
    // Track campaign
    if (data.campaign_id) {
      trackCampaign(data.campaign_id);
    }
  } catch (error) {
    console.error('Error parsing passthrough:', error);
  }
}

function handleDeepLinkNavigation(url, isDeferred) {
  // Parse URL to extract route and parameters
  var urlObj = parseDeepLink(url);
  
  console.log('Navigating to: ' + urlObj.route);
  console.log('Parameters:', urlObj.params);
  console.log('Deferred install:', isDeferred);
  
  // Route based on deep link structure
  switch (urlObj.route) {
    case 'product':
      navigateToProduct(urlObj.params.id);
      break;
    case 'promo':
      navigateToPromo(urlObj.params.code);
      break;
    case 'category':
      navigateToCategory(urlObj.params.name);
      break;
    default:
      navigateToHome();
  }
}

function parseDeepLink(url) {
  // Parse myapp://product/123?variant=blue
  var parts = url.split('?');
  var path = parts[0];
  var queryString = parts[1];
  
  var pathParts = path.replace(/^[^:]+:\/\//, '').split('/');
  var route = pathParts[0];
  
  // Parse parameters
  var params = {};
  
  // Add path parameters
  if (pathParts.length > 1) {
    params.id = pathParts[1];
  }
  
  // Add query parameters
  if (queryString) {
    queryString.split('&').forEach(function(pair) {
      var keyValue = pair.split('=');
      params[keyValue[0]] = decodeURIComponent(keyValue[1]);
    });
  }
  
  return { route: route, params: params };
}

// Navigation functions
function navigateToProduct(productId) {
  console.log('Navigating to product:', productId);
  // Your navigation logic
}

function navigateToPromo(promoCode) {
  console.log('Navigating to promo:', promoCode);
  // Your navigation logic
}

function navigateToCategory(categoryName) {
  console.log('Navigating to category:', categoryName);
  // Your navigation logic
}

function navigateToHome() {
  console.log('Navigating to home');
  // Your navigation logic
}

// Utility functions
function applyPromoCode(code) {
  console.log('Applying promo code:', code);
}

function setUserSegment(segment) {
  console.log('Setting user segment:', segment);
}

function trackCampaign(campaignId) {
  console.log('Tracking campaign:', campaignId);
}

Detalles de los parámetros

Comprender los parámetros proporcionados en la devolución de llamada de Singular Link le ayudará a crear una lógica de enlace profundo sólida.

Parámetro Tipo Descripción
deeplink Cadena La URL de destino dentro de tu aplicación para los usuarios que hagan clic en el enlace (por ejemplo, myapp://product/123)
passthrough Cadena Datos personalizados pasados a través del enlace de seguimiento, normalmente codificados en JSON para un contexto adicional
isDeferred Booleano Indica si se trata de un enlace profundo diferido (el usuario instala la aplicación después de hacer clic en el enlace)

Buenas prácticas

  • Analice las URL de forma segura: Valide y desinfecte siempre las URL de los enlaces profundos antes de utilizarlas para la navegación a fin de evitar redireccionamientos malintencionados.
  • Gestione los datos que faltan: Compruebe si hay valores nulos o indefinidos antes de acceder a los parámetros de los enlaces profundos.
  • Pruebe los enlaces diferidos: Pruebe tanto los enlaces profundos inmediatos como los diferidos para garantizar una navegación correcta después de nuevas instalaciones.
  • Registro para depuración: Habilite el registro detallado durante el desarrollo para verificar que los enlaces profundos se reciben y analizan correctamente.
  • Utilice Passthrough para el contexto: Aproveche los parámetros passthrough para enviar contexto adicional como ID de campaña, códigos promocionales o segmentos de usuarios.
  • Coordine con Marketing: Trabaje con su equipo de marketing para definir y documentar la estructura de URL de enlaces profundos de su aplicación.

Para obtener la documentación completa del método, consulte la referencia withSingularLink.

Comportamiento del controlador

Comprensión de los activadores de devolución de llamada

El comportamiento de la devolución de llamada de withSingularLink varía en función de si la aplicación se acaba de instalar o ya está presente en el dispositivo.

Escenario de instalación reciente

En una instalación nueva, no hay ninguna URL abierta cuando se inicia la aplicación. Singular debe completar la atribución al último punto de contacto y determinar si el enlace de seguimiento contenía un valor de enlace profundo o de enlace profundo diferido (DDL) configurado.

Cómo funciona:

  • El proceso de atribución se produce cuando el SDK de Singular envía la primera sesión a los servidores de Singular.
  • Si procede, el valor del enlace profundo se devuelve al gestor del SDK withSingularLink
  • El enlace profundo aparece en el parámetro deeplink con isDeferred ajustado a true
  • Este proceso puede tardar unos segundos ya que requiere comunicación con el servidor

Escenario ya instalado

Si la aplicación ya está instalada, al hacer clic en un Enlace Singular se abre la aplicación inmediatamente. El sistema operativo proporciona la URL completa del enlace de seguimiento, que Singular SDK analiza durante la inicialización para extraer los valores deeplink y passthrough.

Cómo funciona:

  • El enlace profundo está disponible inmediatamente cuando se activa el controlador
  • El parámetro isDeferred se establece en false
  • No se requiere comunicación con el servidor, lo que acelera la ejecución de la llamada de retorno.

Prueba de enlaces profundos

Siga estos pasos para probar el comportamiento de los enlaces profundos diferidos en su entorno de desarrollo.

Requisitos de la prueba:

  1. Desinstalar la aplicación del dispositivo de prueba (si está instalada actualmente).
  2. Restablezca su identificador de publicidad (IDFA en iOS, GAID en Android)
  3. Haga clic en el enlace de seguimiento Singular desde el dispositivo. Asegúrese de que el enlace está configurado con un valor de enlace profundo
  4. Instale y abra la aplicación
  5. Verifique que la atribución se completa y el valor DDL se pasa a su controlador

Pruebas de desarrollo: Cuando realice pruebas con una versión de desarrollo de su aplicación con un nombre de paquete diferente (por ejemplo, com.example.dev en lugar de com.example.prod), asegúrese de que el enlace de seguimiento esté configurado específicamente para el nombre de paquete de la aplicación de desarrollo. Después de hacer clic en el enlace de prueba, instale la versión de desarrollo directamente en el dispositivo de prueba (mediante CLI o IDE) en lugar de descargarla de la tienda de aplicaciones.

Funciones avanzadas

Paso de datos

Si se incluye un parámetro passthrough (_p) en el enlace de seguimiento, el parámetro passthrough del controlador 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.

JavaScript 
// Example tracking link with passthrough:
// https://example.sng.link/A?_dl=myapp://product/123&_p={"campaign":"summer","promo":"SAVE20"}

singularConfig.withSingularLink(function(data) {
  var deeplink = data.deeplink;
  var passthrough = data.passthrough;
  
  if (passthrough) {
    // Parse JSON passthrough data
    var passthroughData = JSON.parse(passthrough);
    console.log('Campaign:', passthroughData.campaign);
    console.log('Promo code:', passthroughData.promo);
  }
});

Reenvío de parámetros de consulta

Para capturar todos los parámetros de consulta de la URL del enlace de seguimiento, añada el parámetro _forward_params=2 a su enlace de seguimiento Singular. Todos los parámetros de consulta se incluirán en el parámetro deeplink del controlador.

JavaScript 
// Example tracking link with parameter forwarding:
// https://example.sng.link/A?_dl=myapp://product&_forward_params=2&category=electronics&sort=price

singularConfig.withSingularLink(function(data) {
  var deeplink = data.deeplink;
  // deeplink will contain: myapp://product?category=electronics&sort=price
  
  console.log('Deep link with parameters:', deeplink);
  // Parse and use the forwarded parameters
});

Importante: La llamada de retorno withSingularLink sólo se activa cuando la aplicación se abre a través de un enlace Singular. Los lanzamientos normales de aplicaciones sin un enlace profundo no activarán el controlador.