Rastreamento de Eventos no Aplicativo

Rastreie eventos no aplicativo para analisar o desempenho das campanhas e medir indicadores-chave de desempenho (KPIs), como logins de usuários, cadastros, conclusões de tutoriais ou marcos de progressão.

Eventos e Atributos Padrão

Usando Eventos Padrão

O Singular oferece suporte a eventos padrão que são reconhecidos pelas redes de anúncios para relatórios e otimização. Use nomes de eventos padrão sempre que possível para reconhecimento automático e configuração simplificada.

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 How to Track In-App Events: Guide For Singular Attribution Customers para o planejamento.

Cada evento oferece suporte a diversos atributos. Consulte os atributos padrão recomendados por evento para detalhes de implementação.

Enviando Eventos

Diretrizes de Implementação de Eventos

Envie eventos ao Singular usando os métodos event ou eventWithArgs para rastrear ações e comportamentos dos usuários.

Eventos Padrão: Use o nome iOS do evento da lista de eventos padrão, por exemplo, EVENT_SNG_LOGIN
Eventos Personalizados: Para eventos exclusivos do seu aplicativo que não correspondem aos eventos padrão, use qualquer string descritiva que atenda às limitações de caracteres

Limitações de Eventos Personalizados:

Idioma: Passe nomes de eventos e atributos em inglês para garantir a compatibilidade com parceiros terceiros e soluções de análise
Nomes de Eventos: Limitados a 32 caracteres ASCII. Strings não ASCII devem ter menos de 32 bytes quando convertidas para UTF-8
Atributos e Valores: Limitados a 500 caracteres ASCII

Método event

Relate eventos de usuários sem informações adicionais para cenários de rastreamento simples.

Assinatura do Método:

+ (void)event:(NSString *)name;

+event: retorna void — não há sinal de sucesso/falha no local da chamada. O SDK descarta silenciosamente o evento quando o nome é nil ou vazio, ou quando +start: ainda não foi chamado. Inspecione os logs para identificar problemas.

Exemplos de Uso

// Example 1: Standard event
Singular.event(EVENT_SNG_LOGIN)

// Example 2: Custom event
Singular.event("signup")

// Example 1: Standard event
[Singular event:EVENT_SNG_LOGIN];

// Example 2: Custom event
[Singular event:@"signup"];

Método eventWithArgs

Relate eventos de usuários com informações adicionais usando o formato de dicionário para dados estruturados.

Assinatura do Método:

+ (void)event:(NSString *)name withArgs:(NSDictionary *)args;

Nota: O parâmetro args é um NSDictionary contendo um ou mais pares de chave-valor. As chaves devem ser strings e os valores podem ser de qualquer tipo permitido em um NSDictionary.

Exemplos de Uso

// Example 1: Standard event with recommended attributes
var dic: [AnyHashable: Any] = [:]
dic[ATTRIBUTE_SNG_ATTR_CONTENT_TYPE] = "video"
dic[ATTRIBUTE_SNG_ATTR_CONTENT_ID] = "32"
dic[ATTRIBUTE_SNG_ATTR_CONTENT] = "Telugu"
dic[ATTRIBUTE_SNG_ATTR_SUCCESS] = "yes"

Singular.event(EVENT_SNG_TUTORIAL_COMPLETE, withArgs: dic)

// Example 2: Custom event with custom attributes
var bonusData: [AnyHashable: Any] = [
    "level": 10,
    "points": 500
]
Singular.event("Bonus Points Earned", withArgs: bonusData)

// Example 1: Standard event with recommended attributes
NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
[dic setValue:@"video" forKey:ATTRIBUTE_SNG_ATTR_CONTENT_TYPE];
[dic setValue:@"32" forKey:ATTRIBUTE_SNG_ATTR_CONTENT_ID];
[dic setValue:@"Telugu" forKey:ATTRIBUTE_SNG_ATTR_CONTENT];
[dic setValue:@"yes" forKey:ATTRIBUTE_SNG_ATTR_SUCCESS];

[Singular event:EVENT_SNG_TUTORIAL_COMPLETE withArgs:dic];

