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

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

// Track a simple custom event
NativeSingular.event('SignUp');

// Track a standard event using constant
NativeSingular.event('sngLogin');

import { Singular } from 'singular-react-native';

// Track a simple custom event
Singular.event('SignUp');

// Track a standard event using constant
Singular.event('sngLogin');

Assinatura do método:

static 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.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

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

// Track standard event with recommended attributes
NativeSingular.eventWithArgs('sngTutorialComplete', {
  sngAttrContent: 'React Native Basics',
  sngAttrContentId: '32',
  sngAttrContentType: 'video',
  sngAttrSuccess: 'yes'
});

import { Singular } from 'singular-react-native';

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

// Track standard event with recommended attributes
Singular.eventWithArgs('sngTutorialComplete', {
  sngAttrContent: 'React Native Basics',
  sngAttrContentId: '32',
  sngAttrContentType: 'video',
  sngAttrSuccess: 'yes'
});

Assinatura do método:

static eventWithArgs(eventName: string, args: Record<string, any>): 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 as bibliotecas IAP específicas da plataforma para recuperar o objeto de compra com detalhes completos da transação.

• iOS: Use react-native-iapou similar para acessar os detalhes de compra do StoreKit
• Android: Utilize react-native-iapou a biblioteca de faturação do Google Play para obter o objeto de compra

Método InAppPurchase

Acompanhe eventos de compra in-app com detalhes de compra para validação de receita e prevenção de fraudes.

Assinaturas de método:

static inAppPurchase(eventName: string, purchase: SingularIOSPurchase | SingularAndroidPurchase): void
static inAppPurchaseWithArgs(eventName: string, purchase: SingularIOSPurchase | SingularAndroidPurchase, args: Record<string, any>): void

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

Exemplo completo de implementação de IAP

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

// TurboModule direct API (React Native 0.76+ New Architecture)
import { Platform } from 'react-native';
import NativeSingular from 'singular-react-native/jsNativeSingular';
import { 
  SingularIOSPurchase, 
  SingularAndroidPurchase 
} from 'singular-react-native';
import { 
  initConnection,
  getProducts,
  setPurchaseListener,
  finishTransaction,
  IAPResponseCode
} from 'react-native-iap';

// Helper function to convert price to a double
const getPriceAsDouble = (product) => {
  if (Platform.OS === 'android' && product.priceAmountMicros) {
    // Android: Convert priceAmountMicros to double
    return product.priceAmountMicros / 1000000.0;
  } else if (Platform.OS === 'ios') {
    // iOS: Parse price string (e.g., "$4.99" -> 4.99)
    const priceString = product.price.replace(/[^0-9.]/g, '');
    return parseFloat(priceString) || 0.0;
  }
  return 0.0; // Fallback
};

// Set up purchase listener
const handlePurchases = async () => {
  try {
    // Initialize connection
    await initConnection();

    // Set purchase listener
    setPurchaseListener(async ({ responseCode, results }) => {
      if (responseCode === IAPResponseCode.OK) {
        for (const purchase of results) {
          if (!purchase.acknowledged) {
            // Fetch product details
            const products = await getProducts({ skus: [purchase.productId] });
            const product = products.length > 0 ? products[0] : null;
            if (!product) return;

            // Create purchase object
            let singularPurchase = null;

            if (Platform.OS === 'ios') {
              singularPurchase = new SingularIOSPurchase(
                getPriceAsDouble(product),
                product.currency ?? 'USD',
                purchase.productId,
                purchase.transactionId ?? '',
                purchase.transactionReceipt
              );
            } else if (Platform.OS === 'android') {
              const jsonData = JSON.parse(purchase.transactionReceipt || '{}');
              const receipt = jsonData.purchaseToken || '';

              singularPurchase = new SingularAndroidPurchase(
                getPriceAsDouble(product),
                product.currency ?? 'USD',
                purchase.transactionReceipt,
                purchase.signatureAndroid
              );
            } else {
              return;
            }

            // Track in-app purchase
            NativeSingular.inAppPurchase('iap_purchase', singularPurchase);

            // Complete the purchase
            await finishTransaction(purchase, Platform.OS === 'ios');
          }
        }
      }
    });
  } catch (error) {
    console.error('Error handling purchases:', error);
  }
};

