SDK de Unreal Engine - Referencia de métodos

El SDK de Unreal Engine de Singular proporciona funciones completas de seguimiento y atribución para las aplicaciones de Unreal Engine. Esta referencia documenta todos los métodos SDK disponibles con sus firmas y ejemplos de uso.

CreateReferrerShortLink

Crear enlace corto de referencia

Genere un enlace corto de Singular que pueda compartirse para realizar un seguimiento de la atribución de usuario a usuario y de las campañas de crecimiento viral.

Firma

static void CreateReferrerShortLink(
    FString baseLink,
    FString referrerName,
    FString referrerId,
    TMap<FString, FString> args
);

Ejemplo de uso

// Create a referrer short link
FString BaseLink = TEXT("https://example.sng.link/abc123");
FString ReferrerName = TEXT("John Doe");
FString ReferrerId = TEXT("user_12345");

TMap<FString, FString> PassthroughParams;
PassthroughParams.Add(TEXT("campaign"), TEXT("summer_promo"));
PassthroughParams.Add(TEXT("level"), TEXT("5"));

USingularSDKBPLibrary::CreateReferrerShortLink(
    BaseLink,
    ReferrerName,
    ReferrerId,
    PassthroughParams
);

DeviceAttributionCallbackHandler

Callback de atribución del dispositivo

Función BETA: Este callback no está disponible de forma general y Singular debe habilitarlo para tu cuenta. Si no se ha habilitado, el delegate nunca se ejecuta. Contacta a tu Customer Success Manager para solicitarlo.

Un delegate multicast asignable desde Blueprint que transmite el resultado de atribución de Singular para la instalación durante la primera sesión del usuario después de instalar. Disponible en Android y en iOS.

Payload: SingularDeviceAttributionData es un mapa de cadena a cadena, por lo que cada valor llega como texto: los campos numéricos que devuelve Singular se convierten antes de que se ejecute el delegate.

Solo se incluyen los campos que tienen valor, así que verifica que la clave exista antes de leerla. La mayoría de las instalaciones devuelve un subconjunto: los campos presentes dependen del touchpoint que Singular haya encontrado.

Clave	Tipo	Notas
`network`	FString	Siempre presente cuando se ejecuta el callback. "Organic" cuando no se encontró ningún touchpoint.
`campaign_id`	FString	Presente cuando el touchpoint lo proporciona.
`campaign_name`	FString	Presente cuando el touchpoint lo proporciona.
`subcampaign_id`	FString	Presente cuando el touchpoint lo proporciona. No está disponible en todas las fuentes.
`subcampaign_name`	FString	Presente cuando el touchpoint lo proporciona. No está disponible en todas las fuentes.
`creative_id`	FString	Presente cuando el touchpoint lo proporciona. No está disponible en todas las fuentes.
`creative_name`	FString	Presente cuando el touchpoint lo proporciona. No está disponible en todas las fuentes.
`passthrough`	FString	Presente cuando el enlace llevaba valores de passthrough.
`match_type`	FString	Presente cuando el touchpoint lo proporciona. Contacta a Singular si necesitas el conjunto de valores.
`click_timestamp`	FString	Presente cuando el touchpoint lo proporciona. Microsegundos epoch: divide entre 1.000.000 para obtener segundos.

Firma

// Blueprint-assignable delegate on USingularDelegates
UPROPERTY(BlueprintAssignable, Category = "Singular-SDK")
FDeviceAttributionCallbackHandler DeviceAttributionCallbackHandler;

// Your handler must match this signature
UFUNCTION()
void OnDeviceAttribution(const FSingularDeviceAttributionCallbackHandler& AttributionData);

Ejemplo de uso

// Bind the delegate, for example in BeginPlay
void AMyGameMode::BeginPlay()
{
    Super::BeginPlay();

    USingularDelegates* Delegates = FindComponentByClass<USingularDelegates>();
    if (Delegates)
    {
        Delegates->DeviceAttributionCallbackHandler.AddDynamic(
            this, &AMyGameMode::OnDeviceAttribution);
    }
}

// Read the attribution data
void AMyGameMode::OnDeviceAttribution(const FSingularDeviceAttributionCallbackHandler& AttributionData)
{
    for (const TPair<FString, FString>& Pair : AttributionData.SingularDeviceAttributionData)
    {
        UE_LOG(LogTemp, Log, TEXT("%s = %s"), *Pair.Key, *Pair.Value);
    }
}