// Example 2: Custom event with custom attributes
NSMutableDictionary *bonusData = [[NSMutableDictionary alloc] init];
[bonusData setValue:@10 forKey:@"level"];
[bonusData setValue:@500 forKey:@"points"];

[Singular event:@"Bonus Points Earned" withArgs:bonusData];

Rastreamento de Receita no Aplicativo

Rastreie receita de compras no aplicativo (IAP), assinaturas e fontes de receita personalizadas para medir o desempenho das campanhas e o retorno sobre o investimento em anúncios (ROAS).

Os dados de receita fluem por três canais:

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

Limitações de Eventos de Receita:

Nomes de Eventos: Os nomes de eventos de receita personalizados são limitados a 32 caracteres ASCII (ou 32 bytes para não ASCII quando convertidos para UTF-8)
Atributos: Os nomes e valores de atributos de eventos são limitados a 500 caracteres ASCII
Códigos de Moeda: Devem estar em MAIÚSCULAS e seguir o padrão de três letras ISO 4217 (por exemplo, USD, EUR, INR)

Práticas Recomendadas

Nomenclatura Padrão: Use a convenção de nomenclatura de eventos e atributos padrão do Singular
Idioma: Envie os nomes de eventos de receita personalizados em inglês para melhor compatibilidade com postbacks das redes de anúncios
Valores Diferentes de Zero: Envie eventos de receita somente quando o valor for maior ou menor que 0

Compra no Aplicativo Sem Assinatura

Integração com SKPaymentTransaction

Passe o objeto SKPaymentTransaction do StoreKit para o método iapComplete para relatórios enriquecidos e validação de transações.

Benefícios:

Dados Ricos: O Singular recebe detalhes completos da transação para relatórios abrangentes
Prevenção de Fraudes: Os recibos de transação permitem a validação para combater fraudes no aplicativo

Notas:

Objeto Obrigatório: O método iapComplete requer o objeto SKPaymentTransaction
Conversão de Moeda: A receita em diferentes moedas é convertida automaticamente para a moeda preferencial da sua organização
Nomes de Eventos Personalizados: Use o parâmetro withName para categorizar a receita por tipo de evento nos relatórios

Método iapComplete

Envie um evento de receita com o objeto SKPaymentTransaction para validação automática e dados enriquecidos.

Assinaturas do Método:

+ (void)iapComplete:(id)transaction;
+ (void)iapComplete:(id)transaction withName:(NSString *)name;

Exemplos de Uso

// Get the SKPaymentTransaction object
let transaction: SKPaymentTransaction = ...

// Send transaction without custom event name
Singular.iapComplete(transaction)

// Send transaction with custom event name
Singular.iapComplete(transaction, withName: "MyCustomRevenue")

// Get the SKPaymentTransaction object
SKPaymentTransaction *transaction = ...;

// Send transaction without custom event name
[Singular iapComplete:transaction];

// Send transaction with custom event name
[Singular iapComplete:transaction withName:@"MyCustomRevenue"];

Receita de Assinatura

Implementação de Eventos de Assinatura

Rastreie compras e renovações de assinaturas para obter insights sobre o comportamento dos usuários e a geração de receita recorrente.

Guia de Implementação: Consulte o abrangente Subscription Event Technical Implementation Guide para instruções detalhadas sobre o rastreamento de assinaturas com o SDK do Singular.

Receita Personalizada sem Validação de Compra

Rastreamento Manual de Receita

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

Importante: Ao usar esses métodos, o Singular não consegue validar as transações. Recomendamos fortemente o uso dos métodos SKPaymentTransaction descritos acima sempre que possível.

Método revenue

Envie eventos de receita com moeda, valor e detalhes opcionais do produto.

Assinaturas do Método:

+ (void)revenue:(NSString *)currency amount:(double)amount;

+ (void)revenue:(NSString *)currency
         amount:(double)amount
     productSKU:(NSString *)productSKU
    productName:(NSString *)productName
productCategory:(NSString *)productCategory
productQuantity:(int)productQuantity
   productPrice:(double)productPrice;

