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 withGlobalProperty() 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 overrideExistingpara controlar se o novo valor deve substituir os 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
  );
}

Assinatura do método:

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

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

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

Assinatura do método:

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

Retorna: Promise<boolean> que resolve para true se a propriedade foi definida com sucesso, false caso contrário

Importante:

Se 5 propriedades já existirem e você tentar adicionar uma nova, o método retornará false
O parâmetro overrideExisting determina se os valores de propriedade existentes devem ser substituídos
Verifique sempre o valor de retorno para confirmar que a propriedade foi definida com êxito

Obter propriedades globais

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

Assinatura do método:

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

Retorna: Uma Promise que resolve para um objeto que contém todos os pares de valores-chave 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.

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

Assinatura do método:

static unsetGlobalProperty(key: string): void

Parâmetros:

key: O nome da propriedade a ser removida

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.

// 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();

Assinatura do método:

static clearGlobalProperties(): void

Melhores práticas: Utilizar clearGlobalProperties()quando um utilizador termina a sessão ou quando é necessário repor todas as propriedades de seguimento personalizadas para o seu estado predefinido.

Exemplo de implementação

Padrão de utilização completo

Rastreie propriedades específicas do usuário e do nível do aplicativo durante todo o ciclo de vida do aplicativo com o tratamento adequado de erros e o gerenciamento de login/logout.

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

Melhores práticas: Sincronizar identificadores analíticos 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. Propriedades no nível do aplicativo, como app_version, persistem em todas as sessões.

Gerenciamento 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 você atingir o limite, considere remover propriedades menos críticas antes de adicionar novas. O exemplo acima mostra como lidar com o limite de 5 propriedades de forma elegante, verificando os valores de retorno.

SDK do React Native - Definir propriedades globais

Definir propriedades globais

Especificações da propriedade

Limites e persistência

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

Configurar antes da inicialização do SDK

Gerir propriedades após a inicialização

Definir propriedade global

Obter propriedades globais

Remover propriedade global

Limpar todas as propriedades globais

Exemplo de implementação

Padrão de utilização completo