GetLimitDataSharing

Obtener estado de limitación de uso compartido de datos

Comprueba el estado actual de limitación de uso compartido de datos para el cumplimiento de la privacidad.

Firma

static bool GetLimitDataSharing();

Ejemplo de uso

// Check if data sharing is limited
bool IsLimited = USingularSDKBPLibrary::GetLimitDataSharing();

if (IsLimited)
{
    UE_LOG(LogTemp, Log, TEXT("Data sharing is currently limited"));
}
else
{
    UE_LOG(LogTemp, Log, TEXT("Data sharing is enabled"));
}

Inicializar

Inicializar Singular SDK

Inicializa Singular SDK con parámetros de configuración que incluyen credenciales de API, ajustes de seguimiento y opciones de privacidad.

Firma

static bool Initialize(
    FString apiKey,
    FString apiSecret,
    int sessionTimeout = 60,
    FString customUserId = TEXT(""),
    bool skAdNetworkEnabled = true,
    bool manualSkanConversionManagement = false,
    int waitForTrackingAuthorizationWithTimeoutInterval = 0,
    bool oaidCollection = false,
    bool enableLogging = false,
    int logLevel = 0,
    bool clipboardAttribution = false,
    FString facebookAppId = TEXT(""),
    FString customSdid = TEXT("")
);

Ejemplo de uso

// Initialize SDK with required parameters
FString ApiKey = TEXT("SDK KEY");
FString ApiSecret = TEXT("SDK SECRET");

bool Success = USingularSDKBPLibrary::Initialize(
    ApiKey,
    ApiSecret,
    60,                    // Session timeout in seconds
    TEXT(""),             // Custom user ID (optional)
    true,                 // SKAdNetwork enabled
    false,                // Manual SKAN conversion management
    0,                    // Wait for tracking authorization timeout
    false,                // OAID collection
    true,                 // Enable logging for debugging
    3,                    // Log level (0-5)
    false,                // Clipboard attribution
    TEXT(""),             // Facebook App ID (optional)
    TEXT("")              // Custom SDID (optional)
);

if (Success)
{
    UE_LOG(LogTemp, Log, TEXT("Singular SDK initialized successfully"));
}
else
{
    UE_LOG(LogTemp, Error, TEXT("Failed to initialize Singular SDK"));
}

IsAllTrackingStopped

Comprobar si se ha detenido todo el seguimiento

Determina si se ha detenido todo el seguimiento por motivos de privacidad o por preferencia del usuario.

Firma

static bool IsAllTrackingStopped();

Ejemplo de uso

// Check tracking status
bool IsTrackingStopped = USingularSDKBPLibrary::IsAllTrackingStopped();

if (IsTrackingStopped)
{
    UE_LOG(LogTemp, Warning, TEXT("Tracking is currently stopped"));
    // Update UI to reflect tracking status
}
else
{
    UE_LOG(LogTemp, Log, TEXT("Tracking is active"));
}

LimitDataSharing

Establecer limitación de uso compartido de datos

Controle si los datos del usuario se comparten con terceros para el cumplimiento de la privacidad con normativas como GDPR y CCPA.

Firma

static void LimitDataSharing(bool shouldLimitDataSharing);

Ejemplo de uso

// Limit data sharing when user opts out
USingularSDKBPLibrary::LimitDataSharing(true);
UE_LOG(LogTemp, Log, TEXT("Data sharing has been limited"));

// Enable data sharing when user opts in
USingularSDKBPLibrary::LimitDataSharing(false);
UE_LOG(LogTemp, Log, TEXT("Data sharing has been enabled"));

ReanudarTodoElSeguimiento

Reanudar todo el seguimiento

Vuelva a activar el seguimiento después de que se haya detenido, permitiendo que el SDK reanude la recopilación de datos y la notificación de eventos.

Firma

static void ResumeAllTracking();

Ejemplo de uso

// Resume tracking when user grants consent
USingularSDKBPLibrary::ResumeAllTracking();
UE_LOG(LogTemp, Log, TEXT("Tracking has been resumed"));

EnviarEvento

Enviar evento personalizado

Realice el seguimiento de un evento personalizado por nombre para medir las acciones y el compromiso del usuario dentro de su aplicación.

Firma

