Rastreamento de Eventos In-App

Rastreie eventos in-app para analisar o desempenho de campanhas e medir indicadores-chave de desempenho (KPI), como logins de usuários, registros, conclusões de tutoriais ou marcos de progressão.

Eventos e Atributos Padrão

Entendendo os Tipos de Evento

O Singular oferece suporte a dois tipos de eventos para atender tanto às necessidades de rastreamento universal quanto às específicas do app.

• 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ão para obter os nomes completos dos eventos e os atributos recomendados.
• Eventos Personalizados: Eventos exclusivos do seu app (por exemplo, Signup , AchievementUnlocked ) que não correspondem aos eventos padrão do Singular.

Sua equipe 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 In-App: Guia para Clientes de Atribuição do Singular para 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 terceiros e soluções de análise.

Enviando Eventos

Método Event

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

import 'package:singular_flutter_sdk/singular.dart';

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

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

Assinatura do Método:

static void event(String eventName)

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

Método EventWithArgs

Rastreie eventos com atributos personalizados adicionais para fornecer um contexto mais rico e permitir uma segmentação detalhada nos relatórios.

import 'package:singular_flutter_sdk/singular.dart';

// 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': 'Flutter Basics',
  'sngAttrContentId': '32',
  'sngAttrContentType': 'video',
  'sngAttrSuccess': 'yes'
});

Assinatura do Método:

static void eventWithArgs(String eventName, Map args)

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

Práticas Recomendadas

Rastreamento de Receita In-App

Rastreie a receita de compras in-app (IAP), assinaturas e fontes de receita personalizadas para medir o desempenho de campanhas e o retorno sobre o investimento em publicidade (ROAS).

Os dados de receita fluem por três canais:

• Relatórios Interativos: Visualize as métricas de receita no dashboard do Singular
• Logs de Exportação: Acesse dados detalhados de ETL para análises personalizadas
• Postbacks em Tempo Real: Envie eventos de receita para plataformas externas

Por Que Rastrear Eventos de Receita?

• Análises Ricas: Capture dados detalhados de transações para aprimorar os relatórios do Singular
• Prevenção de Fraude: Inclua recibos de transações (por exemplo, do Google Play ou da Apple App Store) para validar compras e combater fraudes in-app
• Otimização de Campanhas: Meça o ROI vinculando a receita aos esforços de marketing

Integração de Compra In-App

Capturar o Objeto de Compra IAP

Use o pacote in_app_purchase do Flutter para recuperar o objeto de compra com os detalhes completos da transação.

• Flutter: Use o pacote in_app_purchase para acessar os detalhes de compra tanto do iOS StoreKit quanto do Android Google Play Billing

Método InAppPurchase

Rastreie eventos de compra in-app com detalhes da compra para validação de receita e prevenção de fraude.

Assinaturas do Método:

static void inAppPurchase(String eventName, SingularIAP purchase)

static void inAppPurchaseWithAttributes(String eventName, SingularIAP purchase, Map attributes)

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

Exemplo Completo de Implementação de IAP

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

import 'dart:io' show Platform;
import 'package:in_app_purchase/in_app_purchase.dart';
import 'package:in_app_purchase_android/in_app_purchase_android.dart';
import 'package:in_app_purchase_storekit/in_app_purchase_storekit.dart';
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_iap.dart';

Future<void> handlePurchase(PurchaseDetails purchaseDetails) async {
  if (purchaseDetails.status != PurchaseStatus.purchased &&
      purchaseDetails.status != PurchaseStatus.restored) {
    return;
  }

  final response = await InAppPurchase.instance
      .queryProductDetails({purchaseDetails.productID});
  if (response.productDetails.isEmpty) {
    return;
  }
  final product = response.productDetails.first;

  // Extract price and currency with platform-specific handling
  double price = 0.0;
  String currency = 'USD';

  if (Platform.isAndroid && product is GooglePlayProductDetails) {
    final offer = product.productDetails.oneTimePurchaseOfferDetails;
    price = (offer?.priceAmountMicros ?? 0) / 1000000;
    currency = offer?.priceCurrencyCode ?? 'USD';
  } else if (Platform.isIOS && product is AppStoreProductDetails) {
    price = product.skProduct.price;
    currency = product.skProduct.priceLocale.currencyCode ?? 'USD';
  }

  SingularIAP? singularPurchase;

  if (Platform.isAndroid && purchaseDetails is GooglePlayPurchaseDetails) {
    singularPurchase = SingularAndroidIAP(
      price,
      currency,
      purchaseDetails.billingClientPurchase.signature,
      purchaseDetails.billingClientPurchase.originalJson,
    );
  } else if (Platform.isIOS && purchaseDetails is AppStorePurchaseDetails) {
    singularPurchase = SingularIOSIAP(
      price,
      currency,
      purchaseDetails.productID,
      purchaseDetails.skPaymentTransaction.transactionIdentifier ?? '',
      purchaseDetails.verificationData.serverVerificationData,
    );
  } else {
    return;
  }

  const String eventName = 'iap_purchase';

  // Track with attributes (use only ONE tracking method)
  Singular.inAppPurchaseWithAttributes(eventName, singularPurchase, {
    'user_level': 42,
    'is_first_purchase': true,
    'gems_balance': 1500
  });

  await InAppPurchase.instance.completePurchase(purchaseDetails);
}

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

