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

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

Configurar via SingularConfig

Defina 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 as inicializações do aplicativo, as propriedades podem já existir com valores diferentes. Utilize o parâmetro overrideExistingpara controlar se o novo valor deve substituir 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á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
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 êxito, false caso contrário

Obter propriedades globais

Recupera todas as propriedades globais atualmente definidas e os respectivos valores como um Mapa.

// 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 de valores-chave de propriedades globais

Remover propriedade global

Remove 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

Remove todas as propriedades globais de uma só 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 utilização completo

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

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