Acompanhamento de eventos in-app

Acompanhe os eventos in-app para analisar o desempenho da campanha e medir os principais indicadores de desempenho (KPIs), como logins de utilizadores, registos, conclusões de tutoriais ou marcos de progressão.

Eventos e atributos padrão

Entendendo os tipos de eventos

O Singular suporta dois tipos de eventos para acomodar as necessidades de rastreamento universais e específicas do aplicativo.

• Eventos padrão: Eventos predefinidos (por exemplo, sngLogin, sngContentView) reconhecidos pelo Singular e suportados por redes de anúncios para relatórios e otimização. O uso de eventos padrão simplifica a configuração, pois o Singular os adiciona automaticamente à sua lista de eventos sem definição manual. Consulte a Lista de eventos e atributos padrãopara obter os nomes completos dos eventos e os atributos recomendados.
• Eventos personalizados: Eventos exclusivos do seu aplicativo (por exemplo, Signup, AchievementUnlocked) que não correspondem aos eventos padrão do Singular.

A sua equipa de UA, marketing ou negócios deve compilar a lista de eventos com base nos KPIs de marketing da sua organização. Consulte o guia Como rastrear eventos no aplicativo: Guia para clientes de atribuição Singularpara planejamento.

Limitações de eventos personalizados

Os eventos personalizados têm restrições específicas de caracteres e codificação para garantir a compatibilidade com parceiros de terceiros e soluções de análise.

Envio de eventos

Método de evento

Acompanhe eventos simples sem atributos adicionais usando o método event().

// Track a simple custom event
cordova.plugins.SingularCordovaSdk.event('SignUp');

// Track a standard event
cordova.plugins.SingularCordovaSdk.event('sngLogin');

Assinatura do método:

event(eventName: string): void

Para obter a lista completa de métodos, consulte a referência do método de evento.

Método EventWithArgs

Rastreia eventos com atributos personalizados adicionais para fornecer um contexto mais rico e permitir a segmentação detalhada em relatórios.

// Track custom event with attributes
cordova.plugins.SingularCordovaSdk.eventWithArgs('LevelComplete', {
  level: 5,
  score: 1250,
  time_spent: 45.3
});

// Track standard event with recommended attributes
cordova.plugins.SingularCordovaSdk.eventWithArgs('sngTutorialComplete', {
  sngAttrContent: 'Cordova Basics',
  sngAttrContentId: '32',
  sngAttrContentType: 'video',
  sngAttrSuccess: 'yes'
});

Assinatura do método:

eventWithArgs(eventName: string, args: Object): void

Para obter a lista completa de métodos, consulte a referência do método eventWithArgs.

Práticas recomendadas

Acompanhamento da receita no aplicativo

Acompanhe a receita de compras in-app (IAP), assinaturas e fontes de receita personalizadas para medir o desempenho da campanha e o retorno sobre o gasto com anúncios (ROAS).

Os dados de receita fluem através de três canais:

• Relatórios interactivos: Visualizar métricas de receita no painel do Singular
• Registos de exportação: Aceder a dados ETL detalhados para análise personalizada
• Postbacks em tempo real: Envie eventos de receita para plataformas externas

Por que rastrear eventos de receita?

• Análises avançadas: Capturar dados detalhados de transacções para melhorar os relatórios Singular
• Prevenção de fraudes: Incluir recibos de transação (por exemplo, do Google Play ou da Apple App Store) para validar as compras e combater a fraude na aplicação
• Otimização de campanhas: Medir o ROI associando a receita aos esforços de marketing

Integração de compras no aplicativo

Capturar o objeto de compra IAP

Use os plug-ins IAP do Cordova para recuperar o objeto de compra com detalhes completos da transação das lojas da plataforma.

• iOS: Use cordova-plugin-purchaseou similar para acessar os detalhes de compra do StoreKit
• Android: Use cordova-plugin-purchaseou similar para obter detalhes de compra do Google Play Billing

Construtor SingularIAP

Crie um objeto de compra in-app para rastrear a receita com validação de recibo específica da plataforma e prevenção contra fraudes.

Assinatura do construtor:

function SingularIAP(product: Object): SingularIAP

Para obter a referência completa do construtor, consulte Referência do construtor SingularIAP.

Exemplo de implementação de IAP completo

Implemente um ouvinte de compra completo que captura eventos IAP e os envia para o Singular com objetos de compra específicos da plataforma.

// Import Singular SDK and SingularIAP constructor
var Singular = cordova.plugins.SingularCordovaSdk;
var SingularIAP = cordova.require('singular-cordova-sdk.SingularIAP');

// iOS App Store purchase example
function handleiOSPurchase(purchase) {
  // Create iOS product object
  var iosProduct = {
    currency: 'USD',
    price: 4.99,
    id: 'com.app.premiumgems',
    transaction: {
      type: 'ios-appstore',
      appStoreReceipt: purchase.receipt, // Base64 receipt from StoreKit
      id: purchase.transactionId // Transaction identifier
    }
  };

  // Create SingularIAP object
  var iosIAP = new SingularIAP(iosProduct);

  // Track the purchase with Singular
  // The SingularIAP object is passed as additional args
  cordova.plugins.SingularCordovaSdk.eventWithArgs('iap_purchase', iosIAP);
}

// Android Play Store purchase example
function handleAndroidPurchase(purchase) {
  // Create Android product object
  var androidProduct = {
    currency: 'USD',
    price: 4.99,
    id: 'com.app.premiumgems',
    transaction: {
      type: 'android-playstore',
      receipt: purchase.receipt, // JSON receipt from Google Play
      signature: purchase.signature // Signature from Google Play
    }
  };

  // Create SingularIAP object
  var androidIAP = new SingularIAP(androidProduct);

  // Track the purchase with Singular
  cordova.plugins.SingularCordovaSdk.eventWithArgs('iap_purchase', androidIAP);
}

