Definir propriedades globais

Defina propriedades personalizadas que se ligam automaticamente a todas as sessões e eventos enviados da sua aplicação, permitindo uma segmentação detalhada dos dados nos relatórios.

As propriedades globais permitem-lhe controlar qualquer utilizador, modo de aplicação ou informação contextual de que necessite. Por exemplo, numa aplicação de jogos, crie uma propriedade "Nível" inicializada como "0" que é actualizada à medida que os utilizadores progridem. Todas as sessões e eventos incluem esta propriedade, permitindo-lhe analisar sessões, contagens de eventos e receitas discriminadas por nível de utilizador.

Especificações da propriedade

Limites e persistência

Compreenda as restrições e o comportamento de persistência das propriedades globais.

• Máximo de propriedades: Defina até 5 propriedades globais por instalação de aplicativo
• Persistência: As propriedades persistem entre lançamentos de aplicações com os seus valores mais recentes até serem explicitamente desactivadas ou a aplicação ser desinstalada
• Limite de caracteres: Os nomes e valores das propriedades podem ter até 200 caracteres. Os valores mais longos são automaticamente truncados para 200 caracteres
• Disponibilidade de dados: As propriedades globais estão acessíveis em exportações e postbacks ao nível do utilizador. Entre em contato com o gerente de sucesso do cliente da Singular para obter atualizações sobre o suporte a relatórios agregados

Configuração de propriedades globais na inicialização

Configurar antes da inicialização do SDK

Defina as propriedades globais antes da inicialização do SDK usando SetGlobalProperty() para garantir que elas sejam incluídas na sessão inicial.

Como as propriedades globais persistem entre as inicializações de aplicativos, as propriedades podem já existir com valores diferentes. Utilize o parâmetro overrideExisting para controlar se o novo valor deve substituir os 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();
    }
}

Assinatura do método:

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

Parâmetros:

• key: Nome da propriedade (máx. 200 caracteres)
• value: Valor da propriedade (máx. 200 caracteres)
• overrideExisting: Se deve substituir uma propriedade existente com a mesma chave

Gerir propriedades após a inicialização

Definir propriedade global

Adicionar ou atualizar uma propriedade global em qualquer ponto durante o tempo de execução da aplicação.

// 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");
}

Assinatura do método:

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

Retorna: true se a propriedade foi definida com êxito, false caso contrário

Obter propriedades globais

Recupera todas as propriedades globais atualmente definidas e os respectivos valores como um Dicionário.

// 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}");
}

Assinatura do método:

public static Dictionary<string, string> GetGlobalProperties()

Retorna: Um Dictionary contendo todos os pares de valores-chave de propriedades globais

Remover propriedade global

Remove uma propriedade global específica pela sua chave.

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

Assinatura do método:

public static void UnsetGlobalProperty(string key)

Parâmetros:

• key: O nome da propriedade a ser removida

Limpar todas as propriedades globais

Remove todas as propriedades globais de uma só vez.

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

Assinatura do método:

public static void ClearGlobalProperties()

Exemplo de implementação

Padrão de utilização completo

Rastrear propriedades de nível de aplicativo e específicas do usuário durante todo o ciclo de vida do aplicativo.

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");
    }
}