SDK de Flutter - Configuración de propiedades globales

Seguir
Avatar
Jared Ornstead
Updated
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 un máximo de 200 caracteres. Los valores más largos se truncan automáticamente a 200 caracteres.
  • Disponibilidad de datos: Las propiedades globales son accesibles en 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 globales.

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 la propiedad de configuración globalProperties 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 overrideExistingen el constructor SingularGlobalProperty para controlar si el nuevo valor debe anular los valores existentes.

Dart 
import 'package:flutter/material.dart';
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';
import 'package:singular_flutter_sdk/singular_global_property.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    initializeSDK();
  }

  void initializeSDK() {
    // Create configuration with global properties
    SingularConfig config = SingularConfig(
      'YOUR_SDK_KEY',
      'YOUR_SDK_SECRET'
    );

    // Set app-level global properties before initialization
    config.globalProperties = [
      SingularGlobalProperty('app_version', '1.2.3', true),
      SingularGlobalProperty('platform', 'flutter', true)
    ];

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      home: MyHomePage(),
    );
  }
}

Propiedad de configuración: 

List<SingularGlobalProperty> globalProperties

SingularGlobalProperty Constructor: 

SingularGlobalProperty(String key, String value, 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 utilizando setGlobalProperty().

Dart 
import 'package:singular_flutter_sdk/singular.dart';

// Set a global property after initialization
void updatePlayerLevel(int level) {
  Singular.setGlobalProperty(
    'player_level',
    level.toString(),
    true
  );

  print('Global property set: player_level = $level');
}

Firma del método: 

static void setGlobalProperty(String key, String value, bool overrideExisting)

Importante:

  • Si ya existen 5 propiedades e intenta añadir una nueva con una clave diferente, el SDK no la añadirá.
  • El parámetro overrideExisting determina si se reemplazan los valores de las propiedades existentes.
  • Las propiedades establecidas durante la inicialización o en tiempo de ejecución tienen el mismo comportamiento de persistencia.

Ejemplo: Actualizar Propiedad en Acción de Usuario

Dart 
import 'package:singular_flutter_sdk/singular.dart';

// Example: Track user subscription tier
void handleSubscriptionChange(String tier) {
  // Update global property
  Singular.setGlobalProperty('subscription_tier', tier, true);

  // Track the subscription event
  Singular.eventWithArgs('subscription_changed', {
    'new_tier': tier,
    'timestamp': DateTime.now().toIso8601String()
  });

  print('Subscription tier updated: $tier');
}

Obtener propiedades globales

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

Dart 
import 'package:singular_flutter_sdk/singular.dart';

// Retrieve all global properties
Future<void> displayGlobalProperties() async {
  Map<String, String> properties = await Singular.getGlobalProperties();

  // Iterate through properties
  properties.forEach((key, value) {
    print('Property: $key = $value');
  });

  // Check if specific property exists
  if (properties.containsKey('player_level')) {
    print('Current player level: ${properties['player_level']}');
  }
}

Firma del método: 

static Future<Map<String, String>> getGlobalProperties()

Devuelve: Un Future que resuelve a un Map<String, String> 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.

Dart 
import 'package:singular_flutter_sdk/singular.dart';

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

Firma del método: 

static void unsetGlobalProperty(String key)

Parámetros:

  • Clave: El nombre de la propiedad a eliminar

Ejemplo: Borrar propiedades de usuario al cerrar sesión

Dart 
import 'package:singular_flutter_sdk/singular.dart';

// Clear user-specific properties on logout
void handleUserLogout() {
  // Remove user-specific properties
  Singular.unsetGlobalProperty('subscription_tier');
  Singular.unsetGlobalProperty('player_level');
  Singular.unsetGlobalProperty('user_segment');

  // Also clear custom user ID
  Singular.unsetCustomUserId();

  print('User properties cleared on logout');
}

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.

Dart 
import 'package:singular_flutter_sdk/singular.dart';

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

Firma del método: 

static void clearGlobalProperties()

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. Esto es especialmente útil en escenarios multiusuario donde diferentes usuarios pueden iniciar sesión en el mismo dispositivo.

Ejemplo de implementación

Patrón de uso completo

Realice 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 durante los flujos de inicio y cierre de sesión.

Dart 
import 'package:flutter/material.dart';
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';
import 'package:singular_flutter_sdk/singular_global_property.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    initializeSDK();
  }

  void initializeSDK() {
    // Set app-level global properties before initialization
    SingularConfig config = SingularConfig(
      'YOUR_SDK_KEY',
      'YOUR_SDK_SECRET'
    );

    config.globalProperties = [
      SingularGlobalProperty('app_version', '1.2.3', true),
      SingularGlobalProperty('platform', 'flutter', true)
    ];

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

  // Set user-specific properties on login
  void handleUserLogin(String userId, String userTier) {
    // Set custom user ID
    Singular.setCustomUserId(userId);

    // Set user tier property
    Singular.setGlobalProperty('user_tier', userTier, true);

    // Set initial player level
    Singular.setGlobalProperty('player_level', '1', true);

    print('User properties set successfully');
  }

  // Update dynamic properties during gameplay
  void handleLevelUp(int newLevel) {
    // Update player level property
    Singular.setGlobalProperty('player_level', newLevel.toString(), true);

    // Track level up event
    Singular.eventWithArgs('level_up', {
      'new_level': newLevel.toString(),
      'timestamp': DateTime.now().millisecondsSinceEpoch.toString()
    });

    print('Level updated to $newLevel');
  }

  // Update subscription status
  void handleSubscriptionPurchase(String tier) {
    // Update subscription tier
    Singular.setGlobalProperty('subscription_tier', tier, true);

    // Track subscription event
    Singular.customRevenue('subscription_purchase', 'USD', 9.99);

    print('Subscription tier updated: $tier');
  }

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

    // Clear custom user ID
    Singular.unsetCustomUserId();

    print('User properties cleared on logout');
  }

  // Alternative: Clear all properties at once
  void handleCompleteReset() {
    // Remove all global properties
    Singular.clearGlobalProperties();

    // Clear custom user ID
    Singular.unsetCustomUserId();

    print('All properties and user ID cleared');
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      home: MyHomePage(),
    );
  }
}

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.

Casos de uso comunes

Aplicaciones de juegos

Seguimiento de la progresión del jugador, nivel de compromiso y nivel de monetización para segmentar a los usuarios y optimizar las campañas.

  • nivel_jugador: Nivel actual o etapa en el juego
  • vip_status: Nivel de suscripción Premium (gratuito, plata, oro)
  • last_purchase_date: Fecha de la última compra dentro de la aplicación.
  • engagement_score: Métrica de participación calculada

Aplicaciones de comercio electrónico

Realice un seguimiento de los segmentos de clientes, el estado de fidelidad y las preferencias de compra para personalizar las campañas de marketing.

  • loyalty_tier: Nivel del programa de fidelización del cliente
  • categoría_preferida: Categoría de producto más buscada
  • cart_status: Si el usuario tiene artículos en el carrito
  • lifetime_value_bucket: Gasto total categorizado (bajo, medio, alto)

Contenido/Aplicaciones multimedia

Realice un seguimiento de las preferencias de contenido, el estado de suscripción y los patrones de participación para recomendaciones de contenido y retención.

  • subscription_type: Plan gratuito, premium o familiar
  • preferencia_contenido: Categoría de contenido de interés principal
  • calidad_descarga: Calidad de streaming preferida por el usuario
  • watch_time_bucket: Tiempo de visionado diario categorizado

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. Planifique cuidadosamente su estrategia de propiedades para maximizar la información.