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 antes de su implementación.

• 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

Configurar antes de la inicialización del SDK

Configure las propiedades globales antes de la inicialización del SDK utilizando withGlobalProperty() para asegurarse de que se incluyen en la sesión inicial.

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.

// Initialize SDK with global properties
var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
);

// Set app-level global properties before initialization
config.withGlobalProperty('app_version', '1.2.3', true);
config.withGlobalProperty('user_type', 'free', true);

// Initialize SDK with global properties
cordova.plugins.SingularCordovaSdk.init(config);

Firma del método:

withGlobalProperty(key: string, value: string, overrideExisting: boolean): SingularConfig

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 utilizando setGlobalProperty().

// Set a global property after initialization
function updatePlayerLevel(level) {
  cordova.plugins.SingularCordovaSdk.setGlobalProperty(
    'player_level',
    level.toString(),
    true,
    function(success) {
      if (success) {
        console.log('Global property set successfully');
      } else {
        console.error('Failed to set property - may have reached 5 property limit');
      }
    }
  );
}

Firma del método:

setGlobalProperty(key: string, value: string, overrideExisting: boolean, success: Function): void

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
• éxito: Función de callback que recibe 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 objeto.

// Retrieve all global properties
function displayGlobalProperties() {
  cordova.plugins.SingularCordovaSdk.getGlobalProperties(function(properties) {
    // Iterate through properties
    for (var key in properties) {
      if (properties.hasOwnProperty(key)) {
        console.log('Property: ' + key + ' = ' + properties[key]);
      }
    }
  });
}

Firma del método:

getGlobalProperties(success: Function): void

Parámetros:

• Éxito: Función de devolución de llamada que recibe un objeto que contiene todos los pares clave-valor de propiedades globales.

Desactivar propiedad global

Elimina una propiedad global específica por su clave cuando ya no necesita realizar un seguimiento de esa dimensión.

// Remove a specific global property
cordova.plugins.SingularCordovaSdk.unsetGlobalProperty('player_level');

Firma del método:

unsetGlobalProperty(key: string): void

Parámetros:

• Clave: El nombre de la propiedad a eliminar

Borrar todas las propiedades globales

Elimina todas las propiedades globales a la vez, normalmente cuando un usuario cierra la sesión o necesita restablecer todas las propiedades de seguimiento.

// Remove all global properties
cordova.plugins.SingularCordovaSdk.clearGlobalProperties();

Firma del método:

clearGlobalProperties(): void

Ejemplo de implementación

Patrón de uso completo

Realiza un seguimiento de las propiedades específicas de la aplicación y del usuario a lo largo del ciclo de vida de la aplicación con una gestión adecuada de los errores y del inicio y cierre de sesión.

document.addEventListener('deviceready', initializeApp, false);

function initializeApp() {
  // Set app-level global properties before initialization
  var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
    'YOUR_SDK_KEY',
    'YOUR_SDK_SECRET'
  );
  
  config.withGlobalProperty('app_version', '1.2.3', true);
  config.withGlobalProperty('platform', 'cordova', true);
  
  // Initialize SDK
  cordova.plugins.SingularCordovaSdk.init(config);
}

// Set user-specific properties on login
function handleUserLogin(userId, userTier) {
  // Set third-party identifier
  cordova.plugins.SingularCordovaSdk.setGlobalProperty(
    'third_party_id',
    userId,
    true,
    function(success) {
      if (success) {
        // Set user tier property
        cordova.plugins.SingularCordovaSdk.setGlobalProperty('user_tier', userTier, true, function(tierSuccess) {
          if (tierSuccess) {
            console.log('User properties set successfully');
          }
        });
      } else {
        console.error('Failed to set user properties');
      }
    }
  );
}

// Update dynamic properties during gameplay
function handleLevelUp(newLevel) {
  cordova.plugins.SingularCordovaSdk.setGlobalProperty(
    'player_level',
    newLevel.toString(),
    true,
    function(success) {
      if (success) {
        // Track level up event
        cordova.plugins.SingularCordovaSdk.eventWithArgs('level_up', {
          new_level: newLevel
        });
      }
    }
  );
}

// Clear user-specific properties on logout
function handleUserLogout() {
  // Remove user-specific properties
  cordova.plugins.SingularCordovaSdk.unsetGlobalProperty('third_party_id');
  cordova.plugins.SingularCordovaSdk.unsetGlobalProperty('user_tier');
  cordova.plugins.SingularCordovaSdk.unsetGlobalProperty('player_level');
  
  console.log('User properties cleared');
}