static void SendEvent(FString eventName);

Ejemplo de uso

// Track level completion event
USingularSDKBPLibrary::SendEvent(TEXT("level_completed"));

// Track tutorial start
USingularSDKBPLibrary::SendEvent(TEXT("tutorial_start"));

// Track user achievement
USingularSDKBPLibrary::SendEvent(TEXT("achievement_unlocked"));

EnviarEventoConAtributos

Enviar evento personalizado con atributos

Realiza el seguimiento de un evento personalizado con atributos adicionales para proporcionar un contexto detallado sobre las acciones del usuario.

Firma

static void SendEventWithArgs(
    FString eventName,
    TMap<FString, FString> args
);

Ejemplo de uso

// Track level completion with attributes
TMap<FString, FString> LevelAttributes;
LevelAttributes.Add(TEXT("level_name"), TEXT("Dark Forest"));
LevelAttributes.Add(TEXT("level_number"), TEXT("5"));
LevelAttributes.Add(TEXT("time_spent"), TEXT("245"));
LevelAttributes.Add(TEXT("score"), TEXT("8500"));

USingularSDKBPLibrary::SendEventWithArgs(
    TEXT("level_completed"),
    LevelAttributes
);

// Track item purchase with details
TMap<FString, FString> PurchaseAttributes;
PurchaseAttributes.Add(TEXT("item_id"), TEXT("sword_legendary"));
PurchaseAttributes.Add(TEXT("item_category"), TEXT("weapon"));
PurchaseAttributes.Add(TEXT("item_rarity"), TEXT("legendary"));

USingularSDKBPLibrary::SendEventWithArgs(
    TEXT("item_purchased"),
    PurchaseAttributes
);

EnviarIngresos

Enviar evento de ingresos

Realiza un seguimiento de los eventos que generan ingresos con la divisa y el importe para medir el rendimiento de la monetización.

Firma

static void SendRevenue(
    FString eventName,
    FString currency,
    float amount
);

Ejemplo de uso

// Track in-app purchase revenue
USingularSDKBPLibrary::SendRevenue(
    TEXT("coin_pack_purchase"),
    TEXT("USD"),
    4.99f
);

// Track subscription purchase
USingularSDKBPLibrary::SendRevenue(
    TEXT("premium_subscription"),
    TEXT("EUR"),
    9.99f
);

SendRevenueWithArgs

Enviar evento de ingresos con atributos

Realiza un seguimiento de los ingresos con atributos adicionales para proporcionar información detallada sobre la transacción.

Firma

static void SendRevenueWithArgs(
    FString eventName,
    FString currency,
    float amount,
    TMap<FString, FString> args
);

Ejemplo de uso

// Track revenue with transaction details
TMap<FString, FString> TransactionAttributes;
TransactionAttributes.Add(TEXT("product_id"), TEXT("com.game.coins.large"));
TransactionAttributes.Add(TEXT("product_name"), TEXT("Large Coin Pack"));
TransactionAttributes.Add(TEXT("quantity"), TEXT("1"));
TransactionAttributes.Add(TEXT("payment_method"), TEXT("credit_card"));

USingularSDKBPLibrary::SendRevenueWithArgs(
    TEXT("iap_purchase"),
    TEXT("USD"),
    9.99f,
    TransactionAttributes
);

SetCustomUserId

Establecer ID de usuario personalizado

Asigne un identificador de usuario personalizado para realizar un seguimiento de los usuarios en todos los dispositivos y sesiones utilizando su propio sistema de identificación.

Firma

static void SetCustomUserId(FString customUserId);

Ejemplo de uso

// Set custom user ID after login
FString UserId = TEXT("user_abc123xyz");
USingularSDKBPLibrary::SetCustomUserId(UserId);
UE_LOG(LogTemp, Log, TEXT("Custom user ID set: %s"), *UserId);

SetUninstallToken

Establecer token de seguimiento de desinstalación

Registre un token de notificación push para habilitar el seguimiento de desinstalación para medir la retención de usuarios.

Firma

static void SetUninstallToken(FString token);

Ejemplo de uso

// Set push notification token for uninstall tracking
FString PushToken = TEXT("abc123def456...");
USingularSDKBPLibrary::SetUninstallToken(PushToken);
UE_LOG(LogTemp, Log, TEXT("Uninstall token registered"));

SkanGetConversionValue

