SDK de Unity - Referencia de métodos

Seguir
Avatar
Jared Ornstead
Updated
Documento

SDK de Unity - Referencia de Métodos

Este documento proporciona una referencia completa de todos los métodos disponibles en Singular SDK para aplicaciones Unity. El SDK de Singular Unity envuelve los SDK nativos de iOS y Android, proporcionando una interfaz unificada en C# para atribución móvil, deep linking, seguimiento de ingresos y análisis. Cada método se presenta con una descripción, firma y ejemplos prácticos de uso.

AdRevenue

Método SingularSDK.AdRevenue

Realiza un seguimiento de los ingresos publicitarios de las plataformas de mediación. Este método le permite informar de los ingresos generados por las impresiones de anuncios en su aplicación Unity, respaldando el análisis de atribución y ROI para la monetización de anuncios.

Firma

public static void AdRevenue(string currency, double amount)

Ejemplo de uso

C# 
// Track ad revenue from an ad impression
SingularSDK.AdRevenue("USD", 0.05);

ClearGlobalProperties

Método SingularSDK.ClearGlobalProperties

Elimina todas las propiedades globales establecidas anteriormente. Las propiedades globales son pares clave-valor que se incluyen automáticamente con cada evento rastreado por el SDK.

Firma

public static void ClearGlobalProperties()

Ejemplo de uso

C# 
// Clear all global properties
SingularSDK.ClearGlobalProperties();

Crea un enlace corto de remitente para campañas de atribución de usuario a usuario. Este método genera un enlace corto que los usuarios pueden compartir para realizar un seguimiento de las remisiones y atribuir nuevas instalaciones a remitentes específicos. 

public static void createReferrerShortLink(string baseLink, string referrerName, 
    string referrerId, Dictionary<string, string> passthroughParams, 
    ShortLinkCallback completionHandler)
C# 
// Create a referrer short link
var passthroughParams = new Dictionary<string, string>
{
    { "promo_code", "WELCOME10" },
    { "campaign", "spring_2024" }
};

SingularSDK.createReferrerShortLink(
    "https://yourapp.sng.link/12345",
    "John Doe",
    "user_12345",
    passthroughParams,
    (data, error) =>
    {
        if (error == null)
        {
            Debug.Log("Short link created: " + data);
        }
        else
        {
            Debug.LogError("Error creating short link: " + error);
        }
    }
);

CustomRevenue

Método SingularSDK.CustomRevenue

Rastrea un evento de ingresos personalizado con un nombre de evento especificado. Esto permite realizar un seguimiento de los ingresos procedentes de fuentes distintas a las compras dentro de la aplicación, como suscripciones u otros métodos de monetización.

Firma

public static void CustomRevenue(string eventName, string currency, double amount)

public static void CustomRevenue(Dictionary<string, object> args, 
    string eventName, string currency, double amount)

Ejemplo de uso

C# 
// Track custom revenue event
SingularSDK.CustomRevenue("subscription_renewal", "USD", 9.99);

// Track custom revenue with additional attributes
var attributes = new Dictionary<string, object>
{
    { "subscription_type", "premium" },
    { "billing_period", "monthly" }
};

SingularSDK.CustomRevenue(attributes, "subscription_renewal", "USD", 9.99);

EndSingularSession

Método SingularSDK.EndSingularSession

Finaliza manualmente la sesión actual de Singular. Suele ejecutarse cuando la aplicación pasa a segundo plano si se necesita un control explícito de la gestión de la sesión.

Firma

public static void EndSingularSession()

Ejemplo de uso

C# 
// End the current session
SingularSDK.EndSingularSession();

Evento

Método SingularSDK.Event

Rastrea un evento personalizado en su aplicación Unity. Los eventos pueden ser rastreados sólo con un nombre, o con atributos adicionales como pares clave-valor para un análisis más detallado.

Firma

public static void Event(string name)

public static void Event(Dictionary<string, object> args, string name)

public static void Event(string name, params object[] args)

Ejemplo de uso

