SDK do Flutter - Definir propriedades globais

Seguir
Avatar
Jared Ornstead
Updated
Documento

Definir propriedades globais

Defina propriedades personalizadas que se ligam automaticamente a todas as sessões e eventos enviados da sua aplicação, permitindo uma segmentação detalhada dos dados nos relatórios.

As propriedades globais permitem-lhe controlar qualquer utilizador, modo de aplicação ou informação contextual de que necessite. Por exemplo, numa aplicação de jogos, crie uma propriedade "Nível" inicializada como "0" que é actualizada à medida que os utilizadores progridem. Todas as sessões e eventos incluem esta propriedade, permitindo-lhe analisar sessões, contagens de eventos e receitas discriminadas por nível de utilizador.

Especificações da propriedade

Limites e persistência

Compreenda as restrições e o comportamento de persistência das propriedades globais antes da implementação.

  • Máximo de propriedades: Defina até 5 propriedades globais por instalação de aplicativo.
  • Persistência: As propriedades persistem entre lançamentos de aplicações com os seus valores mais recentes até serem explicitamente desactivadas ou a aplicação ser desinstalada.
  • Limite de caracteres: Os nomes e valores das propriedades podem ter até 200 caracteres. Os valores mais longos são automaticamente truncados para 200 caracteres.
  • Disponibilidade de dados: As propriedades globais estão acessíveis em exportações e postbacks ao nível do utilizador. Entre em contato com o gerente de sucesso do cliente da Singular para obter atualizações sobre o suporte a relatórios agregados.

Configuração de propriedades globais na inicialização

Configurar antes da inicialização do SDK

Defina as propriedades globais antes da inicialização do SDK usando a propriedade de configuração globalProperties para garantir que elas sejam incluídas na sessão inicial.

Como as propriedades globais persistem entre as inicializações de aplicativos, as propriedades podem já existir com valores diferentes. Utilize o parâmetro overrideExistingno construtor SingularGlobalProperty para controlar se o novo valor deve substituir os 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(),
    );
  }
}

Propriedade de configuração: 

List<SingularGlobalProperty> globalProperties

Construtor SingularGlobalProperty: 

SingularGlobalProperty(String key, String value, bool overrideExisting)

Parâmetros:

  • key: Nome da propriedade (máx. 200 caracteres)
  • value: Valor da propriedade (máx. 200 caracteres)
  • overrideExisting: Se deve substituir uma propriedade existente com a mesma chave

Gerir propriedades após a inicialização

Definir propriedade global

Adicione ou actualize uma propriedade global em qualquer ponto durante o tempo de execução da aplicação 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');
}

Assinatura do método: 

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

Importante:

  • Se já existirem 5 propriedades e você tentar adicionar uma nova com uma chave diferente, o SDK não a adicionará.
  • O parâmetro overrideExisting determina se os valores de propriedade existentes devem ser substituídos.
  • As propriedades definidas durante a inicialização ou em tempo de execução têm o mesmo comportamento de persistência.

Exemplo: Atualizar propriedade na ação do utilizador

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');
}

Obter propriedades globais

Recupera todas as propriedades globais atualmente definidas e os respectivos valores como um 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']}');
  }
}

Assinatura do método: 

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

Retorna: Um Future que resolve para um Map<String, String> contendo todos os pares chave-valor de propriedades globais.

Remover propriedade global

Remova uma propriedade global específica pela sua chave quando já não precisar de controlar essa dimensão.

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

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

Assinatura do método: 

static void unsetGlobalProperty(String key)

Parâmetros:

  • key: O nome da propriedade a ser removida

Exemplo: Limpar as propriedades do utilizador ao terminar a sessão

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');
}

Limpar todas as propriedades globais

Remove todas as propriedades globais de uma só vez, normalmente quando um utilizador termina a sessão ou quando é necessário repor todas as propriedades de seguimento.

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

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

Assinatura do método: 

static void clearGlobalProperties()

Melhores práticas: Utilize clearGlobalProperties()quando um utilizador terminar a sessão ou quando precisar de repor todas as propriedades de seguimento personalizadas para o seu estado predefinido. Isto é especialmente útil em cenários com vários utilizadores, em que diferentes utilizadores podem iniciar sessão no mesmo dispositivo.

Exemplo de implementação

Padrão de utilização completo

Acompanhe as propriedades específicas do utilizador e ao nível da aplicação ao longo do ciclo de vida da aplicação com uma gestão adequada durante os fluxos de início e fim de sessão.

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(),
    );
  }
}

Melhores práticas: Sincronizar identificadores de análise de terceiros (por exemplo, Mixpanel distinct_id, Amplitude user_id) com propriedades globais Singular para rastreamento unificado entre plataformas. Defina identificadores específicos do utilizador no início de sessão e limpe-os com unsetGlobalProperty() no fim de sessão. As propriedades ao nível da aplicação, como app_version, persistem ao longo das sessões.

Casos de uso comuns

Aplicações de jogos

Acompanhe a progressão do jogador, o nível de envolvimento e o nível de monetização para segmentar utilizadores e otimizar campanhas.

  • player_level: Nível ou estágio atual no jogo
  • vip_status: Nível de subscrição premium (gratuito, prata, ouro)
  • last_purchase_date: Data da compra in-app mais recente
  • engagement_score: Métrica de envolvimento calculada

Aplicações de comércio eletrónico

Acompanhe os segmentos de clientes, o status de fidelidade e as preferências de compras para personalizar as campanhas de marketing.

  • loyalty_tier: Nível do programa de fidelidade do cliente
  • preferred_category: Categoria de produto mais pesquisada
  • cart_status: Se o utilizador tem itens no carrinho
  • lifetime_value_bucket: Total de gastos categorizado (baixo, médio, alto)

Aplicações de conteúdos/meios de comunicação

Acompanhe as preferências de conteúdo, o status da assinatura e os padrões de envolvimento para recomendações e retenção de conteúdo.

  • subscription_type: Gratuito, premium ou plano familiar
  • content_preference: Interesse na categoria de conteúdo principal
  • download_quality: A qualidade de transmissão preferida do utilizador
  • watch_time_bucket: Tempo de visualização diário categorizado

Gestão do limite de propriedades: Com um máximo de 5 propriedades globais, dê prioridade às dimensões de rastreio mais valiosas para a sua análise. Se atingir o limite, considere a remoção de propriedades menos críticas antes de adicionar novas. Planeie cuidadosamente a sua estratégia de propriedades para maximizar as informações.