Configurando propriedades globais

Defina propriedades personalizadas que se anexam automaticamente a todas as sessões e eventos enviados de seu app, permitindo uma segmentação detalhada de dados nos relatórios.

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

Especificações de propriedades

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 app
• Persistência: As propriedades persistem entre os lançamentos do app com seus valores mais recentes até serem explicitamente removidas ou o app ser desinstalado
• Limite de caracteres: Os nomes e valores das propriedades podem ter até 200 caracteres. Valores maiores são automaticamente truncados em 200 caracteres
• Disponibilidade dos dados: As propriedades globais estão acessíveis em exports a nível de usuário e postbacks. Entre em contato com seu gerente de sucesso do cliente da Singular para atualizações sobre o suporte a relatórios agregados

Configurando propriedades globais na inicialização

Configurar via SingularConfig

Defina propriedades globais durante a inicialização do SDK usando o método setGlobalProperty antes de chamar Singular.start() .

Como as propriedades globais persistem entre os lançamentos do app, propriedades podem já existir com valores diferentes. Use o parâmetro overrideExisting para controlar se o novo valor deve substituir os valores existentes.

func getConfig() -> SingularConfig? {
    // Create config with API credentials
    guard let config = SingularConfig(apiKey: "SDK_KEY", andSecret: "SDK_SECRET") else {
        return nil
    }

    // Set global properties during initialization
    config.setGlobalProperty("MyProperty", withValue: "MyValue", overrideExisting: true)
    config.setGlobalProperty("AnotherProperty", withValue: "AnotherValue", overrideExisting: true)

    return config
}

// Initialize SDK with config
if let config = getConfig() {
    Singular.start(config)
}

- (SingularConfig *)getConfig {
    // Create config with API credentials
    SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"SDK_KEY"
        andSecret:@"SDK_SECRET"];

    // Set global properties during initialization
    [config setGlobalProperty:@"MyProperty" withValue:@"MyValue" overrideExisting:YES];
    [config setGlobalProperty:@"AnotherProperty" withValue:@"AnotherValue" overrideExisting:YES];

    return config;
}

// Initialize SDK with config
SingularConfig *config = [self getConfig];
[Singular start:config];

Assinatura do método:

- (void)setGlobalProperty:(NSString *)key withValue:(NSString *)value overrideExisting:(BOOL)overrideExisting;

Parâmetros:

• key: Nome da propriedade (máximo 200 caracteres)
• value: Valor da propriedade (máximo 200 caracteres)
• overrideExisting: Se deve substituir 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 a execução do app.

// Set a global property after initialization
let result = Singular.setGlobalProperty("MyProperty",
    andValue: "MyValue",
    overrideExisting: true)

if result {
    print("Property set successfully")
} else {
    print("Failed to set property")
}

// Set a global property after initialization
BOOL result = [Singular setGlobalProperty:@"MyProperty"
    andValue:@"MyValue"
    overrideExisting:YES];

if (result) {
    NSLog(@"Property set successfully");
} else {
    NSLog(@"Failed to set property");
}

Assinatura do método:

+ (BOOL)setGlobalProperty:(NSString *)key andValue:(NSString *)value overrideExisting:(BOOL)overrideExisting;

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

Obter propriedades globais

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

// Retrieve all global properties
let properties = Singular.getGlobalProperties()

// Iterate through properties
if let properties = properties as? [String: String] {
    for (key, value) in properties {
        print("Property: \(key) = \(value)")
    }
}

// Retrieve all global properties
NSDictionary *properties = [Singular getGlobalProperties];

// Iterate through properties
for (NSString *key in properties) {
    NSString *value = properties[key];
    NSLog(@"Property: %@ = %@", key, value);
}

Assinatura do método:

+ (NSDictionary *)getGlobalProperties;

Retorna: Um Dictionary contendo todos os pares chave-valor das propriedades globais

Remover propriedade global

Remova uma propriedade global específica por sua chave.

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

// Remove a specific global property
[Singular unsetGlobalProperty:@"MyProperty"];

Assinatura do método:

+ (void)unsetGlobalProperty:(NSString *)key;

Parâmetros:

• key: O nome da propriedade a ser removida

Limpar todas as propriedades globais

Remova todas as propriedades globais de uma só vez.

// Remove all global properties
Singular.clearGlobalProperties()

// Remove all global properties
[Singular clearGlobalProperties];

Assinatura do método:

+ (void)clearGlobalProperties;

Exemplo de implementação

Padrão de uso completo

Faça o rastreamento de propriedades a nível de app e específicas do usuário ao longo de todo o ciclo de vida da aplicação.

// Initialize SDK with app-level global properties
func getConfig() -> SingularConfig? {
    guard let config = SingularConfig(apiKey: "SDK_KEY", andSecret: "SDK_SECRET") else {
        return nil
    }

    // Set app version as a global property
    if let appVersion = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String {
        config.setGlobalProperty("app_version", withValue: appVersion, overrideExisting: true)
    }

    return config
}

// Set third-party identifier on login
func onUserLogin(thirdPartyUserId: String) {
    let success = Singular.setGlobalProperty("third_party_identifier",
        andValue: thirdPartyUserId,
        overrideExisting: true)

    if success {
        print("Third-party identifier set")
    }
}

// Clear third-party identifier on logout
func onUserLogout() {
    Singular.unsetGlobalProperty("third_party_identifier")
    print("Third-party identifier cleared")
}

// Initialize SDK with app-level global properties
- (SingularConfig *)getConfig {
    SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"SDK_KEY"
        andSecret:@"SDK_SECRET"];

    // Set app version as a global property
    NSString *appVersion = [[NSBundle mainBundle] infoDictionary][@"CFBundleShortVersionString"];
    if (appVersion) {
        [config setGlobalProperty:@"app_version" withValue:appVersion overrideExisting:YES];
    }

    return config;
}

// Set third-party identifier on login
- (void)onUserLogin:(NSString *)thirdPartyUserId {
    BOOL success = [Singular setGlobalProperty:@"third_party_identifier"
        andValue:thirdPartyUserId
        overrideExisting:YES];

    if (success) {
        NSLog(@"Third-party identifier set");
    }
}

// Clear third-party identifier on logout
- (void)onUserLogout {
    [Singular unsetGlobalProperty:@"third_party_identifier"];
    NSLog(@"Third-party identifier cleared");
}