+ (void)revenue:(NSString *)currency
         amount:(double)amount
 withAttributes:(NSDictionary *)attributes;

Exemplos de Uso

// Without product details
Singular.revenue("USD", amount: 1.99)

// With product details
Singular.revenue("EUR",
    amount: 5.00,
    productSKU: "SKU1928375",
    productName: "Reservation Fee",
    productCategory: "Fee",
    productQuantity: 1,
    productPrice: 5.00)

// With product details in a dictionary
var dic: [AnyHashable: Any] = [:]
dic[ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION] = "100% Organic Cotton Mixed Plaid Flannel Shirt"
dic[ATTRIBUTE_SNG_ATTR_ITEM_PRICE] = "$69.95"
dic[ATTRIBUTE_SNG_ATTR_RATING] = "5 Star"
dic[ATTRIBUTE_SNG_ATTR_SEARCH_STRING] = "Flannel Shirt"

Singular.revenue("USD", amount: 19.95, withAttributes: dic)

// Without product details
[Singular revenue:@"USD" amount:1.99];

// With product details
[Singular revenue:@"EUR"
           amount:5.00
       productSKU:@"SKU1928375"
      productName:@"Reservation Fee"
  productCategory:@"Fee"
  productQuantity:1
     productPrice:5.00];

// With product details in a dictionary
NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
[dic setValue:@"100% Organic Cotton Mixed Plaid Flannel Shirt"
       forKey:ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION];
[dic setValue:@"$69.95" forKey:ATTRIBUTE_SNG_ATTR_ITEM_PRICE];
[dic setValue:@"5 Star" forKey:ATTRIBUTE_SNG_ATTR_RATING];
[dic setValue:@"Flannel Shirt" forKey:ATTRIBUTE_SNG_ATTR_SEARCH_STRING];

[Singular revenue:@"USD" amount:19.99 withAttributes:dic];

Método customRevenue

Envie eventos de receita personalizados com um nome de evento especificado, moeda, valor e atributos opcionais da transação.

Assinaturas do Método:

+ (void)customRevenue:(NSString *)eventName
             currency:(NSString *)currency
               amount:(double)amount;

+ (void)customRevenue:(NSString *)eventName
             currency:(NSString *)currency
               amount:(double)amount
           productSKU:(NSString *)productSKU
          productName:(NSString *)productName
      productCategory:(NSString *)productCategory
      productQuantity:(int)productQuantity
         productPrice:(double)productPrice;

+ (void)customRevenue:(NSString *)eventName
             currency:(NSString *)currency
               amount:(double)amount
       withAttributes:(NSDictionary *)attributes;

Exemplos de Uso

// Without product details
Singular.customRevenue("MyCustomRevenue", currency: "USD", amount: 1.99)

// With product details
Singular.customRevenue("MyCustomRevenue",
    currency: "EUR",
    amount: 5.00,
    productSKU: "SKU1928375",
    productName: "Reservation Fee",
    productCategory: "Fee",
    productQuantity: 1,
    productPrice: 5.00)

// With product details in a dictionary
var dic: [AnyHashable: Any] = [:]
dic[ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION] = "100% Organic Cotton Mixed Plaid Flannel Shirt"
dic[ATTRIBUTE_SNG_ATTR_ITEM_PRICE] = "$69.95"
dic[ATTRIBUTE_SNG_ATTR_RATING] = "5 Star"
dic[ATTRIBUTE_SNG_ATTR_SEARCH_STRING] = "Flannel Shirt"

Singular.customRevenue("CustomRevenueWithArgsDic",
    currency: "USD",
    amount: 44.99,
    withAttributes: dic)

// Without product details
[Singular customRevenue:@"MyCustomRevenue" currency:@"USD" amount:1.99];

// With product details
[Singular customRevenue:@"MyCustomRevenue"
               currency:@"EUR"
                 amount:5.00
             productSKU:@"SKU1928375"
            productName:@"Reservation Fee"
        productCategory:@"Fee"
        productQuantity:1
           productPrice:5.00];

// With product details in a dictionary
NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
[dic setValue:@"100% Organic Cotton Mixed Plaid Flannel Shirt"
       forKey:ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION];