// Call handlePurchases when your app starts
handlePurchases();

import { Platform } from 'react-native';
import { 
  Singular, 
  SingularIOSPurchase, 
  SingularAndroidPurchase 
} from 'singular-react-native';
import { 
  initConnection,
  getProducts,
  setPurchaseListener,
  finishTransaction,
  IAPResponseCode
} from 'react-native-iap';

// Helper function to convert price to a double
const getPriceAsDouble = (product) => {
  if (Platform.OS === 'android' && product.priceAmountMicros) {
    // Android: Convert priceAmountMicros to double
    return product.priceAmountMicros / 1000000.0;
  } else if (Platform.OS === 'ios') {
    // iOS: Parse price string (e.g., "$4.99" -> 4.99)
    const priceString = product.price.replace(/[^0-9.]/g, '');
    return parseFloat(priceString) || 0.0;
  }
  return 0.0; // Fallback
};

// Set up purchase listener
const handlePurchases = async () => {
  try {
    // Initialize connection
    await initConnection();

    // Set purchase listener
    setPurchaseListener(async ({ responseCode, results }) => {
      if (responseCode === IAPResponseCode.OK) {
        for (const purchase of results) {
          if (!purchase.acknowledged) {
            // Fetch product details
            const products = await getProducts({ skus: [purchase.productId] });
            const product = products.length > 0 ? products[0] : null;
            if (!product) return;

            // Create purchase object
            let singularPurchase = null;

            if (Platform.OS === 'ios') {
              singularPurchase = new SingularIOSPurchase(
                getPriceAsDouble(product), // Price as double, e.g., 4.99
                product.currency ?? 'USD', // Currency code, e.g., "USD"
                purchase.productId, // e.g., "com.example.premium_subscription"
                purchase.transactionId ?? '', // e.g., "1000000823456789"
                purchase.transactionReceipt // JWS receipt from StoreKit
              );
            } else if (Platform.OS === 'android') {
              // Parse transactionReceipt to extract purchaseToken
              const jsonData = JSON.parse(purchase.transactionReceipt || '{}');
              const receipt = jsonData.purchaseToken || '';

              singularPurchase = new SingularAndroidPurchase(
                getPriceAsDouble(product), // Price as double, e.g., 4.99
                product.currency ?? 'USD', // Currency code, e.g., "USD"
                purchase.transactionReceipt, // Full JSON receipt from Google Play
                purchase.signatureAndroid // Signature from Google Play
              );
            } else {
              return; // Unsupported platform
            }

            // Track in-app purchase
            Singular.inAppPurchase('iap_purchase', singularPurchase);

            // Complete the purchase
            await finishTransaction(purchase, Platform.OS === 'ios');
          }
        }
      }
    });
  } catch (error) {
    console.error('Error handling purchases:', error);
  }
};

// Call handlePurchases when your app starts
handlePurchases();

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 Purchase. Observe que esse método não fornece recibos de transação para validação.

Método de receita

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

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

// Track revenue without product details
NativeSingular.revenue('USD', 4.99);

import { Singular } from 'singular-react-native';

// Track revenue without product details
Singular.revenue('USD', 4.99);

Assinatura do método:

static 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.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

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

import { Singular } from 'singular-react-native';

// Track revenue with attributes
Singular.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:

static revenueWithArgs(currency: string, amount: number, args: Record<string, any>): 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.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

// Track custom revenue event
NativeSingular.customRevenue('PremiumUpgrade', 'USD', 9.99);

import { Singular } from 'singular-react-native';

// Track custom revenue event
Singular.customRevenue('PremiumUpgrade', 'USD', 9.99);

Assinatura do método:

static 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.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

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

import { Singular } from 'singular-react-native';

// Track custom revenue event with attributes
Singular.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:

static customRevenueWithArgs(eventName: string, currency: string, amount: number, args: Record<string, any>): 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 a Singular em paralelo com o SDK da 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.