C# 
// Track a simple event
SingularSDK.Event("level_completed");

// Track event with dictionary attributes
var attributes = new Dictionary<string, object>
{
    { "level", 5 },
    { "score", 1250 },
    { "time_seconds", 45.3 }
};
SingularSDK.Event(attributes, "level_completed");

// Track event with params array (key-value pairs)
SingularSDK.Event("item_purchased", 
    "item_name", "Golden Sword",
    "item_category", "weapons",
    "price", 4.99);

GetAPID

Método SingularSDK.GetAPID

Devuelve el APID (identificador de plataforma de atribución) de Singular para el dispositivo actual. Singular utiliza internamente este identificador para la atribución y el análisis. Sólo iOS.

Firma

public static string GetAPID()

Ejemplo de uso

C# 
// Get the APID
string apid = SingularSDK.GetAPID();
Debug.Log("APID: " + apid);

GetGlobalProperties

Método SingularSDK.GetGlobalProperties

Recupera todas las propiedades globales configuradas actualmente como una cadena JSON. Las propiedades globales son pares clave-valor que se incluyen automáticamente con cada evento rastreado.

Firma

public static string GetGlobalProperties()

Ejemplo de uso

C# 
// Get all global properties
string globalProps = SingularSDK.GetGlobalProperties();
Debug.Log("Global Properties: " + globalProps);

GetIDFA

Método SingularSDK.GetIDFA

Devuelve el IDFA (identificador para anunciantes) del dispositivo iOS actual. Este método requiere la autorización adecuada de ATT (App Tracking Transparency). Sólo iOS.

Firma

public static string GetIDFA()

Ejemplo de uso

C# 
// Get the IDFA (iOS only)
string idfa = SingularSDK.GetIDFA();
Debug.Log("IDFA: " + idfa);

GetLimitDataSharing

Método SingularSDK.GetLimitDataSharing

Devuelve el estado actual de limitación de uso compartido de datos. Indica si el SDK está limitando actualmente la recopilación y el uso compartido de datos en función de la configuración de privacidad.

Firma

public static bool GetLimitDataSharing()

Ejemplo de uso

C# 
// Check if data sharing is limited
bool isLimited = SingularSDK.GetLimitDataSharing();
Debug.Log("Data sharing limited: " + isLimited);

HandlePushNotification

Método SingularSDK.HandlePushNotification

Procesa las cargas útiles de las notificaciones push para la atribución y la gestión de enlaces profundos. Este método debe invocarse cuando la aplicación recibe una notificación push. Sólo para iOS.

Firma

public static void HandlePushNotification(Dictionary<string, string> pushNotificationPayload)

Ejemplo de uso

C# 
// Handle push notification (iOS only)
var pushPayload = new Dictionary<string, string>
{
    { "aps", "{"alert":"New message"}" },
    { "deep_link", "myapp://promo/spring2024" }
};

SingularSDK.HandlePushNotification(pushPayload);

InAppPurchase

Método SingularSDK.InAppPurchase

Rastrea las compras dentro de la aplicación desde Unity IAP. Este método es compatible con Unity IAP 4.x y 5.x y valida automáticamente los recibos de compra con Apple y Google.

Firma

public static void InAppPurchase(Product product, Dictionary<string, object> attributes)

Ejemplo de uso

C# 
// Track in-app purchase
void OnPurchaseComplete(Product product)
{
    var attributes = new Dictionary<string, object>
    {
        { "category", "consumables" },
        { "location", "main_store" }
    };

    SingularSDK.InAppPurchase(product, attributes);
}

InicializarSingularSDK

Método SingularSDK.InitializeSingularSDK

Inicializa manualmente el Singular SDK. Este método sólo debe invocarse si se ha establecido InitializeOnAwake en false en la configuración del SDK. De lo contrario, el SDK se inicializa automáticamente.

Firma

public static void InitializeSingularSDK()

Ejemplo de uso

C# 
// Manually initialize the SDK (only if InitializeOnAwake = false)
SingularSDK.InitializeSingularSDK();

