Atribuição de receitas de anúncios

Ligue as receitas de anúncios a campanhas de marketing específicas que trouxeram utilizadores à sua aplicação, proporcionando uma visibilidade completa dos custos da campanha, das receitas in-app e das receitas de anúncios para uma medição precisa do ROI.

Descrição geral

O que é a atribuição de receitas de anúncios

A Atribuição de receitas de anúncios associa as receitas de anúncios de aplicações móveis às campanhas de marketing que geraram utilizadores, permitindo-lhe medir o verdadeiro desempenho da campanha, ligando os custos de aquisição de utilizadores às receitas vitalícias, incluindo a monetização de anúncios.

• ROI da campanha: Visualize o custo da campanha, as compras in-app e a receita de anúncios em relatórios unificados para calcular o verdadeiro retorno dos gastos com anúncios
• Otimização de redes: Envie os dados de receita de anúncios de volta às redes de anúncios para melhorar os algoritmos de licitação e o desempenho da campanha
• Fontes de dados: Suporta dados ao nível do utilizador e ao nível da impressão de plataformas de mediação, incluindo AdMob, AppLovin MAX, Unity LevelPlay (IronSource) e TradPlus

Para obter detalhes completos, consulte as Perguntas frequentes sobre atribuição de receita de anúncios.

Requisitos de implementação

O rastreamento de receita de anúncios requer integração com o SDK da plataforma de mediação e configuração de callbacks de receita.

1. Versão do SDK: Atualizar para a versão mais recente do SDK do Singular Cordova
2. Plataforma de mediação: Integrar o SDK compatível com o Cordova para sua plataforma de mediação ou usar um plug-in de terceiros (AdMob, AppLovin MAX, IronSource ou TradPlus)
3. Callbacks de receita: Implemente manipuladores de eventos pagos específicos da plataforma para capturar dados de receita no nível da impressão
4. Lógica de validação: Adicionar validação de receita e moeda antes de enviar dados para o Singular

Método SDK

cordova.plugins.SingularCordovaSdk.adRevenue

Relata dados de receita de anúncios para o Singular com plataforma, moeda e valor da receita para atribuição à campanha de aquisição do usuário.

Assinatura do método:

cordova.plugins.SingularCordovaSdk.adRevenue(adData: Object): void

Parâmetros:

• adData.adPlatform: Nome da plataforma de mediação (por exemplo, "AdMob", "AppLovin", "IronSource", "TradPlus")
• adData.currency: Código de moeda de três letras ISO 4217 (por exemplo, "USD", "EUR")
• adData.revenue: Valor da receita na moeda especificada (deve ser maior que 0)

Para obter a documentação completa do método, consulte a referência adRevenue.

Integração com a AdMob

Implemente o rastreamento de receita de anúncios da AdMob usando retornos de chamada de eventos pagos para relatórios de receita no nível da impressão em todos os formatos de anúncio.

Pré-requisitos

• Ative o relatório de receita de anúncios na sua conta da AdMob. Consulte Suporte do AdMob
• O Cordova não é oficialmente suportado pelo Google e requer um plug-in de terceiros. O AdMob Plus é recomendado como sucessor do cordova-plugin-admob-free. Consulte o Guia de introdução

Visão geral da implementação

Ao carregar formatos de anúncio (App Open, Banner, Interstitial, Native, Rewarded), configure um manipulador de eventos pagos que é acionado quando os anúncios geram receita. Extraia o valor da receita e a moeda dos dados do evento, valide os dois valores e envie para o Singular.

Exemplo de anúncio premiado da AdMob

Carregar e monitorizar anúncios recompensados

Configure ouvintes de eventos para anúncios recompensados e capture eventos pagos para rastreamento de receita.

document.addEventListener('deviceready', initializeAdMob, false);