Obtener valor de conversión de SKAdNetwork

Recupera el valor de conversión SKAdNetwork actual para aplicaciones iOS (sólo iOS).

Firma

static int SkanGetConversionValue();

Ejemplo de uso

// Get current SKAdNetwork conversion value (iOS only)
int ConversionValue = USingularSDKBPLibrary::SkanGetConversionValue();
UE_LOG(LogTemp, Log, TEXT("Current conversion value: %d"), ConversionValue);

SkanRegisterAppForAdNetworkAttribution

Registrar aplicación para la atribución de red publicitaria

Registra la aplicación en el marco SKAdNetwork de Apple para el seguimiento de atribución (sólo iOS).

Firma

static void SkanRegisterAppForAdNetworkAttribution();

Ejemplo de uso

// Register for SKAdNetwork attribution (iOS only)
USingularSDKBPLibrary::SkanRegisterAppForAdNetworkAttribution();
UE_LOG(LogTemp, Log, TEXT("Registered for SKAdNetwork attribution"));

SkanUpdateConversionValue

Actualizar valor de conversión de SKAdNetwork

Actualiza el valor de conversión de SKAdNetwork para reflejar la participación del usuario y la monetización (sólo iOS).

Firma

static bool SkanUpdateConversionValue(int conversionValue);

Ejemplo de uso

// Update conversion value based on user actions (iOS only)
int NewValue = 10;
bool Success = USingularSDKBPLibrary::SkanUpdateConversionValue(NewValue);

if (Success)
{
    UE_LOG(LogTemp, Log, TEXT("Conversion value updated to: %d"), NewValue);
}
else
{
    UE_LOG(LogTemp, Warning, TEXT("Failed to update conversion value"));
}

SkanUpdateConversionValues

Actualizar valores de conversión de SKAdNetwork con valores finos y gruesos

Actualiza SKAdNetwork con el valor de conversión fino, el valor grueso y el estado de bloqueo para iOS 16.1+ (solo iOS).

Firma

static void SkanUpdateConversionValues(
    int conversionValue,
    int coarse,
    bool lock
);

Ejemplo de uso

// Update conversion values with fine and coarse values (iOS 16.1+)
int FineValue = 25;
int CoarseValue = 1;  // 0 = low, 1 = medium, 2 = high
bool Lock = false;    // Set to true to prevent further updates

USingularSDKBPLibrary::SkanUpdateConversionValues(FineValue, CoarseValue, Lock);
UE_LOG(LogTemp, Log, TEXT("Updated conversion values: fine=%d, coarse=%d"), FineValue, CoarseValue);

StopAllTracking

Detener todo el seguimiento

Detener completamente todas las actividades de seguimiento del SDK para cumplir con las preferencias de privacidad del usuario o los requisitos normativos.

Firma

static void StopAllTracking();

Ejemplo de uso

// Stop tracking when user withdraws consent
USingularSDKBPLibrary::StopAllTracking();
UE_LOG(LogTemp, Warning, TEXT("All tracking has been stopped"));

TrackingOptIn

Registrar la aceptación del seguimiento

Notifica a Singular que el usuario ha optado explícitamente por el seguimiento para cumplir con la GDPR.

Firma

static void TrackingOptIn();

Ejemplo de uso

// Record user opt-in for GDPR compliance
USingularSDKBPLibrary::TrackingOptIn();
UE_LOG(LogTemp, Log, TEXT("User has opted in to tracking"));

TrackingUnder13

Marcar usuario como menor de 13 años

Notificar a Singular que el usuario es menor de 13 años para el cumplimiento de COPPA y la protección de la privacidad de los niños.

Firma

static void TrackingUnder13();

Ejemplo de uso

// Mark user as under 13 for COPPA compliance
USingularSDKBPLibrary::TrackingUnder13();
UE_LOG(LogTemp, Log, TEXT("User marked as under 13 years old"));

UnsetCustomUserId

Eliminar ID de usuario personalizado

Borra el ID de usuario personalizado establecido previamente, que se utiliza normalmente al cerrar sesión o cambiar de cuenta.

Firma

static void UnsetCustomUserId();

Ejemplo de uso

// Clear custom user ID on logout
USingularSDKBPLibrary::UnsetCustomUserId();
UE_LOG(LogTemp, Log, TEXT("Custom user ID has been cleared"));