IsAllTrackingStopped

Método SingularSDK.IsAllTrackingStopped

Devuelve si se ha detenido todo el seguimiento. Cuando se detiene el seguimiento, el SDK no enviará ningún evento ni recopilará ningún dato.

Firma

public static bool IsAllTrackingStopped()

Ejemplo de uso

C# 
// Check if tracking is stopped
bool isTrackingStopped = SingularSDK.IsAllTrackingStopped();
Debug.Log("Tracking stopped: " + isTrackingStopped);

LimitDataSharing

Método SingularSDK.LimitDataSharing

Establece si el SDK debe limitar el uso compartido de datos. Si está activado, el SDK restringirá determinadas actividades de recopilación y uso compartido de datos para cumplir la normativa sobre privacidad.

Firma

public static void LimitDataSharing(bool limitDataSharingValue)

Ejemplo de uso

C# 
// Enable limited data sharing based on user consent
SingularSDK.LimitDataSharing(true);

RegisterDeviceTokenParaDesinstalar

Método SingularSDK.RegisterDeviceTokenForUninstall

Registra el token del dispositivo para el seguimiento de la desinstalación. Esto permite a Singular detectar cuándo los usuarios desinstalan su aplicación. Sólo para iOS.

Firma

public static void RegisterDeviceTokenForUninstall(string APNSToken)

Ejemplo de uso

C# 
// Register APNS token for uninstall tracking (iOS only)
void OnTokenReceived(string token)
{
    SingularSDK.RegisterDeviceTokenForUninstall(token);
}

RestartSingularSession

Método SingularSDK.RestartSingularSession

Reinicia manualmente la sesión de Singular. Suele ejecutarse cuando la aplicación vuelve al primer plano si se necesita un control explícito de la gestión de la sesión.

Firma

public static void RestartSingularSession(string key, string secret)

Ejemplo de uso

C# 
// Restart the session
SingularSDK.RestartSingularSession("SDK KEY", "YOUR_SECRET");

ResumeAllTracking

Método SingularSDK.ResumeAllTracking

Reanuda todo el seguimiento después de haberlo detenido previamente. De este modo, se vuelve a activar el seguimiento de eventos y la recopilación de datos.

Firma

public static void ResumeAllTracking()

Ejemplo de uso

C# 
// Resume tracking
SingularSDK.ResumeAllTracking();

Ingresos

Método SingularSDK.Revenue

Rastrea un evento de ingresos. Este es el método principal para rastrear compras y otros eventos de monetización que no son rastreados automáticamente a través de Unity IAP.

Firma

public static void Revenue(string currency, double amount)

public static void Revenue(Dictionary<string, object> args, 
    string currency, double amount)

Ejemplo de uso

C# 
// Track simple revenue
SingularSDK.Revenue("USD", 9.99);

// Track revenue with attributes
var attributes = new Dictionary<string, object>
{
    { "product_id", "premium_upgrade" },
    { "product_name", "Premium Subscription" },
    { "product_category", "subscriptions" }
};

SingularSDK.Revenue(attributes, "USD", 9.99);

SetAge

Método SingularSDK.SetAge

Establece la edad del usuario para el seguimiento demográfico. La edad debe estar comprendida entre 0 y 100. Sólo para iOS.

Firma

public static void SetAge(int age)

Ejemplo de uso

C# 
// Set user age (iOS only)
SingularSDK.SetAge(28);

SetConversionValueUpdatedHandler

Método SingularSDK.SetConversionValueUpdatedHandler

Establece un controlador de devolución de llamada para las actualizaciones de valores de conversión de SKAdNetwork (iOS 14+). Este controlador se llama cada vez que se actualiza el valor de conversión. Sólo iOS.

Firma

public static void SetConversionValueUpdatedHandler(SingularConversionValueUpdatedHandler handler)

Ejemplo de uso

C# 
// Set conversion value updated handler (iOS only)
SingularSDK.SetConversionValueUpdatedHandler((conversionValue) =>
{
    Debug.Log("Conversion value updated: " + conversionValue);
});

