Documento

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.

// TurboModule direct API (React Native 0.76+ New Architecture)
import React, { useEffect } from 'react';
import NativeSingular from 'singular-react-native/jsNativeSingular';

export default function App() {
  useEffect(() => {
    initializeSDK();
  }, []);

  async function initializeSDK() {
    // Initialize SDK with global properties in config
    const config: SingularConfig = {
      apikey: 'YOUR_SDK_KEY',
      secret: 'YOUR_SDK_SECRET',
      globalProperties: {
        app_version: {
          Key: 'app_version',
          Value: '1.2.3',
          OverrideExisting: true
        },
        user_type: {
          Key: 'user_type',
          Value: 'free',
          OverrideExisting: true
        }
      }
    };

    NativeSingular.init(config);
  }

  return (
    // Your app components
    null
  );
}

import React, { useEffect } from 'react';
import { Singular, SingularConfig } from 'singular-react-native';

export default function App() {
  useEffect(() => {
    initializeSDK();
  }, []);

  async function initializeSDK() {
    // Create configuration with global properties
    const config = new SingularConfig(
      'YOUR_SDK_KEY',
      'YOUR_SDK_SECRET'
    )
      // Set app-level global properties before initialization
      .withGlobalProperty('app_version', '1.2.3', true)
      .withGlobalProperty('user_type', 'free', true);

    // Initialize SDK with global properties
    Singular.init(config);
  }

  return (
    // Your app components
  );
}

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

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

// Set a global property after initialization
async function updatePlayerLevel(level) {
  const success = await NativeSingular.setGlobalProperty(
    'player_level',
    level.toString(),
    true
  );

  if (success) {
    console.log('Global property set successfully');
  } else {
    console.error('Failed to set property - may have reached 5 property limit');
  }
}

import { Singular } from 'singular-react-native';

