Configuración de propiedades globales

Defina propiedades personalizadas que se adjunten automáticamente a cada sesión y evento enviado desde su aplicación, permitiendo una segmentación detallada de los datos en los informes.

Las propiedades globales le permiten realizar un seguimiento de cualquier usuario, modo de aplicación o información contextual que necesite. Por ejemplo, en una aplicación de juegos, cree una propiedad "Nivel" inicializada a "0" que se actualice a medida que los usuarios progresan. Todas las sesiones y eventos incluyen esta propiedad, permitiéndole analizar sesiones, recuentos de eventos e ingresos desglosados por nivel de usuario.

Especificaciones de la propiedad

Límites y Persistencia

Comprenda las limitaciones y el comportamiento de persistencia de las propiedades globales.

• Máximo de propiedades: Defina hasta 5 propiedades globales por instalación de aplicación.
• Persistencia: Las propiedades persisten entre lanzamientos de aplicaciones con sus valores más recientes hasta que se anulen explícitamente o se desinstale la aplicación.
• Límite de caracteres: Los nombres y valores de las propiedades pueden tener hasta 200 caracteres. Los valores más largos se truncan automáticamente a 200 caracteres.
• Disponibilidad de datos: Las propiedades globales son accesibles en las exportaciones y postbacks a nivel de usuario. Póngase en contacto con su gestor de éxito de clientes de Singular para obtener información actualizada sobre la compatibilidad con informes agregados.

Configuración de propiedades globales en la inicialización

Configurar antes de la inicialización del SDK

Configure las propiedades globales antes de la inicialización del SDK utilizando SetGlobalProperty() para asegurarse de que se incluyen en la sesión inicial.

Dado que las propiedades globales persisten entre lanzamientos de aplicaciones, es posible que ya existan propiedades con valores diferentes. Utilice el parámetro overrideExisting para controlar si el nuevo valor debe anular los valores existentes.

using UnityEngine;
using Singular;

public class SingularInitializer : MonoBehaviour
{
    void Awake()
    {
        // Set global properties before SDK initialization
        SingularSDK.SetGlobalProperty("app_version", Application.version, true);
        SingularSDK.SetGlobalProperty("user_type", "free", true);

        // Manually initialize SDK to ensure properties are in first session
        SingularSDK.InitializeSingularSDK();
    }
}

Firma del Método:

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

Parámetros:

• Clave: Nombre de la propiedad (máximo 200 caracteres)
• value: Valor de la propiedad (máximo 200 caracteres)
• anularExistente: Si se anula una propiedad existente con la misma clave

Gestión de propiedades tras la inicialización

Establecer propiedad global

Añade o actualiza una propiedad global en cualquier momento durante el tiempo de ejecución de la aplicación.

// Set a global property after initialization
bool result = SingularSDK.SetGlobalProperty("player_level", "5", true);

if (result)
{
    Debug.Log("Property set successfully");
}
else
{
    Debug.LogError("Failed to set property - may have reached 5 property limit");
}

Firma del método:

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

Devuelve: true si la propiedad se ha establecido correctamente, false en caso contrario

Obtener propiedades globales

Recupera todas las propiedades globales actualmente establecidas y sus valores como un diccionario.

// Retrieve all global properties
Dictionary<string, string> properties = SingularSDK.GetGlobalProperties();

// Iterate through properties
foreach (KeyValuePair<string, string> property in properties)
{
    Debug.Log($"Property: {property.Key} = {property.Value}");
}

Firma del método:

public static Dictionary<string, string> GetGlobalProperties()

Devuelve: Un diccionario que contiene todos los pares clave-valor de propiedades globales

Desestablecer Propiedad Global

Elimina una propiedad global específica por su clave.

// Remove a specific global property
SingularSDK.UnsetGlobalProperty("player_level");

Firma del método:

public static void UnsetGlobalProperty(string key)

Parámetros:

• Clave: El nombre de la propiedad a eliminar

Borrar todas las propiedades globales

Elimina todas las propiedades globales a la vez.

// Remove all global properties
SingularSDK.ClearGlobalProperties();

Firma del método:

public static void ClearGlobalProperties()

Ejemplo de implementación

Patrón de uso completo

Realiza un seguimiento de las propiedades específicas de la aplicación y del usuario durante todo el ciclo de vida de la aplicación.

using UnityEngine;
using Singular;

public class GlobalPropertiesManager : MonoBehaviour
{
    void Awake()
    {
        // Set app-level global properties before initialization
        SingularSDK.SetGlobalProperty("app_version", Application.version, true);
        
        // Initialize SDK
        SingularSDK.InitializeSingularSDK();
    }
    
    // Set third-party identifier on login
    public void OnUserLogin(string thirdPartyUserId)
    {
        bool success = SingularSDK.SetGlobalProperty("third_party_identifier", thirdPartyUserId, true);
        
        if (success)
        {
            Debug.Log("Third-party identifier set");
        }
    }
    
    // Clear third-party identifier on logout
    public void OnUserLogout()
    {
        SingularSDK.UnsetGlobalProperty("third_party_identifier");
        Debug.Log("Third-party identifier cleared");
    }
}