SetConversionValuesUpdatedHandler

Método SingularSDK.SetConversionValuesUpdatedHandler

Establece un controlador de devolución de llamada para las actualizaciones de valores de conversión de SKAdNetwork 4.0+. Este controlador proporciona el valor de conversión, el valor de conversión grueso y el estado de bloqueo. Sólo iOS.

Firma

public static void SetConversionValuesUpdatedHandler(SingularConversionValuesUpdatedHandler handler)

Ejemplo de uso

C# 
// Set conversion values updated handler (iOS only)
SingularSDK.SetConversionValuesUpdatedHandler((conversionValue, coarse, lockWindow) =>
{
    Debug.Log($"CV: {conversionValue}, Coarse: {coarse}, Lock: {lockWindow}");
});

SetCustomUserId

Método SingularSDK.SetCustomUserId

Establece un ID de usuario personalizado para asociarlo a todos los eventos rastreados. Esto le permite vincular los datos de Singular a su propio sistema de identificación de usuarios.

Firma

public static void SetCustomUserId(string customUserId)

Ejemplo de uso

C# 
// Set custom user ID
SingularSDK.SetCustomUserId("user_123456");

SetDeviceCustomUserId

Método SingularSDK.SetDeviceCustomUserId

Establece un ID de usuario personalizado a nivel de dispositivo. Es diferente del ID de usuario personalizado normal y persiste en todas las sesiones de la aplicación a nivel de dispositivo.

Firma

public static void SetDeviceCustomUserId(string customUserId)

Ejemplo de uso

C# 
// Set device-level custom user ID
SingularSDK.SetDeviceCustomUserId("device_user_789");

SetFCMDeviceToken

SingularSDK.SetFCMDeviceToken Método

Establece el token de dispositivo FCM (Firebase Cloud Messaging) para el seguimiento de notificaciones push y la detección de desinstalaciones. Sólo para Android.

Firma

public static void SetFCMDeviceToken(string fcmDeviceToken)

Ejemplo de uso

C# 
// Set FCM token (Android only)
void OnFCMTokenReceived(string token)
{
    SingularSDK.SetFCMDeviceToken(token);
}

SetGender

Método SingularSDK.SetGender

Establece el género del usuario para el seguimiento demográfico. Acepta "m" para hombre o "f" para mujer. Sólo para iOS.

Firma

public static void SetGender(string gender)

Ejemplo de uso

C# 
// Set user gender (iOS only)
SingularSDK.SetGender("f");

SetGlobalProperty

Método SingularSDK.SetGlobalProperty

Establece una propiedad global que se enviará con todos los eventos. Las propiedades globales son pares clave-valor que persisten en varios eventos hasta que se borran o cambian.

Firma

public static bool SetGlobalProperty(string key, string value, bool overrideExisting)

Ejemplo de uso

C# 
// Set a global property
bool success = SingularSDK.SetGlobalProperty("user_level", "premium", true);

// Set multiple global properties
SingularSDK.SetGlobalProperty("app_version", "2.1.0", true);
SingularSDK.SetGlobalProperty("platform", "unity", true);

SetIMEI

Método SingularSDK.SetIMEI

Establece el IMEI del dispositivo para el seguimiento. Esto es útil en regiones donde el rastreo de IMEI está permitido y es preferible. Sólo para Android.

Firma

public static void SetIMEI(string imei)

Ejemplo de uso

C# 
// Set device IMEI (Android only)
SingularSDK.SetIMEI("123456789012345");

SetLimitAdvertisingIdentifiers

SingularSDK.SetLimitAdvertisingIdentifiers Método

Activa el modo de identificadores publicitarios limitados. Esto afecta al modo en que el SDK recopila y utiliza los identificadores de dispositivo para el seguimiento, adecuado para aplicaciones de público mixto.

Firma

public static void SetLimitAdvertisingIdentifiers(bool isEnabled)

Ejemplo de uso

