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.
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.
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.
// 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.
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
withSingularLinkdo SDK -
O deep link aparece no parâmetro
deeplinkcomisDeferreddefinido comotrue - 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 comofalse - 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:
- Desinstalar a aplicação do dispositivo de teste (se estiver atualmente instalada)
- Redefinir seu identificador de publicidade (IDFA no iOS, GAID no Android)
- Clique no link de rastreamento Singular do dispositivo. Certifique-se de que o link esteja configurado com um valor de link profundo
- Instale e abra o aplicativo
- 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.
// 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.
// 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.