async function initializeAdMob() {
  const admob = window.cordova.plugins.AdMobPlus;
  
  // Initialize RewardedAd with your ad unit ID
  const rewarded = admob.RewardedAd.create({
    adUnitId: 'ca-app-pub-xxxxxxxxxxxxx/yyyyyyyyyy',
    isTesting: true // Set to false for production
  });

  // Handle the 'paid' event to capture revenue details
  rewarded.on('paid', (event) => {
    const { value, currencyCode } = event;
    
    // Validate revenue and currency data
    if (value > 0 && currencyCode) {
      // Convert from micros to dollars
      const revenueAmount = value / 1_000_000.0;
      
      // Create ad data object
      const adData = new cordova.plugins.SingularCordovaSdk.SingularAdData(
        'AdMob',
        currencyCode,
        revenueAmount
      );

      // Send Ad Revenue data to Singular
      cordova.plugins.SingularCordovaSdk.adRevenue(adData);

      // Log for debugging
      console.log('Ad Revenue reported to Singular:', {
        adPlatform: 'AdMob',
        currency: currencyCode,
        revenue: revenueAmount
      });
    } else {
      console.error('Invalid ad revenue data:', { value, currencyCode });
    }
  });

  // Handle ad lifecycle events
  rewarded.on('load', async () => {
    console.log('Rewarded ad loaded');
    await rewarded.load(); // Preload next ad
  });

  rewarded.on('show', () => {
    console.log('Rewarded ad shown');
  });

  rewarded.on('dismiss', async () => {
    console.log('Rewarded ad dismissed');
    await rewarded.load(); // Load new ad for future use
  });

  rewarded.on('error', (error) => {
    console.error('Error with rewarded ad:', error);
  });

  // Initial ad load
  await rewarded.load();
}
        

Notas de implementação:

• Conversão de receita: A AdMob retorna a receita em micros (milionésimos) - divida por 1.000.000 para converter em dólares
• Validação de dados: Verifique se a receita é maior que 0 e se o código da moeda existe antes de enviar
• Tratamento de eventos: Registe todos os eventos do ciclo de vida (carregar, mostrar, rejeitar, erro) para uma gestão completa do anúncio
• Pré-carregamento: Carregue o próximo anúncio imediatamente após a rejeição para minimizar os tempos de espera

Relatório direto da plataforma

Para cenários sem integração da plataforma de mediação ou para implementações de anúncios personalizados, comunique diretamente as receitas dos anúncios utilizando dados validados.

Relatório manual de receitas de anúncios

Criar função auxiliar

Crie uma função reutilizável com validação abrangente para relatar a receita de anúncios de qualquer fonte.

// Reusable ad revenue reporting function with validation
function reportAdRevenue(mediationPlatform, currencyCode, revenueAmount) {
  // Validate mediation platform
  if (!mediationPlatform || typeof mediationPlatform !== 'string' || mediationPlatform.trim() === '') {
    console.error('Invalid mediation platform:', mediationPlatform);
    return;
  }

  // Validate currency code (ISO 4217 format)
  if (!currencyCode || typeof currencyCode !== 'string' || currencyCode.length !== 3) {
    console.error('Invalid currency code:', currencyCode);
    return;
  }

  // Validate revenue amount
  if (typeof revenueAmount !== 'number' || revenueAmount <= 0 || isNaN(revenueAmount) || !isFinite(revenueAmount)) {
    console.error('Invalid revenue amount:', revenueAmount);
    return;
  }

  try {
    // Create SingularAdData object
    const adData = new cordova.plugins.SingularCordovaSdk.SingularAdData(
      mediationPlatform,
      currencyCode.toUpperCase(), // Ensure uppercase
      revenueAmount
    );

    // Report Ad Revenue to Singular
    cordova.plugins.SingularCordovaSdk.adRevenue(adData);

    // Log success
    console.log('Ad Revenue reported successfully:', {
      mediationPlatform: adData.mediationPlatform,
      currencyCode: adData.currencyCode,
      revenueAmount: adData.revenueAmount
    });
  } catch (error) {
    // Log any errors that occur during the process
    console.error('Failed to report Ad Revenue:', error);
  }
}

// Usage examples
document.addEventListener('deviceready', function() {
  // Example: Report revenue from a custom ad network
  reportAdRevenue('CustomNetwork', 'USD', 0.05);
  
  // Example: Report revenue from direct ad placement
  reportAdRevenue('FacebookAudienceNetwork', 'EUR', 0.03);
}, false);

Caraterísticas de validação:

