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

Configuración mediante SingularConfig

Establezca las propiedades globales durante la inicialización del SDK utilizando el método setGlobalProperty antes de llamar a Singular.start().

Dado que las propiedades globales persisten entre lanzamientos de aplicaciones, es posible que ya existan propiedades con valores diferentes. Utilice el parámetro overrideExistingpara controlar si el nuevo valor debe anular los 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];

Firma del método:

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

Parámetros:

• Clave: Nombre de la propiedad (máximo 200 caracteres)
• valor: 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
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");
}

Firma del método:

+ (BOOL)setGlobalProperty:(NSString *)key andValue:(NSString *)value overrideExisting:(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
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);
}

Firma del método:

+ (NSDictionary *)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
Singular.unsetGlobalProperty("MyProperty")

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

Firma del método:

+ (void)unsetGlobalProperty:(NSString *)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
Singular.clearGlobalProperties()

// Remove all global properties
[Singular clearGlobalProperties];

Firma del método:

+ (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.

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