C# 
// Enable limited advertising identifiers mode
SingularSDK.SetLimitAdvertisingIdentifiers(true);

SetSingularDeviceAttributionCallbackHandler

Método SingularSDK.SetSingularDeviceAttributionCallbackHandler

Establece un controlador de devolución de llamada para recibir datos de atribución de dispositivos. Este controlador se invoca cuando los datos de atribución están disponibles, lo que le permite acceder a la información de campaña y origen.

  1. Cree un C# Script AttributionCallback con el código Handler siguiente

  2. Cree un Objeto Emtpy en la Jerarquía y colóquelo debajo del SingularSDKObject

  3. Añada un Componente Script al Objeto Vacío asociando el Script Handler AttributionCallback

Firma

public static void SetSingularDeviceAttributionCallbackHandler(
    SingularDeviceAttributionCallbackHandler handler)

Ejemplo de Uso

C# 
using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using Singular;

public class AttributionCallback : MonoBehaviour, SingularDeviceAttributionCallbackHandler 
{
    void Awake()
    {
        Debug.Log("Registering SingularDeviceAttributionCallbackHandler");
        SingularSDK.SetSingularDeviceAttributionCallbackHandler(this);
    }

    public void OnSingularDeviceAttributionCallback(Dictionary attributionInfo) {
		foreach(var kvp in attributionInfo)
		{
			Debug.Log($"OnSingularDeviceAttributionCallback Key: {kvp.Key}, Value: {kvp.Value}");
		}
	}
}

SetSingularLinkHandler

Método SingularSDK.SetSingularLinkHandler

Establece un controlador de devolución de llamada para Singular Links (enlaces profundos). Este controlador se invoca cuando se resuelve un enlace profundo, proporcionando parámetros de enlace y datos de transferencia.

  1. Cree un Script C# DeepLinkManager con el código Handler de abajo

  2. Cree un Objeto Emtpy en la Jerarquía y colóquelo debajo del SingularSDKObject

  3. Añada un Componente de Script al Objeto Vacío asociando el Script Manejador DeepLinkManager

Firma

public static void SetSingularLinkHandler(SingularLinkHandler linkHandler)

Ejemplo de Uso

C# 
using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using Singular;

public class DeepLinkManager : MonoBehaviour, SingularLinkHandler
{
    void Awake()
    {
        Debug.Log("Registering SingularLink Handler");
        SingularSDK.SetSingularLinkHandler(this);
    }

    public void OnSingularLinkResolved(SingularLinkParams linkParams)
    {
        Debug.Log("SingularLink Resolved");

        // Extract parameters from the tracking link
        string deeplink = linkParams.Deeplink;
        string passthrough = linkParams.Passthrough;
        bool isDeferred = linkParams.IsDeferred;

        // Log the parameters
        Debug.Log($"SingularLink Deeplink: {deeplink ?? "null"}");
        Debug.Log($"SingularLink Passthrough: {passthrough ?? "null"}");
        Debug.Log($"SingularLink is Deferred: {isDeferred}");

        // Handle deep link routing
        if (!string.IsNullOrEmpty(deeplink))
        {
            HandleDeepLink(deeplink, isDeferred);
        }
    }

    private void HandleDeepLink(string url, bool isDeferred)
    {
        // Your deep link routing logic here
        Debug.Log($"SingularLink Routing to: {url} (Deferred: {isDeferred})");

        // Example: Parse the URL and navigate to the appropriate screen
        // if (url.Contains("product"))
        // {
        //     NavigateToProduct(url);
        // }
    }
}

SetSingularSdidAccessorHandler

Método SingularSDK.SetSingularSdidAccessorHandler

Establece un controlador de devolución de llamada para recibir el ID de dispositivo singular (SDID). Este controlador se invoca cuando el SDID está disponible tras la inicialización del SDK.

  1. Cree un C# Script SDIDManager con el siguiente código de Handler

  2. Cree un Objeto Emtpy en la Jerarquía y colóquelo debajo del SingularSDKObject

  3. Añada un Componente Script al Objeto Vacío asociando el Script Handler SDIDManager