• Validação de plataforma: Assegura que o nome da plataforma não está vazio e está cortado
• Validação de moeda: Verifica o formato de código ISO 4217 de três letras e converte-o em maiúsculas
• Validação de receita: Verifica se o número é positivo, exclui NaN e Infinito
• Tratamento de erros: O bloco Try-catch evita falhas e fornece um registo de erros detalhado

Melhores práticas

Validação de dados

Implemente uma validação robusta para evitar que dados incorretos cheguem à análise da Singular.

• Receita positiva: Sempre verifique se a receita é maior que zero antes de enviar
• Moeda válida: Use códigos ISO 4217 e verifique se as strings não estão vazias
• Consistência da plataforma: Utilize nomes de plataforma consistentes em toda a aplicação (por exemplo, sempre "AdMob" e não "Admob" ou "ADMOB")
• Verificação de tipo: Verifique se os tipos de dados correspondem aos valores esperados (número para receita, cadeia de caracteres para moeda/plataforma)
• Verificações de nulos: Tratar adequadamente os valores nulos, indefinidos e vazios

Tratamento de moeda

Garanta relatórios precisos de moeda para aplicativos de várias regiões e diversas redes de anúncios.

• Verificar a moeda da plataforma: Verifique a documentação da plataforma de mediação quanto à moeda padrão (a maioria usa USD)
• Formato consistente: Utilize sempre códigos ISO 4217 de três letras em maiúsculas
• Sem conversão: Comunicar as receitas na moeda fornecida pela rede de publicidade - não converter moedas
• Moeda por rede: Diferentes redes de publicidade podem comunicar em diferentes moedas - verifique cada uma separadamente

Considerações específicas da plataforma

Trate as diferenças de plataforma nos formatos e unidades de relatório de receita.

• AdMob: Receita relatada em micros - divida por 1.000.000 para converter em dólares em todas as plataformas ao usar o AdMob Plus
• TradPlus: eCPM relatado em mili-unidades - divida por 1.000 para converter em dólares
• AppLovin: receita relatada em dólares - use o valor diretamente
• IronSource: Receita relatada em dólares - valor de uso direto

Tratamento de erros e registo

Implemente um registo abrangente para depurar e monitorizar o acompanhamento das receitas dos anúncios.

• Falhas de validação: Registre mensagens de erro detalhadas quando a validação falhar, incluindo os valores reais recebidos
• Registo de sucesso: Registar relatórios de receitas bem sucedidas durante o desenvolvimento para verificar a integração
• Registo de produção: Reduzir a verbosidade do registo em produção, mantendo os registos de erros
• Modo de depuração: Implementar um sinalizador de depuração para ativar o registo detalhado para resolução de problemas

Teste e validação

Verifique a implementação do controlo de receitas de anúncios antes de o implementar na produção.

Lista de verificação de testes

Testes de validação

1. Teste de carga de anúncios: Utilize IDs de blocos de anúncios de teste da sua plataforma de mediação para verificar o carregamento de anúncios
2. Verificar retornos de chamada de receita: Confirme se os manipuladores de eventos pagos são acionados quando os anúncios de teste geram receitas
3. Verificar formatos de dados: Verificar se os valores de receita são convertidos corretamente (micros para dólares para a AdMob)
4. Validar códigos de moeda: Certifique-se de que os códigos de moeda correspondam ao formato esperado (USD, EUR, etc.)
5. Monitorar logs do console: Analise a saída do console para relatórios de receita bem-sucedidos e erros
6. Testar cenários de erro: Passar intencionalmente dados inválidos para verificar se a lógica de validação detecta erros

Verificação do painel único

Após a implementação, verifique se os dados aparecem corretamente no seu painel Singular.

1. Aguardar o processamento: Aguarde de 24 a 48 horas para que os dados iniciais sejam processados e apareçam nos relatórios
2. Verificar relatórios de receita de anúncios: Navegue até os relatórios de atribuição de receita de anúncios no painel do Singular
3. Verificar atribuição de campanha: Confirmar atributos de receita para corrigir campanhas de aquisição
4. Validar moeda: Garantir que a receita apareça na moeda correta
5. Monitorar a divisão da plataforma: Verificar se os nomes das plataformas (AdMob, etc.) aparecem corretamente