Rastreamento de eventos in-app

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

Eventos e atributos padrão

Uso de eventos padrão

A Singular oferece suporte a eventos padrão reconhecidos pelas redes de anúncios para reporting e otimização. Sempre que possível, use nomes de eventos padrão para obter 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 Como rastrear eventos in-app: guia para clientes da Singular Attribution para o planejamento.

Cada evento oferece suporte a vários atributos. Veja os atributos padrão recomendados por evento para detalhes de implementação.

Envio de eventos

Diretrizes de implementação de eventos

Envie eventos para a 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 app que não correspondem aos eventos padrão, use qualquer string descritiva que respeite as limitações de caracteres

Limitações de eventos personalizados:

Idioma: Envie os nomes e atributos dos eventos em inglês para garantir compatibilidade com parceiros externos e soluções de analytics
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

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

Assinatura do método:

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

+event: retorna void — não há sinal de sucesso/falha no ponto de chamada. O SDK descarta o evento silenciosamente quando o nome é nil ou está vazio, ou quando +start: ainda não foi chamado. Verifique 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

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

Assinatura do método:

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

Observação: O parâmetro args é um NSDictionary que contém um ou mais pares 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 in-app

Rastreie receitas de compras in-app (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: Veja as métricas de receita no dashboard da Singular
Export Logs: Acesse dados ETL detalhados para análise personalizada
Postbacks em tempo real: Envie eventos de receita para plataformas externas

Limitações dos 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 do evento 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)

Melhores práticas

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

Compras in-app sem assinatura

Integração com SKPaymentTransaction

Passe o objeto SKPaymentTransaction do StoreKit para o método iapComplete a fim de obter reporting enriquecido e validação de transações.

Benefícios:

Dados ricos: A Singular recebe os detalhes completos da transação para relatórios abrangentes
Prevenção de fraude: Os recibos de transação permitem a validação para combater fraudes in-app

Observações:

Objeto obrigatório: O método iapComplete requer o objeto SKPaymentTransaction
Conversão de moeda: Receitas em moedas diferentes são convertidas automaticamente para a moeda preferida 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 assinaturas

Implementação do evento de assinatura

Rastreie compras e renovações de assinatura para obter insights sobre o comportamento do usuário e a geração de receita recorrente.

Guia de implementação: Consulte o abrangente Guia técnico de implementação do evento de assinatura para obter instruções detalhadas sobre o rastreamento de assinaturas com o SDK da Singular.

Receita personalizada sem validação de compra

Rastreamento manual de receita

Rastreie a receita passando moeda, 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, a Singular não pode validar as transações. Recomendamos fortemente o uso dos métodos com 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 nome de evento, moeda, valor e atributos de transação opcionais especificados.

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 apps que usam o framework StoreKit2, use o método customRevenue com as representações JSON de transação e de produto.

Importante: A validação de compras não é suportada no StoreKit2. Os métodos requerem o formato jsonRepresentation para os objetos de transação e de 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 pelo SDK da Singular integrado ao seu app para obter a atribuição ideal. No entanto, a Singular pode coletar eventos de outras fontes quando necessário.

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

Importante:

Ocorrem discrepâncias quando os identificadores de dispositivo nas solicitações servidor a servidor não correspondem aos identificadores registrados pelo SDK da Singular:

Eventos antecipados: Se um evento chegar antes que o SDK da Singular registre 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 da Singular tiver registrado um identificador de dispositivo diferente daquele da solicitação servidor a servidor, o evento será atribuído de forma incorreta

Guias de rastreamento híbrido de eventos

Envio de eventos a partir 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: Durante eventos in-app de registro ou login, capture e envie os identificadores de dispositivo e armazene esses dados junto com o User ID no seu servidor. Atualize os identificadores quando os usuários gerarem novas sessões do app 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 do Singular Internal BI para enviar eventos em tempo real para o seu endpoint. Veja o Internal BI Postback FAQ
Detalhes de implementação: Revise a seção "Tracking Revenue" no guia de integração servidor a servidor

Envio de eventos a partir de um provedor de receita

Integre provedores terceirizados de receita como RevenueCat ou adapty para enviar receita de compras e assinaturas à Singular.

Provedores suportados:

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

Envio de eventos a partir do Segment

Habilite o Segment para enviar eventos à Singular em paralelo com o SDK da Singular 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.

SDK do iOS - Rastreamento de eventos in-app

Rastreamento de eventos in-app

Eventos e atributos padrão

Uso de eventos padrão

Envio de eventos

Diretrizes de implementação de eventos

Método event

Exemplos de uso

Método eventWithArgs

Exemplos de uso

Rastreamento de receita in-app

Melhores práticas

Compras in-app sem assinatura

Integração com SKPaymentTransaction

Método iapComplete

Exemplos de uso

Receita de assinaturas

Implementação do evento de assinatura

Receita personalizada sem validação de compra

Rastreamento manual de receita

Método revenue

Exemplos de uso

Método customRevenue

Exemplos de uso

Suporte ao StoreKit2

Rastreamento de receita com StoreKit2

Exemplos de uso

Rastreamento híbrido de eventos (avançado)

Guias de rastreamento híbrido de eventos

Envio de eventos a partir de um servidor interno

Envio de eventos a partir de um provedor de receita

Envio de eventos a partir do Segment