Método CustomRevenue

Rastreie eventos de receita personalizada com um nome de evento, moeda e valor especificados.

import 'package:singular_flutter_sdk/singular.dart';

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

Assinatura do Método:

static void customRevenue(String eventName, String currency, double amount)

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

Método CustomRevenueWithAttributes

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

import 'package:singular_flutter_sdk/singular.dart';

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

Assinatura do Método:

static void customRevenueWithAttributes(
  String eventName,
  String currency,
  double amount,
  Map attributes
)

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

Método CustomRevenueWithAllAttributes

Rastreie eventos de receita personalizada com todos os atributos possíveis, incluindo SKU do produto, nome, categoria, quantidade e atributos personalizados.

import 'package:singular_flutter_sdk/singular.dart';

// Track custom revenue with all attributes
Singular.customRevenueWithAllAttributes(
  'CoinPackagePurchase',
  'USD',
  4.99,
  'coin_package_abc123',
  'Coin Pack 10',
  'Virtual Currency',
  2,
  {
    'payment_method': 'google_play',
    'transaction_id': 'T12345'
  }
);

Assinatura do Método:

static void customRevenueWithAllAttributes(
  String eventName,
  String currency,
  double amount,
  String productSKU,
  String productName,
  String productCategory,
  int productQuantity,
  Map attributes
)

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

Receita de Assinatura

Rastreando Assinaturas

O Singular oferece um guia completo sobre a implementação de eventos de assinatura usando o Singular SDK. O guia aborda o rastreamento de eventos de assinatura in-app em diversas plataformas.

• Leia o Guia de Implementação Técnica de Eventos de Assinatura se você quiser rastrear a receita de assinaturas

Rastreamento Híbrido de Eventos (Avançado)

O Singular recomenda enviar todos os eventos e a receita por meio do Singular SDK integrado ao seu app para uma atribuição ideal. No entanto, o Singular pode coletar eventos de outras fontes quando necessário.

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

Guias de Rastreamento Híbrido de Eventos

Enviando Eventos de um Servidor Interno

Colete dados de receita do seu servidor interno para analisar o desempenho de campanhas e o ROI.

Requisitos:

• Capturar Identificadores de Dispositivo: A partir de um Evento de Registro ou Login in-app, capture e passe os identificadores de dispositivo e armazene esses dados com o User ID no seu servidor. Como os identificadores de dispositivo podem mudar para um usuário, atualize os identificadores quando um usuário gerar uma app session. Isso garante que o evento do lado do servidor seja atribuído ao dispositivo correto
• Identificadores Específicos da Plataforma: Os eventos do lado do servidor são específicos da plataforma e devem ser enviados apenas com o identificador de dispositivo correspondente à plataforma do dispositivo (por exemplo, IDFA ou IDFV para dispositivos iOS, GAID para dispositivos Android)
• Atualizações em Tempo Real: Use o mecanismo de postback de BI Interno do Singular para enviar um evento em tempo real para o seu endpoint interno, de modo que você possa atualizar o conjunto de dados no lado do servidor. Consulte o FAQ de Postback de BI Interno
• Detalhes de Implementação: Revise a seção Rastreamento de Receita no guia de Integração Server-to-Server para obter detalhes

Enviando Eventos de um Provedor de Receita

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

Provedores Suportados:

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

Enviando Eventos do Segment

Habilite o Segment para enviar eventos ao Singular em paralelo com o Singular SDK adicionando um destino "Cloud-Mode" no Segment.

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