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ão para 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 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 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().

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

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 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 o pacote Flutter in_app_purchase para recuperar o objeto de compra com detalhes completos da transação.

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

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 void inAppPurchase(String eventName, SingularIAP purchase)

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

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.

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

Método CustomRevenue

Rastreia eventos de receita personalizados 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 obter a lista completa de métodos, consulte a referência do método customRevenue.

Método CustomRevenueWithAttributes

Rastreia eventos de receita personalizados 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 obter a lista completa de métodos, consulte a referência do método customRevenueWithAttributes.

Método CustomRevenueWithAllAttributes

Rastreia eventos de receita personalizados 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 obter a lista completa de métodos, consulte a referência do método customRevenueWithAllAttributes.

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 assinatura se quiser rastrear a receita de assinatura

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 Integração Servidor a Servidor para obter mais 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.