Documento

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

Uso de eventos padrão

O Singular suporta eventos padrãoque 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.

A sua equipa de UA, de marketing ou de 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 planeamento.

Cada evento suporta vários atributos. Consulte os atributos padrão recomendados por eventopara obter 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 do usuário.

Eventos padrão: Use o nome iOS do eventoda lista de eventos padrão, por exemplo, EVENT_SNG_LOGIN
Eventos personalizados: Para eventos exclusivos do seu aplicativo que não correspondam aos eventos padrão, use qualquer cadeia descritiva que esteja em conformidade com as limitações de caracteres

Limitações de eventos personalizados:

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

Método de evento

Comunicar eventos do utilizador sem informações adicionais para cenários de seguimento simples.

Assinatura do método:

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

Exemplos de utilização

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

Comunicar eventos de utilizador com informações adicionais utilizando 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 que contém um ou mais pares de valores chave. As chaves devem ser cadeias de caracteres e os valores podem ser de qualquer tipo permitido num 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

Acompanhe a receita de compras no aplicativo (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 por 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: Enviar eventos de receita para plataformas externas

Limitações de eventos de receita:

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

Melhores práticas

Nomenclatura padrão: Utilizar a convenção de nomenclatura de eventos e atributos padrãoda Singular
Idioma: Envie nomes de eventos de receita personalizados em inglês para melhorar a compatibilidade de postback da rede de anúncios
Valores diferentes de zero: Envie eventos de receita apenas quando o valor for maior ou menor que 0

Compra na aplicação sem subscrição

Integração SKPaymentTransaction

Passe o objeto SKPaymentTransactiondo StoreKit para o método iapComplete para obter relatórios enriquecidos e validação de transacções.

Benefícios:

Dados avançados: 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 a fraude in-app

Observações:

Objeto necessário: O método iapCompleterequer o objeto SKPaymentTransaction
Conversão de moeda: A receita em diferentes moedas é automaticamente convertida para a moeda preferida da sua organização
Nomes de eventos personalizados: Utilize o parâmetro withNamepara categorizar a receita por tipo de evento nos relatórios

Método iapComplete

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

Assinaturas de métodos:

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

Exemplos de utilização

// 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 do evento de subscrição

Acompanhe as compras e renovações de subscrições para obter informações sobre o comportamento do utilizador e a geração de receitas recorrentes.

Guia de implementação: Consulte o abrangente Guia de Implementação Técnica do Evento de Assinaturapara 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 a moeda, o valor e os detalhes opcionais do produto sem o objeto SKPaymentTransaction. Observe que esse método não fornece recibos de transação para validação.

Importante: ao usar esses métodos, a Singular não pode validar transações. É altamente recomendável usar os métodos SKPaymentTransaction descritos acima sempre que possível.

Método de receita

Envia 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

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

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 utilização

// 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 do StoreKit2

Rastreamento de receita do StoreKit2

Para aplicativos que usam a estrutura do StoreKit2, use o método customRevenuecom representações JSON de transação e produto.

Importante: a validação de compra não é compatível com o StoreKit2. Os métodos exigem o formato jsonRepresentationpara objetos de transação e produto.

Assinaturas de 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 de eventos híbrido (avançado)

Envie todos os eventos e receitas através do SDK 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 Singular SDK devem estar em conformidade com a documentação de eventos de servidor para servidor do Singular e fornecer identificadores de dispositivo correspondentes para atribuição correta.

Importante:

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

Eventos antecipados: Se um evento chegar antes de o Singular SDK registar o identificador do dispositivo, o evento torna-se a "primeira sessão" de um dispositivo desconhecido, resultando numa atribuição orgânica
Identificadores incompatíveis: Se o Singular SDK registar um identificador de dispositivo diferente do que consta do pedido de servidor para servidor, o evento será atribuído incorretamente

Guias de rastreamento de eventos híbridos

Envio de eventos de um servidor interno

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

Requisitos:

Capturar identificadores de dispositivo: Durante os eventos de registo ou início de sessão in-app, capture e passe identificadores de dispositivo e, em seguida, armazene estes dados com o ID de utilizador no seu servidor. Atualize os identificadores quando os usuários gerarem novas sessões de 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)
Actualizações em tempo real: Utilize o mecanismo de postback do Singular Internal BI para enviar eventos em tempo real para o seu ponto de extremidade. Consulte as FAQs sobre Postback do BI Interno
Detalhes de implementação: Reveja a secção "Tracking Revenue" no guia de Integração Servidor a Servidor

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

SDK para iOS - Acompanhamento de eventos na aplicação

Acompanhamento 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 de evento

Exemplos de utilização

Método eventWithArgs

Exemplos de uso

Rastreamento de receita no aplicativo

Melhores práticas

Compra na aplicação sem subscrição

Integração SKPaymentTransaction

Método iapComplete

Exemplos de utilização

Receita de assinatura

Implementação do evento de subscrição

Receita personalizada sem validação de compra

Rastreamento manual de receita

Método de receita

Exemplos de uso

Método customRevenue

Exemplos de utilização

Suporte do StoreKit2

Rastreamento de receita do StoreKit2

Exemplos de uso

Rastreamento de eventos híbrido (avançado)

Guias de rastreamento de eventos híbridos

Envio de eventos de um servidor interno

Envio de eventos de um fornecedor de receitas

Envio de eventos do Segment