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 las plataformas iOS y Android.
Notas:
- Esta guía asume que su organización está utilizando Singular Links- la tecnología de enlaces de seguimiento de Singular lanzada en 2019. Los clientes más antiguos pueden estar usando enlaces de seguimiento heredados.
- Los destinos de enlaces profundos de su app deben configurarse en la página Apps en Singular (consulte Configuración de URL de enlaces profundos).
Configuración del SDK
Implementación del gestor de enlaces de Singular
El SDK de Singular proporciona un mecanismo de manejador basado en delegado para recuperar parámetros de enlace profundo, enlace profundo diferido y passthrough de los enlaces de seguimiento de Singular cuando se abre tu app.
Parámetros disponibles:
- Enlace profundo: La URL de destino dentro de su aplicación para los usuarios que hagan clic en el enlace (configurada en la página Gestionar enlaces).
- Passthrough: Datos personalizados pasados a través del enlace de seguimiento para contexto adicional o metadatos de campaña.
- EsDeferido: Indica si el enlace es un enlace profundo diferido (verdadero para nuevas instalaciones, falso para instalaciones existentes).
Añada el gestor de enlaces profundos a su aplicación
Configure el gestor de enlaces profundos para procesar los datos de enlaces profundos entrantes cuando se inicie su aplicación. Esto debe hacerse antes de inicializar Singular SDK.
Pasos de implementación
- Añada los includes de Singular necesarios al archivo de cabecera de su clase.
- Implemente un método para gestionar la llamada de retorno OnSingularLinksResolved.
- Cree y registre el objeto USingularDelegates antes de inicializar SDK.
-
Registre su método handler utilizando
OnSingularLinksResolved.AddDynamic(). - Procese los parámetros de enlace profundo en su método handler.
// Add to the include section of your class header
#include "SingularLinkParams.h"
#include "SingularDelegates.h"
// In your class header, declare the handler method
UFUNCTION()
void OnSingularLinksResolved(const FSingularLinkParams& LinkParams);
// In your class implementation file, implement the handler method
void UYourGameInstance::OnSingularLinksResolved(const FSingularLinkParams& LinkParams)
{
// Extract parameters from the tracking link
const FString Deeplink = LinkParams.SingularLinksParams["deeplink"];
const FString Passthrough = LinkParams.SingularLinksParams["passthrough"];
const bool IsDeferred = LinkParams.SingularLinksParams["isDeferred"] == "true";
// Log the parameters
UE_LOG(LogTemp, Log, TEXT("Deep Link Resolved"));
UE_LOG(LogTemp, Log, TEXT("Deeplink: %s"), *Deeplink);
UE_LOG(LogTemp, Log, TEXT("Passthrough: %s"), *Passthrough);
UE_LOG(LogTemp, Log, TEXT("Is Deferred: %s"), IsDeferred ? TEXT("true") : TEXT("false"));
// Handle deep link routing
if (!Deeplink.IsEmpty())
{
HandleDeepLinkNavigation(Deeplink, IsDeferred);
}
}
void UYourGameInstance::HandleDeepLinkNavigation(const FString& Url, bool IsDeferred)
{
// Your deep link routing logic
UE_LOG(LogTemp, Log, TEXT("Routing to: %s (Deferred: %s)"),
*Url, IsDeferred ? TEXT("true") : TEXT("false"));
// Example: Parse the URL and navigate to appropriate content
if (Url.Contains(TEXT("product")))
{
NavigateToProduct(Url);
}
else if (Url.Contains(TEXT("promo")))
{
NavigateToPromotion(Url);
}
else
{
NavigateToHome();
}
}
// Register the delegate BEFORE initializing the Singular SDK
void UYourGameInstance::InitializeSingular()
{
// Create the delegates object
USingularDelegates* SingularDelegates =
CreateDefaultSubobject<USingularDelegates>(TEXT("SingularLinksHandler"));
// Register the deep link handler
SingularDelegates->OnSingularLinksResolved.AddDynamic(
this,
&UYourGameInstance::OnSingularLinksResolved
);
UE_LOG(LogTemp, Log, TEXT("Singular Link Handler registered"));
// Now initialize the SDK
bool Success = USingularSDKBPLibrary::Initialize(
TEXT("YOUR_SDK_KEY"),
TEXT("YOUR_SDK_SECRET"),
60, // Session timeout
TEXT(""), // Custom user ID
true, // Enable SKAdNetwork
false, // Manual SKAN management
0, // Wait for tracking authorization
false, // OAID collection
true, // Enable logging
3, // Log level
false, // Clipboard attribution
TEXT(""), // Facebook App ID
TEXT("") // Custom SDID
);
if (Success)
{
UE_LOG(LogTemp, Log, TEXT("Singular SDK initialized successfully"));
}
}
Importante: El delegado debe estar registrado antes de llamar a USingularSDKBPLibrary::Initialize(). Si registra el manejador después de la inicialización, no recibirá llamadas de retorno de enlace profundo.
Comportamiento del manejador
Comprensión de la resolución de enlaces profundos
El controlador de enlaces profundos se comporta de forma diferente en función de si la aplicación está recién instalada o ya instalada cuando el usuario pulsa un enlace singular.
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.
Flujo de enlace profundo diferido:
- El usuario hace clic en un enlace de seguimiento de Singular configurado con un valor de enlace profundo.
- El usuario instala y abre la aplicación por primera vez.
- Singular SDK envía la primera sesión a los servidores de Singular.
- La atribución se completa e identifica el enlace profundo del enlace de seguimiento.
-
El valor del enlace profundo vuelve al manejador con
IsDeferred = true.
Pruebade enlaces profundos diferidos:
- Desinstala la aplicación del dispositivo de prueba (si está instalada actualmente).
- iOS: Restablezca su IDFA. Android: Restablezca su ID de publicidad de Google (GAID).
- Haz clic en el enlace de seguimiento Singular del dispositivo (asegúrate de que está configurado con un valor de enlace profundo).
- Instale y abra la aplicación.
La atribución debería completarse correctamente y el valor de enlace profundo diferido se pasará a su controlador.
Consejo para pruebas de desarrollo: Cuando pruebe enlaces profundos con una compilación de desarrollo que utilice un nombre de paquete o ID de paquete diferente, configure el enlace de seguimiento específicamente para el identificador de la aplicación de desarrollo. Después de hacer clic en el enlace de prueba, instale la compilación de desarrollo directamente en el dispositivo mediante Unreal Engine o herramientas específicas de la plataforma, en lugar de descargar la aplicación de producción de la tienda de aplicaciones.
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 Universal Links (iOS) o Android App Links.
Flujo de enlace profundo inmediato:
- El usuario hace clic en un enlace de seguimiento Singular.
- El sistema operativo proporciona una URL abierta que contiene el enlace de seguimiento Singular completo.
- Durante la inicialización del SDK, Singular analiza la URL.
-
Singular extrae los valores
deeplinkypassthrough. -
Los valores vuelven a través del manejador con
IsDeferred = false.
Parámetros Passthrough
Capture datos adicionales del clic en el enlace de seguimiento utilizando parámetros passthrough para metadatos de campaña, segmentación de usuarios o información personalizada.
Si se incluye un parámetro passthrough (_p) en el enlace de seguimiento, el parámetro Passthrough del manipulador contiene los datos correspondientes.
void UYourGameInstance::OnSingularLinksResolved(const FSingularLinkParams& LinkParams)
{
// Extract passthrough data
const FString PassthroughData = LinkParams.SingularLinksParams["passthrough"];
if (!PassthroughData.IsEmpty())
{
// Parse JSON passthrough data
TSharedPtr<FJsonObject> JsonObject;
TSharedRef<TJsonReader<>> Reader = TJsonReaderFactory<>::Create(PassthroughData);
if (FJsonSerializer::Deserialize(Reader, JsonObject) && JsonObject.IsValid())
{
// Extract campaign metadata
FString CampaignId;
if (JsonObject->TryGetStringField(TEXT("campaign_id"), CampaignId))
{
UE_LOG(LogTemp, Log, TEXT("Campaign ID: %s"), *CampaignId);
}
FString UserSegment;
if (JsonObject->TryGetStringField(TEXT("segment"), UserSegment))
{
UE_LOG(LogTemp, Log, TEXT("User Segment: %s"), *UserSegment);
}
FString PromoCode;
if (JsonObject->TryGetStringField(TEXT("promo_code"), PromoCode))
{
UE_LOG(LogTemp, Log, TEXT("Promo Code: %s"), *PromoCode);
ApplyPromoCode(PromoCode);
}
// Use the data in your app
ApplyCampaignSettings(CampaignId, UserSegment);
}
else
{
UE_LOG(LogTemp, Warning, TEXT("Failed to parse passthrough data"));
}
}
}
void UYourGameInstance::ApplyCampaignSettings(const FString& CampaignId, const FString& Segment)
{
// Your campaign-specific logic
UE_LOG(LogTemp, Log, TEXT("Applying campaign settings for: %s (Segment: %s)"),
*CampaignId, *Segment);
}
Ejemplo de URL Passthrough:
https://yourapp.sng.link/A1b2c/abc123?_dl=myapp://product/123&_p={"campaign_id":"summer2025","segment":"premium","promo_code":"SAVE20"}
El manejador recibirá el parámetro passthrough que contiene la cadena JSON con los metadatos de la campaña.
FSingularLinkParams Referencia
Detalles del parámetro
El objeto FSingularLinkParams contiene detalles del enlace de seguimiento pasados a su controlador de enlace profundo.
| Parámetro | Tipo | Descripción |
| deeplink | FString | La URL de destino del enlace profundo, configurada en la página Gestionar enlaces de Singular. Este valor dirige a los usuarios a un contenido específico de la aplicación. |
| passthrough | FString | Parámetros de transferencia añadidos al enlace de seguimiento, normalmente utilizados para metadatos de campaña, segmentación de usuarios o datos personalizados que su aplicación necesita procesar. |
| isDeferred | bool |
Indica si el enlace está configurado como enlace profundo diferido. Devuelve true para nuevas instalaciones (diferidas), false para instalaciones existentes (inmediatas). |
Firma del método
// Callback method signature for Singular Links
void OnSingularLinksResolved(const FSingularLinkParams& linkParams)
// Access parameters using the SingularLinksParams map:
const FString Deeplink = linkParams.SingularLinksParams["deeplink"];
const FString Passthrough = linkParams.SingularLinksParams["passthrough"];
const bool IsDeferred = linkParams.SingularLinksParams["isDeferred"] == "true";
Implementación del enrutamiento de enlaces profundos
Creación de un enrutador de enlaces profundos
Implemente un sistema centralizado de enrutamiento de enlaces profundos para dirigir a los usuarios a contenidos específicos basándose en la estructura de URL de los enlaces profundos.
// Deep Link Router class implementation
class UDeepLinkRouter : public UObject
{
public:
void RouteDeepLink(const FString& DeepLinkUrl, bool IsDeferred)
{
UE_LOG(LogTemp, Log, TEXT("Routing deep link: %s (Deferred: %s)"),
*DeepLinkUrl, IsDeferred ? TEXT("true") : TEXT("false"));
// Parse the URL scheme
if (DeepLinkUrl.StartsWith(TEXT("myapp://product/")))
{
FString ProductId = ExtractParameter(DeepLinkUrl, TEXT("myapp://product/"));
NavigateToProduct(ProductId);
}
else if (DeepLinkUrl.StartsWith(TEXT("myapp://category/")))
{
FString CategoryName = ExtractParameter(DeepLinkUrl, TEXT("myapp://category/"));
NavigateToCategory(CategoryName);
}
else if (DeepLinkUrl.StartsWith(TEXT("myapp://promo")))
{
NavigateToPromotions();
}
else if (DeepLinkUrl.StartsWith(TEXT("myapp://profile")))
{
NavigateToUserProfile();
}
else
{
// Default fallback
UE_LOG(LogTemp, Warning, TEXT("Unknown deep link format, navigating to home"));
NavigateToHome();
}
// Track deep link usage
TrackDeepLinkEvent(DeepLinkUrl, IsDeferred);
}
private:
FString ExtractParameter(const FString& Url, const FString& Prefix)
{
FString Param;
if (Url.Split(Prefix, nullptr, &Param))
{
// Remove query parameters if present
FString CleanParam;
if (Param.Split(TEXT("?"), &CleanParam, nullptr))
{
return CleanParam;
}
return Param;
}
return FString();
}
void NavigateToProduct(const FString& ProductId)
{
UE_LOG(LogTemp, Log, TEXT("Navigating to product: %s"), *ProductId);
// Your product screen navigation logic
}
void NavigateToCategory(const FString& CategoryName)
{
UE_LOG(LogTemp, Log, TEXT("Navigating to category: %s"), *CategoryName);
// Your category screen navigation logic
}
void NavigateToPromotions()
{
UE_LOG(LogTemp, Log, TEXT("Navigating to promotions"));
// Your promotions screen navigation logic
}
void NavigateToUserProfile()
{
UE_LOG(LogTemp, Log, TEXT("Navigating to user profile"));
// Your profile screen navigation logic
}
void NavigateToHome()
{
UE_LOG(LogTemp, Log, TEXT("Navigating to home screen"));
// Your home screen navigation logic
}
void TrackDeepLinkEvent(const FString& DeepLink, bool IsDeferred)
{
// Track deep link usage with Singular
TMap<FString, FString> EventAttributes;
EventAttributes.Add(TEXT("deep_link_url"), DeepLink);
EventAttributes.Add(TEXT("is_deferred"), IsDeferred ? TEXT("true") : TEXT("false"));
USingularSDKBPLibrary::EventWithAttributes(
TEXT("deep_link_opened"),
EventAttributes
);
}
};
Práctica recomendada: Realice un seguimiento de las aperturas de enlaces profundos como eventos personalizados en Singular para medir la eficacia de sus campañas de enlaces profundos y comprender qué contenido genera más participación.
Consideraciones importantes
Notas de implementación
- Momento de registro: Registre siempre el controlador de enlaces profundos antes de inicializar Singular SDK. El controlador debe estar en su lugar antes de que el SDK procese el enlace de seguimiento.
- Seguridad de subprocesos: La llamada de retorno del controlador puede ejecutarse en un subproceso en segundo plano. Asegúrese de que las actualizaciones de la interfaz de usuario o la lógica de navegación se envían al subproceso del juego utilizando los mecanismos de seguridad de subprocesos de Unreal Engine.
-
Esquemas de URL: Diseñe esquemas de URL coherentes para sus enlaces profundos (por ejemplo,
myapp://product/,myapp://category/) para simplificar la lógica de enrutamiento y el mantenimiento. - Manipulación de errores: Implemente siempre una navegación alternativa (normalmente a la pantalla de inicio) para los enlaces profundos no reconocidos o malformados, con el fin de evitar fallos en la aplicación o una mala experiencia de usuario.
- Probar ambos flujos: Pruebe tanto los enlaces profundos inmediatos (aplicación instalada) como los enlaces profundos diferidos (nueva instalación) para garantizar una gestión adecuada en todos los escenarios.
- Validación de parámetros: Valide todos los parámetros extraídos de los enlaces profundos antes de utilizarlos para evitar problemas de seguridad o bloqueos por URL maliciosas o malformadas.
- Configuración de plataformas: Complete la configuración específica de la plataforma (iOS Universal Links, Android App Links) como se documenta en la guía Singular Links Prerequisites.
Lista de comprobación de producción: Antes de lanzar campañas de deep linking, verifique: (1) Handler registrado antes de la inicialización del SDK, (2) Configuración específica de la plataforma completa, (3) Deep links configurados en Singular dashboard, (4) Lógica de enrutamiento maneja todos los patrones de URL esperados, (5) Flujos inmediatos y diferidos probados con éxito.