Firma

public static void SetSingularSdidAccessorHandler(SingularSdidAccessorHandler handler)

Ejemplo de Uso

C# 
using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using Singular;

public class SDIDManager : MonoBehaviour, SingularSdidAccessorHandler
{
    void Awake()
    {
        Debug.Log("Registering SingularSdidAccessorHandler");
        SingularSDK.SetSingularSdidAccessorHandler(this);
    }

    public void DidSetSdid(string sdid)
    {
        Debug.Log($"SDID Set: {sdid}");
    }

    public void SdidReceived(string sdid)
    {
        Debug.Log($"SDID Set: {sdid}");
        // Store or use the SDID as needed
    }   
}

SkanRegisterAppForAdNetworkAttribution

SingularSDK.SkanRegisterAppForAdNetworkAttribution Método

Registra la aplicación para la atribución SKAdNetwork. Este método debe invocarse al principio del ciclo de vida de la aplicación para la compatibilidad con SKAdNetwork de iOS 14.5+. Sólo iOS.

Firma

public static void SkanRegisterAppForAdNetworkAttribution()

Ejemplo de uso

C# 
// Register for SKAdNetwork attribution (iOS only)
SingularSDK.SkanRegisterAppForAdNetworkAttribution();

SkanUpdateConversionValue

Método SingularSDK.SkanUpdateConversionValue

Actualiza manualmente el valor de conversión de SKAdNetwork. Este método se utiliza cuando está activada la gestión manual del valor de conversión. Sólo para iOS.

Firma

public static bool SkanUpdateConversionValue(int conversionValue)

public static bool SkanUpdateConversionValue(int conversionValue, int coarse, bool lockWindow)

Ejemplo de uso

C# 
// Update conversion value (iOS only)
bool success = SingularSDK.SkanUpdateConversionValue(5);

// Update with coarse value and lock (SKAdNetwork 4.0+)
bool success2 = SingularSDK.SkanUpdateConversionValue(10, 2, false);

StopAllTracking

Método SingularSDK.StopAllTracking

Detiene todo el seguimiento y la recopilación de datos. Cuando se detiene el seguimiento, el SDK no enviará ningún evento ni recopilará ningún dato hasta que se reanude el seguimiento.

Firma

public static void StopAllTracking()

Ejemplo de uso

C# 
// Stop all tracking
SingularSDK.StopAllTracking();

TrackingOptIn

Método SingularSDK.TrackingOptIn

Indica que el usuario ha optado por el seguimiento. Este método debe invocarse cuando el usuario consiente explícitamente la recopilación de datos y el seguimiento.

Firma

public static void TrackingOptIn()

Ejemplo de uso

C# 
// User opted in to tracking
SingularSDK.TrackingOptIn();

TrackingUnder13

Método SingularSDK.TrackingUnder13

Indica que el usuario es menor de 13 años, lo que afecta a la recopilación de datos para cumplir la normativa COPPA (Children's Online Privacy Protection Act).

Firma

public static void TrackingUnder13()

Ejemplo de uso

C# 
// User is under 13 years old
SingularSDK.TrackingUnder13();

UnsetCustomUserId

Método SingularSDK.UnsetCustomUserId

Elimina el identificador de usuario personalizado establecido previamente. Después de llamar a este método, los eventos dejarán de estar asociados a un ID de usuario personalizado hasta que se establezca uno nuevo.

Firma

public static void UnsetCustomUserId()

Ejemplo de uso

C# 
// Remove custom user ID (e.g., on logout)
SingularSDK.UnsetCustomUserId();

UnsetGlobalProperty

Método SingularSDK.UnsetGlobalProperty

Elimina una propiedad global específica por clave. Esto impide que la propiedad se envíe con eventos posteriores.

Firma

public static void UnsetGlobalProperty(string key)

Ejemplo de uso

C# 
// Remove a specific global property
SingularSDK.UnsetGlobalProperty("user_level");