Configurar propiedades globales

Define propiedades personalizadas que se adjuntan automáticamente a cada sesión y evento enviado desde tu app, permitiendo una segmentación detallada de datos en los reportes.

Las propiedades globales te permiten hacer tracking de cualquier información de usuario, modo de app o información contextual que necesites. Por ejemplo, en una app de juegos, crea una propiedad "Level" inicializada en "0" que se actualice a medida que los usuarios progresan. Todas las sesiones y eventos incluyen esta propiedad, lo que te permite analizar sesiones, conteos de eventos e ingresos desglosados por nivel de usuario.

Especificaciones de las propiedades

Límites y persistencia

Comprende las restricciones y el comportamiento de persistencia de las propiedades globales.

• Propiedades máximas: Define hasta 5 propiedades globales por instalación de app
• Persistencia: Las propiedades persisten entre lanzamientos de la app con sus valores más recientes hasta que se desactiven explícitamente o se desinstale la app
• Límite de caracteres: Los nombres y valores de las propiedades pueden tener hasta 200 caracteres de longitud. Los valores más largos se truncan automáticamente a 200 caracteres
• Disponibilidad de datos: Las propiedades globales están disponibles en exports a nivel de usuario y postbacks. Contacta a tu gerente de éxito del cliente de Singular para obtener actualizaciones sobre el soporte de reportes agregados

Configurar propiedades globales durante la inicialización

Configurar mediante SingularConfig

Define 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 la app, las propiedades pueden existir con valores diferentes. Usa el parámetro overrideExisting para controlar si el nuevo valor debe sobrescribir 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:

• key: Nombre de la propiedad (máximo 200 caracteres)
• value: Valor de la propiedad (máximo 200 caracteres)
• overrideExisting: Si se debe sobrescribir una propiedad existente con la misma clave

Administrar propiedades después de la inicialización

Configurar propiedad global

Agrega o actualiza una propiedad global en cualquier momento durante el tiempo de ejecución de la 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");
}

Firma del método:

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

Retorna: true si la propiedad se configuró correctamente, false de lo contrario

Obtener propiedades globales

Recupera todas las propiedades globales actualmente configuradas y sus valores como un 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);
}

Firma del método:

+ (NSDictionary *)getGlobalProperties;

Retorna: Un Dictionary que contiene todos los pares clave-valor de las propiedades globales

Desactivar 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:

• key: El nombre de la propiedad a eliminar

Limpiar 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

Haz tracking de propiedades a nivel de app y específicas 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");
}