SDK do Cordova - Suporte de ligações diretas

Documento

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.

Observações:

  • Este artigo pressupõe que sua organização está usando Singular Links- a tecnologia de link de rastreamento da Singular. Os clientes mais antigos podem estar usando links de rastreamento herdados.
  • Os destinos de links diretos do seu aplicativo precisam ser configurados na página Aplicativos no Singular (consulte Configurando seu aplicativo para rastreamento de atribuição).

Implementar o manipulador de links do Singular

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

Parâmetros disponíveis:

  • Deep Link (_dl): O URL de destino dentro do seu aplicativo para usuários que clicam no link
  • Deep Link diferido (_ddl): O URL de destino para os utilizadores que instalam a aplicação depois de clicarem no link
  • Passthrough (_p): Dados personalizados passados através do link de rastreamento para contexto adicional

Configuração da plataforma

Configure o código da plataforma nativa para passar dados de deep link para o SDK Singular para rastreamento de atribuição e navegação.

Configuração do Android

Atualizar MainActivity

Habilite o SDK Singular para processar dados relacionados ao lançamento e lidar com links profundos modificando o arquivo MainActivity para passar o objeto Intent para o SDK Singular.

Java
import singular_cordova_sdk.SingularCordovaSdk;

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

O objeto Intent contém informações sobre como e por que seu aplicativo foi lançado, que o Singular usa para rastreamento de atribuição e navegação de link profundo.

Localização: Adicione este código ao seu arquivo de atividade principal, normalmente localizado em platforms/android/app/src/main/java/[your-package]/MainActivity.java


Configuração do iOS

Atualizar AppDelegate

Habilite o Singular SDK para processar dados relacionados ao lançamento e manipular links profundos passando os objetos launchOptions e userActivity para o Singular SDK no seu arquivo 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)
    }
}

Esses métodos garantem que o SDK Singular receba informações críticas sobre como e por que seu aplicativo foi iniciado, que o Singular usa para rastreamento de atribuição e navegação de link profundo.

Localização: Modifique seu arquivo AppDelegate localizado em platforms/ios/[YourAppName]/Classes/AppDelegate.swiftou AppDelegate.m para projetos Objective-C


Configuração do SDK

Configure o SDK do Singular para lidar com links diretos e links diretos adiados implementando o retorno de chamada withSingularLink durante a inicialização.

Adicionar a chamada de retorno withSingularLink

Implementação básica

Configure a chamada de retorno withSingularLink para manipular dados de entrada de links diretos e links diretos adiados durante a inicialização do 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);

Observação: A chamada de retorno withSingularLink é acionada somente quando o aplicativo é aberto por meio de um link singular. Para obter mais informações, consulte as Perguntas frequentes sobre links singulares.


Implementação avançada

Implemente um tratamento abrangente de links diretos com lógica de navegação, análise de dados de passagem e tratamento de erros para aplicativos de produção.

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

Detalhes do parâmetro

Entender os parâmetros fornecidos no retorno de chamada do Singular Link ajuda a criar uma lógica robusta de links diretos.

Parâmetro Tipo de parâmetro Descrição
deeplink Cadeia de caracteres O URL de destino na sua aplicação para os utilizadores que clicam no link (por exemplo, myapp://product/123)
passthrough Cadeia de caracteres Dados personalizados passados através da ligação de seguimento, normalmente codificados em JSON para contexto adicional
isDeferred Booleano Indica se este é um deep link diferido (o utilizador instalou a aplicação depois de clicar no link)

Melhores práticas

  • Analisar URLs com segurança: Valide e higienize sempre os URLs de deep link antes de os utilizar na navegação para evitar redireccionamentos maliciosos
  • Lidar com dados ausentes: Verifique se há valores nulos ou indefinidos antes de acessar os parâmetros do deep link
  • Testar links adiados: Teste cenários de deep link imediatos e diferidos para garantir a navegação adequada após novas instalações
  • Registro para depuração: Habilite o registro detalhado durante o desenvolvimento para verificar se os deep links são recebidos e analisados corretamente
  • Use passthrough para contexto: Aproveite os parâmetros de passagem para enviar contexto adicional, como IDs de campanha, códigos promocionais ou segmentos de utilizadores
  • Coordenar com o marketing: Trabalhe com a sua equipa de marketing para definir e documentar a estrutura de URL de deep link da sua aplicação

Para obter a documentação completa do método, consulte a referência withSingularLink.


Comportamento do manipulador

Entendendo os acionadores de retorno de chamada

O comportamento do retorno de chamada do withSingularLink difere dependendo se o aplicativo foi instalado recentemente ou se já está presente no dispositivo.

Cenário de instalação recente

Em uma instalação recente, não há uma URL aberta quando o aplicativo é iniciado. A Singular deve concluir a atribuição ao último ponto de contato e determinar se o link de rastreamento continha um valor configurado de Deep Link ou Deferred Deep Link (DDL).

Como funciona:

  • O processo de atribuição ocorre quando o SDK da Singular envia a primeira sessão para os servidores da Singular
  • Se aplicável, o valor do deep link é retornado para o manipulador withSingularLink do SDK
  • O deep link aparece no parâmetro deeplink com isDeferred definido como true
  • Esse processo pode levar alguns segundos, pois requer comunicação com o servidor

Cenário já instalado

Se a aplicação já estiver instalada, clicar numa ligação simples abre imediatamente a aplicação. O sistema operacional fornece o URL completo do link de rastreamento, que o SDK Singular analisa durante a inicialização para extrair os valores deeplink e passthrough.

Como funciona:

  • O deep link fica disponível imediatamente quando o manipulador é acionado
  • O parâmetro isDeferred é definido como false
  • Não é necessária nenhuma comunicação com o servidor, resultando numa execução mais rápida do callback

Testando links diretos

Siga estas etapas para testar o comportamento de links diretos diferidos no seu ambiente de desenvolvimento.

Requisitos de teste:

  1. Desinstalar a aplicação do dispositivo de teste (se estiver atualmente instalada)
  2. Redefinir seu identificador de publicidade (IDFA no iOS, GAID no Android)
  3. Clique no link de rastreamento Singular do dispositivo. Certifique-se de que o link esteja configurado com um valor de link profundo
  4. Instale e abra o aplicativo
  5. Verifique se a atribuição é concluída e se o valor DDL é passado para o seu manipulador

Teste de compilação de desenvolvimento: Ao testar com uma versão de desenvolvimento do seu aplicativo com um nome de pacote diferente (por exemplo, com.example.dev em vez de com.example.prod), verifique se o link de rastreamento está configurado especificamente para o nome do pacote do aplicativo de desenvolvimento. Depois de clicar no link de teste, instale a compilação de desenvolvimento diretamente no dispositivo de teste (através de CLI ou IDE), em vez de fazer o download a partir da loja de aplicações.


Recursos avançados

Dados de passagem

Se um parâmetro de passagem (_p) for incluído no link de rastreamento, o parâmetro passthrough do manipulador 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.

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

Encaminhamento de parâmetro de consulta

Para capturar todos os parâmetros de consulta do URL do link de rastreamento, anexe o parâmetro _forward_params=2 ao seu link de rastreamento Singular. Todos os parâmetros de consulta serão incluídos no parâmetro deeplink do manipulador.

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: O retorno de chamada withSingularLink é acionado somente quando o aplicativo é aberto por meio de um link Singular. Lançamentos regulares de aplicativos sem um deep link não acionam o manipulador.