// Example integration with cordova-plugin-purchase
document.addEventListener('deviceready', function() {
  // Initialize the store
  store.register({
    id: 'com.app.premiumgems',
    type: store.CONSUMABLE
  });

  // Handle purchase approved
  store.when('com.app.premiumgems').approved(function(product) {
    // Determine platform and handle accordingly
    if (device.platform === 'iOS') {
      handleiOSPurchase(product.transaction);
    } else if (device.platform === 'Android') {
      handleAndroidPurchase(product.transaction);
    }

    // Finish the transaction
    product.finish();
  });

  // Refresh the store
  store.refresh();
});

Rastreamento manual de receita

Receita sem validação de compra

Rastreie a receita passando a moeda, o valor e os detalhes opcionais do produto sem o objeto de compra. Observe que esse método não fornece recibos de transação para validação.

Método de receita

Rastreia eventos de receita simples com uma moeda e um valor especificados.

// Track revenue without product details
cordova.plugins.SingularCordovaSdk.revenue('USD', 4.99);

Assinatura do método:

revenue(currency: string, amount: number): void

Para obter a lista completa de métodos, consulte a referência do método revenue.

Método RevenueWithArgs

Rastreia eventos de receita com uma moeda, um valor e atributos personalizados adicionais especificados.

// Track revenue with attributes
cordova.plugins.SingularCordovaSdk.revenueWithArgs('USD', 9.98, {
  productSKU: 'coin_package_abc123',
  productName: 'Coin Pack 10',
  productCategory: 'Bundles',
  productQuantity: 2,
  productPrice: 4.99,
  transaction_id: 'T12345'
});

Assinatura do método:

revenueWithArgs(currency: string, amount: number, args: Object): void

Para obter a lista completa de métodos, consulte a referência do método revenueWithArgs.

Método CustomRevenue

Rastreia eventos de receita personalizados com um nome de evento, uma moeda e um valor especificados.

// Track custom revenue event
cordova.plugins.SingularCordovaSdk.customRevenue('PremiumUpgrade', 'USD', 9.99);

Assinatura do método:

customRevenue(eventName: string, currency: string, amount: number): void

Para obter a lista completa de métodos, consulte a referência do método customRevenue.

Método CustomRevenueWithArgs

Rastreia eventos de receita personalizados com um nome de evento, moeda, valor e atributos personalizados adicionais especificados.

// Track custom revenue event with attributes
cordova.plugins.SingularCordovaSdk.customRevenueWithArgs('PremiumBundlePurchase', 'USD', 99.99, {
  productSKU: 'premium_bundle_xyz',
  productName: 'Premium Bundle',
  productCategory: 'Bundles',
  productQuantity: 1,
  productPrice: 99.99,
  discount_applied: true
});

Assinatura do método:

customRevenueWithArgs(eventName: string, currency: string, amount: number, args: Object): void

Para obter a lista completa de métodos, consulte a referência do método customRevenueWithArgs.

Receita de assinatura

Acompanhamento de assinaturas

A Singular oferece um guia abrangente sobre a implementação de eventos de assinatura usando o Singular SDK. O guia abrange o rastreamento de eventos de assinatura in-app em várias plataformas.

• Leia o Guia de Implementação Técnica de Eventos de Assinaturase quiser rastrear a receita de assinaturas

Rastreamento de eventos híbridos (avançado)

A Singular recomenda o envio de todos os eventos e receitas através do Singular SDK integrado no seu aplicativo para uma atribuição ideal. No entanto, a Singular pode coletar eventos de outras fontes quando necessário.

Os eventos enviados fora do Singular SDK devem estar em conformidade com os requisitos de documentação de eventos de servidor para servidor do Singular e fornecer identificadores de dispositivo correspondentes para atribuição correta.

Guias de rastreamento de eventos híbridos

Envio de eventos de um servidor interno

Recolha dados de receitas do seu servidor interno para analisar o desempenho da campanha e o ROI.

Requisitos:

• Capturar identificadores de dispositivos: A partir de um evento de registo ou início de sessão in-app, capture e passe os identificadores do dispositivo e armazene estes dados com o ID de utilizador no seu servidor. Como os identificadores de dispositivo podem mudar para um utilizador, actualize os identificadores quando um utilizador gera uma sessão de aplicação. Isto garante que o evento do lado do servidor será atribuído ao dispositivo correto
• Identificadores específicos da plataforma: Os eventos do lado do servidor são específicos da plataforma e só devem ser enviados com o identificador de dispositivo correspondente à plataforma do dispositivo (por exemplo, IDFA ou IDFV para dispositivos iOS, GAID para dispositivos Android)
• Actualizações em tempo real: Utilize o mecanismo de postback do Singular Internal BI para enviar um evento em tempo real para o seu ponto de extremidade interno, para que possa atualizar o conjunto de dados no lado do servidor. Consulte as FAQs sobre Postback do BI Interno
• Detalhes de implementação: Reveja a secção Rastreio de receitas no guia de Integração Servidor a Servidor para obter detalhes

Envio de eventos de um fornecedor de receitas

Integre provedores de receita de terceiros como RevenueCat ou adapty para enviar receitas de compras e assinaturas para o Singular.

Provedores suportados:

• RevenueCat: Saiba mais na documentação do RevenueCat
• adapty: Saiba mais na documentação do adapty

Envio de eventos do Segment

Habilite o Segment para enviar eventos para o Singular em paralelo com o SDK do Singular adicionando um destino "Modo nuvem" no Segment.

Siga o guia de implementação Integração Singular-Segment para obter instruções detalhadas de configuração.