[dic setValue:@"$69.95" forKey:ATTRIBUTE_SNG_ATTR_ITEM_PRICE];
[dic setValue:@"5 Star" forKey:ATTRIBUTE_SNG_ATTR_RATING];
[dic setValue:@"Flannel Shirt" forKey:ATTRIBUTE_SNG_ATTR_SEARCH_STRING];

[Singular customRevenue:@"MyCustomRevenue"
               currency:@"USD"
                 amount:44.99
         withAttributes:dic];

Suporte ao StoreKit2

Rastreamento de Receita com StoreKit2

Para aplicativos que usam o framework StoreKit2, use o método customRevenue com as representações JSON da transação e do produto.

A validação do StoreKit2 agora é compatível a partir da versão 12.13+ do SDK. Os métodos exigem o formato jsonRepresentation para os objetos de transação e produto.

Assinaturas do Método:

+ (void)customRevenue:(NSData *)transactionJsonRepresentation
productJsonRepresentation:(NSData *)productJsonRepresentation;

+ (void)customRevenue:(NSString *)eventName
transactionJsonRepresentation:(NSData *)transactionJsonRepresentation
productJsonRepresentation:(NSData *)productJsonRepresentation;

Exemplos de Uso

// Fetch transaction and product from StoreKit2
let transaction = ... // Valid StoreKit2 transaction
let product = ... // Valid StoreKit2 product

// Custom Revenue with default __iap__ event name
Singular.customRevenue(
    transactionJsonRepresentation: transaction.jsonRepresentation,
    productJsonRepresentation: product.jsonRepresentation)

// Custom Revenue with custom event name
Singular.customRevenue(
    "PaymentSuccess",
    transactionJsonRepresentation: transaction.jsonRepresentation,
    productJsonRepresentation: product.jsonRepresentation)

// Fetch transaction and product from StoreKit2
SKTransaction *transaction = ...;  // Valid StoreKit2 transaction
SKProduct *product = ...;          // Valid StoreKit2 product

// Convert JSON representations to NSData
NSData *transactionData = [transaction.jsonRepresentation
    dataUsingEncoding:NSUTF8StringEncoding];
NSData *productData = [product.jsonRepresentation
    dataUsingEncoding:NSUTF8StringEncoding];

// Custom Revenue with default __iap__ event name
[Singular customRevenue:transactionData
    productJsonRepresentation:productData];

// Custom Revenue with custom event name
[Singular customRevenue:@"PaymentSuccess"
    transactionJsonRepresentation:transactionData
    productJsonRepresentation:productData];

Rastreamento Híbrido de Eventos (Avançado)

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

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

Importante:

Discrepâncias ocorrem quando os identificadores de dispositivo nas requisições server-to-server não correspondem aos identificadores registrados pelo SDK do Singular:

Eventos Antecipados: Se um evento chegar antes de o SDK do Singular registrar o identificador de dispositivo, o evento se torna a "primeira sessão" de um dispositivo desconhecido, resultando em atribuição orgânica
Identificadores Incompatíveis: Se o SDK do Singular registrou um identificador de dispositivo diferente daquele na requisição server-to-server, o evento será atribuído incorretamente

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 das campanhas e o ROI.

Requisitos:

Capturar Identificadores de Dispositivo: Durante eventos de cadastro ou login no aplicativo, capture e passe os identificadores de dispositivo, depois armazene esses dados junto ao User ID no seu servidor. Atualize os identificadores quando os usuários gerarem novas sessões do aplicativo para garantir a atribuição correta
Identificadores Específicos da Plataforma: Envie eventos do lado do servidor com o identificador de dispositivo correspondente à plataforma (por exemplo, IDFA ou IDFV para dispositivos iOS)
Atualizações em Tempo Real: Use o mecanismo de postback Internal BI do Singular para enviar eventos em tempo real ao seu endpoint. Consulte o Internal BI Postback FAQ
Detalhes de Implementação: Consulte a seção "Tracking Revenue" no guia de Integração Server-to-Server

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 Compatíveis:

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

Enviando Eventos do Segment

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

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