Configurando propriedades globais

Defina propriedades personalizadas que se anexam automaticamente a cada sessão e evento enviado do seu aplicativo, permitindo uma segmentação detalhada de dados nos relatórios.

As propriedades globais permitem rastrear qualquer usuário, modo de aplicativo ou informação contextual de que você precise. Por exemplo, em um aplicativo de jogos, crie uma propriedade "Level" inicializada em "0" que é atualizada conforme os usuários progridem. Todas as sessões e eventos incluem essa propriedade, permitindo que você analise sessões, contagens de eventos e receita divididas por nível de usuário.

Especificações da propriedade

Limites e persistência

Entenda 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 inicializações do aplicativo com seus valores mais recentes até serem explicitamente removidas ou o aplicativo ser desinstalado
• Limite de caracteres: Nomes e valores de propriedades podem ter até 200 caracteres. Valores mais longos são automaticamente truncados em 200 caracteres
• Disponibilidade de dados: As propriedades globais são acessíveis em exportações no nível do usuário e postbacks. Entre em contato com seu Customer Success Manager da Singular para obter atualizações sobre o suporte a relatórios agregados

Configurando propriedades globais na inicialização

Configurar via SingularConfig

Configure as propriedades globais durante a inicialização do SDK usando o método withGlobalProperty antes de chamar Singular.init() .

Como as propriedades globais persistem entre inicializações do aplicativo, propriedades podem já existir com valores diferentes. Use o parâmetro overrideExisting para controlar se o novo valor deve sobrescrever os valores existentes.

// Set global properties during initialization
val config = SingularConfig("SDK_KEY", "SDK_SECRET")
    .withGlobalProperty("MyProperty", "MyValue", true)
    .withGlobalProperty("AnotherProperty", "AnotherValue", true)

Singular.init(applicationContext, config)

// Set global properties during initialization
SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
    .withGlobalProperty("MyProperty", "MyValue", true)
    .withGlobalProperty("AnotherProperty", "AnotherValue", true);

Singular.init(getApplicationContext(), config);

Assinatura do método:

public SingularConfig withGlobalProperty(String key, String value, boolean overrideExisting)

Parâmetros:

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

Gerenciando propriedades após a inicialização

Definir propriedade global

Adicione ou atualize uma propriedade global em qualquer momento durante o tempo de execução do aplicativo.

// Set a global property after initialization
val result = Singular.setGlobalProperty("MyProperty", "MyValue", true)
if (result) {
    Log.d("Singular", "Property set successfully")
} else {
    Log.e("Singular", "Failed to set property")
}

// Set a global property after initialization
boolean result = Singular.setGlobalProperty("MyProperty", "MyValue", true);
if (result) {
    Log.d("Singular", "Property set successfully");
} else {
    Log.e("Singular", "Failed to set property");
}

Assinatura do método:

public static boolean setGlobalProperty(String key, String value, boolean overrideExisting)

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

Obter propriedades globais

Recupere todas as propriedades globais definidas atualmente e seus valores como um Map.

// Retrieve all global properties
val properties: Map<String, String> = Singular.getGlobalProperties()

// Iterate through properties
properties.forEach { (key, value) ->
    Log.d("Singular", "Property: $key = $value")
}

// Retrieve all global properties
Map<String, String> properties = Singular.getGlobalProperties();

// Iterate through properties
for (Map.Entry<String, String> entry : properties.entrySet()) {
    Log.d("Singular", "Property: " + entry.getKey() + " = " + entry.getValue());
}

Assinatura do método:

public static Map<String, String> getGlobalProperties()

Retorna: Um Map contendo todos os pares chave-valor de propriedades globais

Remover propriedade global

Remova uma propriedade global específica pela sua chave.

// Remove a specific global property
Singular.unsetGlobalProperty("MyProperty")

// Remove a specific global property
Singular.unsetGlobalProperty("MyProperty");

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

Remova todas as propriedades globais de uma vez.

// Remove all global properties
Singular.clearGlobalProperties()

// Remove all global properties
Singular.clearGlobalProperties();

Assinatura do método:

public static void clearGlobalProperties()

Exemplo de implementação

Padrão de uso completo

Rastreie propriedades no nível do aplicativo e específicas do usuário ao longo do ciclo de vida da aplicação.

// Initialize SDK with app-level global properties
val config = SingularConfig("SDK_KEY", "SDK_SECRET")
    .withGlobalProperty("app_version", BuildConfig.VERSION_NAME, true)

Singular.init(applicationContext, config)

// Set third-party identifier on login
fun onUserLogin(thirdPartyUserId: String) {
    val success = Singular.setGlobalProperty("third_party_identifier", thirdPartyUserId, true)
    if (success) {
        Log.d("Singular", "Third-party identifier set")
    }
}

// Clear third-party identifier on logout
fun onUserLogout() {
    Singular.unsetGlobalProperty("third_party_identifier")
    Log.d("Singular", "Third-party identifier cleared")
}

// Initialize SDK with app-level global properties
SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
    .withGlobalProperty("app_version", BuildConfig.VERSION_NAME, true);

Singular.init(getApplicationContext(), config);

// Set third-party identifier on login
public void onUserLogin(String thirdPartyUserId) {
    boolean success = Singular.setGlobalProperty("third_party_identifier", thirdPartyUserId, true);
    if (success) {
        Log.d("Singular", "Third-party identifier set");
    }
}

// Clear third-party identifier on logout
public void onUserLogout() {
    Singular.unsetGlobalProperty("third_party_identifier");
    Log.d("Singular", "Third-party identifier cleared");
}