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.

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

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

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

Assinatura do método:

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

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
• success: Função de retorno de chamada que recebe true se a propriedade foi definida com êxito, false caso contrário

Obter propriedades globais

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

Assinatura do método:

getGlobalProperties(success: Function): void

Parâmetros:

• success: Função de retorno de chamada que recebe 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.

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

Assinatura do método:

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.

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

Assinatura do método:

clearGlobalProperties(): void

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.

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