// Set a global property after initialization
async function updatePlayerLevel(level) {
  const success = await Singular.setGlobalProperty(
    'player_level',
    level.toString(),
    true
  );

  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:

static setGlobalProperty(key: string, value: string, overrideExisting: boolean): Promise<boolean>

Devuelve: Promise<boolean> que resuelve a true si la propiedad se ha establecido correctamente, false en caso contrario.

Importante:

Si ya existen 5 propiedades e intentas añadir una nueva, el método devuelve false.
El parámetro overrideExisting determina si se reemplazan los valores de las propiedades existentes
Compruebe siempre el valor devuelto para confirmar que la propiedad se ha establecido correctamente.

Obtener propiedades globales

Recupera todas las propiedades globales actualmente establecidas y sus valores como un objeto.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

// Retrieve all global properties
async function displayGlobalProperties() {
  const properties = await NativeSingular.getGlobalProperties();

  // Iterate through properties
  Object.entries(properties).forEach(([key, value]) => {
    console.log(`Property: ${key} = ${value}`);
  });
}

import { Singular } from 'singular-react-native';

// Retrieve all global properties
async function displayGlobalProperties() {
  const properties = await Singular.getGlobalProperties();

  // Iterate through properties
  Object.entries(properties).forEach(([key, value]) => {
    console.log(`Property: ${key} = ${value}`);
  });
}

Firma del método:

static getGlobalProperties(): Promise<Record<string, any>>

Devuelve: Una Promise que resuelve a un objeto que contiene todos los pares clave-valor de propiedades globales

Desestablecer propiedad global

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

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

// Remove a specific global property
NativeSingular.unsetGlobalProperty('player_level');

import { Singular } from 'singular-react-native';

// Remove a specific global property
Singular.unsetGlobalProperty('player_level');

Firma del método:

static 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.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

// Remove all global properties
NativeSingular.clearGlobalProperties();

import { Singular } from 'singular-react-native';

// Remove all global properties
Singular.clearGlobalProperties();

Firma del método:

static clearGlobalProperties(): void

Práctica recomendada: Utilice clearGlobalProperties()cuando un usuario cierre la sesión o cuando necesite restablecer todas las propiedades de seguimiento personalizadas a su estado predeterminado.

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 con una gestión adecuada de los errores y del inicio y cierre de sesión.

// TurboModule direct API (React Native 0.76+ New Architecture)
import React, { useEffect } from 'react';
import NativeSingular from 'singular-react-native/jsNativeSingular';

export default function App() {
  useEffect(() => {
    initializeSDK();
  }, []);

  async function initializeSDK() {
    // Set app-level global properties before initialization
    const config: SingularConfig = {
      apikey: 'YOUR_SDK_KEY',
      secret: 'YOUR_SDK_SECRET',
      globalProperties: {
        app_version: {
          Key: 'app_version',
          Value: '1.2.3',
          OverrideExisting: true
        },
        platform: {
          Key: 'platform',
          Value: 'react-native',
          OverrideExisting: true
        }
      }
    };

    // Initialize SDK
    NativeSingular.init(config);
  }

  // Set user-specific properties on login
  async function handleUserLogin(userId, userTier) {
    // Set third-party identifier
    const success = await NativeSingular.setGlobalProperty(
      'third_party_id',
      userId,
      true
    );

    if (success) {
      // Set user tier property
      await NativeSingular.setGlobalProperty('user_tier', userTier, true);
      console.log('User properties set successfully');
    } else {
      console.error('Failed to set user properties');
    }
  }

  // Update dynamic properties during gameplay
  async function handleLevelUp(newLevel) {
    await NativeSingular.setGlobalProperty('player_level', newLevel.toString(), true);

    // Track level up event
    NativeSingular.eventWithArgs('level_up', {
      new_level: newLevel
    });
  }

  // Clear user-specific properties on logout
  function handleUserLogout() {
    // Remove user-specific properties
    NativeSingular.unsetGlobalProperty('third_party_id');
    NativeSingular.unsetGlobalProperty('user_tier');
    NativeSingular.unsetGlobalProperty('player_level');

    console.log('User properties cleared');
  }

  return (
    // Your app components
    null
  );
}

import React, { useEffect } from 'react';
import { Singular, SingularConfig } from 'singular-react-native';

export default function App() {
  useEffect(() => {
    initializeSDK();
  }, []);

  async function initializeSDK() {
    // Set app-level global properties before initialization
    const config = new SingularConfig(
      'YOUR_SDK_KEY',
      'YOUR_SDK_SECRET'
    )
      .withGlobalProperty('app_version', '1.2.3', true)
      .withGlobalProperty('platform', 'react-native', true);

    // Initialize SDK
    Singular.init(config);
  }

  // Set user-specific properties on login
  async function handleUserLogin(userId, userTier) {
    // Set third-party identifier
    const success = await Singular.setGlobalProperty(
      'third_party_id',
      userId,
      true
    );

    if (success) {
      // Set user tier property
      await Singular.setGlobalProperty('user_tier', userTier, true);
      console.log('User properties set successfully');
    } else {
      console.error('Failed to set user properties');
    }
  }

  // Update dynamic properties during gameplay
  async function handleLevelUp(newLevel) {
    await Singular.setGlobalProperty('player_level', newLevel.toString(), true);

    // Track level up event
    Singular.eventWithArgs('level_up', {
      new_level: newLevel
    });
  }

  // Clear user-specific properties on logout
  function handleUserLogout() {
    // Remove user-specific properties
    Singular.unsetGlobalProperty('third_party_id');
    Singular.unsetGlobalProperty('user_tier');
    Singular.unsetGlobalProperty('player_level');

    console.log('User properties cleared');
  }

  return (
    // Your app components
  );
}

Práctica recomendada: Sincronice los identificadores de análisis de terceros (por ejemplo, Mixpanel distinct_id, Amplitude user_id) con las propiedades globales de Singular para un seguimiento unificado entre plataformas. Establezca identificadores específicos de usuario al iniciar sesión y bórrelos con unsetGlobalProperty() al cerrar sesión. Las propiedades a nivel de aplicación como app_version persisten a través de las sesiones.

Gestión del límite de propiedades: Con un máximo de 5 propiedades globales, priorice las dimensiones de seguimiento más valiosas para sus análisis. Si alcanza el límite, considere eliminar las propiedades menos críticas antes de añadir otras nuevas. El ejemplo anterior muestra cómo gestionar con elegancia el límite de 5 propiedades comprobando los valores de retorno.

SDK de React Native - Configuración de propiedades globales

Configuración de propiedades globales

Especificaciones de la propiedad

Límites y Persistencia

Configuración de propiedades globales en la inicialización

Configurar antes de la inicialización del SDK

Gestión de propiedades tras la inicialización

Establecer propiedad global

Obtener propiedades globales

Desestablecer propiedad global

Borrar todas las propiedades globales

Ejemplo de implementación

Patrón de uso completo