SDK do Unity - Acompanhamento de receitas de anúncios

Seguir
Avatar
Jared Ornstead
Updated
Documento

Atribuição de receitas de anúncios

Acompanhe as receitas de anúncios das plataformas de mediação e atribua-as às campanhas de marketing que adquiriram os seus utilizadores, fornecendo uma visibilidade completa do ROI dos custos das campanhas, das compras na aplicação e da monetização da publicidade.

Visão geral

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

A atribuição de receitas de anúncios liga as receitas de publicidade de aplicações móveis às campanhas de aquisição de utilizadores que conduziram a instalações de aplicações, permitindo-lhe medir a verdadeira rentabilidade da campanha, incluindo a monetização de anúncios.

Principais benefícios:

  • Visão unificada do ROI: Veja os custos da campanha, a receita in-app e a receita de anúncios em um único painel
  • Otimização de campanhas: Envie os dados da receita de anúncios de volta às redes de anúncios para melhorar os lances e a segmentação
  • Medição de LTV: Calcular o valor total do tempo de vida do utilizador, incluindo a monetização da publicidade

Fontes de dados: Os dados de receita de anúncios geralmente vêm da sua plataforma de mediação (por exemplo, AdMob, AppLovin MAX, IronSource) no nível do usuário ou no nível da impressão. O Singular suporta vários métodos de integração para receber esses dados.

Saiba mais: Consulte as Perguntas frequentes sobre atribuição de receita de anúnciospara obter detalhes abrangentes sobre configuração, relatórios e solução de problemas.

Requisitos de implementação

Diretrizes críticas

A precisão dos dados é fundamental:

  1. Códigos de moeda: Use códigos de moeda ISO 4217 de três letras (por exemplo, USD, EUR, INR). Muitas plataformas de mediação reportam em USD - verifique a moeda da sua plataforma antes da implementação
  2. Validar antes de enviar: Valide sempre os dados da receita e da moeda antes de ligar para SingularSDK.AdRevenue(). Os dados incorrectos não podem ser corrigidos após o envio
  3. Diferenças entre plataformas: A AdMob reporta a receita em micros no Unity e no Android (divida por 1.000.000), mas em unidades padrão no iOS. Verifique a documentação da sua plataforma

Passos de configuração

Siga estas etapas para implementar a atribuição de receita de anúncios:

  1. Atualizar o SDK: Verifique se você está usando a versão mais recente do Singular SDK
  2. Escolher integração: Selecione a integração da plataforma de mediação abaixo que corresponde à sua configuração
  3. Implementar retornos de chamada: Adicione ouvintes de eventos pagos específicos da plataforma para capturar dados de receita
  4. Validar dados: Teste os relatórios de receita e verifique se os dados aparecem no painel do Singular

Integrações de plataforma

Integração com a AdMob

Acompanhe a receita de anúncios do Google AdMob usando o ouvinte de eventos pagos para relatórios de receita no nível da impressão.

Requisitos:

Relatório de receita da plataforma: A AdMob reporta as receitas de forma diferente consoante a plataforma. A receita de anúncios de US$ 0,005 será retornada como 5000 nas plataformas Unity e Android, mas como 0,005 no iOS. Para iOS, envie 0,005 diretamente para o SDK do Singular. Em outras plataformas, converta adValue de micros para dólares antes de enviá-lo para a Singular.

Implementação

Registe um manipulador de eventos OnAdPaid ao carregar anúncios para capturar dados de receitas e enviá-los para a Singular.

C# 
using UnityEngine;
using Singular;
using GoogleMobileAds.Api;

public class AdMobRevenueTracking : MonoBehaviour
{
    private const string AD_UNIT_ID = "YOUR_AD_UNIT_ID";
    private RewardedAd rewardedAd;
    
    void Start()
    {
        // Initialize Mobile Ads SDK
        MobileAds.Initialize(initStatus =>
        {
            Debug.Log("AdMob initialized");
            LoadRewardedAd();
        });
    }
    
    private void LoadRewardedAd()
    {
        // Create ad request
        AdRequest adRequest = new AdRequest();
        
        // Load rewarded ad
        RewardedAd.Load(AD_UNIT_ID, adRequest, (RewardedAd ad, LoadAdError error) =>
        {
            if (error != null || ad == null)
            {
                Debug.LogError($"Rewarded ad failed to load: {error}");
                return;
            }
            
            Debug.Log("Rewarded ad loaded");
            rewardedAd = ad;
            
            // Register event handlers
            RegisterEventHandlers(ad);
        });
    }
    
    private void RegisterEventHandlers(RewardedAd ad)
    {
        // Raised when the ad is estimated to have earned money
        ad.OnAdPaid += (AdValue adValue) =>
        {
            // Validate and ensure revenue data is within an expected range
            float revenue = adValue.Value / 1_000_000f; // Convert micros to dollars
            string currency = adValue.CurrencyCode;
            
            // Check if revenue is positive and currency is valid
            if (revenue > 0 && !string.IsNullOrEmpty(currency))
            {
                // Construct and send the Singular Ad Revenue Event
                SingularAdData data = new SingularAdData(
                    "AdMob",
                    currency,
                    revenue
                );
                
                SingularSDK.AdRevenue(data);
                
                // Log the revenue data for debugging purposes
                Debug.Log($"Ad Revenue reported to Singular: {data}");
            }
            else
            {
                Debug.LogError($"Invalid ad revenue data: revenue = {revenue}, currency = {currency}");
            }
        };
        
        // Additional event handlers
        ad.OnAdFullScreenContentOpened += () =>
        {
            Debug.Log("Rewarded ad full screen content opened");
        };
        
        ad.OnAdFullScreenContentClosed += () =>
        {
            Debug.Log("Rewarded ad full screen content closed");
            // Load next ad
            LoadRewardedAd();
        };
        
        ad.OnAdFullScreenContentFailed += (AdError error) =>
        {
            Debug.LogError($"Rewarded ad failed to show: {error}");
            // Load next ad
            LoadRewardedAd();
        };
    }
    
    public void ShowRewardedAd()
    {
        if (rewardedAd != null && rewardedAd.CanShowAd())
        {
            rewardedAd.Show((Reward reward) =>
            {
                Debug.Log($"User earned reward: {reward.Type} - {reward.Amount}");
            });
        }
        else
        {
            Debug.Log("Rewarded ad is not ready yet");
        }
    }
}

Integração AppLovin MAX

Acompanhe a receita de anúncios no nível de impressão usando a API de receita do usuário no nível de impressão do AppLovin.

Requisitos:

  • Implementar o AppLovin MAX SDK para Unity (consulte o Guia de Introdução)
  • Anexar callbacks de receita paga a todos os formatos de anúncio que estiver a utilizar

Implementação

Registar OnAdRevenuePaidEvent callbacks para capturar e enviar dados de receita para Singular.

C# 
using UnityEngine;
using Singular;

public class AppLovinRevenueTracking : MonoBehaviour
{
    void Start()
    {
        // Attach callbacks based on the ad format(s) you are using
        MaxSdkCallbacks.Interstitial.OnAdRevenuePaidEvent += OnAdRevenuePaidEvent;
        MaxSdkCallbacks.Rewarded.OnAdRevenuePaidEvent += OnAdRevenuePaidEvent;
        MaxSdkCallbacks.Banner.OnAdRevenuePaidEvent += OnAdRevenuePaidEvent;
        MaxSdkCallbacks.MRec.OnAdRevenuePaidEvent += OnAdRevenuePaidEvent;
    }
    
    private void OnAdRevenuePaidEvent(string adUnitId, MaxSdkBase.AdInfo adInfo)
    {
        double revenue = adInfo.Revenue;
        
        if (revenue > 0)
        {
            // Create a SingularAdData object with relevant information
            SingularAdData adData = new SingularAdData(
                "AppLovin",
                "USD", // AppLovin typically reports in USD
                revenue
            );
            
            // Send ad revenue data to Singular
            SingularSDK.AdRevenue(adData);
            
            Debug.Log($"Ad Revenue reported to Singular: {revenue} USD from {adUnitId}");
        }
        else
        {
            Debug.LogError("Failed to parse valid revenue value from ad info or revenue is not greater than 0");
        }
    }
    
    void OnDestroy()
    {
        // Detach callbacks to prevent memory leaks
        MaxSdkCallbacks.Interstitial.OnAdRevenuePaidEvent -= OnAdRevenuePaidEvent;
        MaxSdkCallbacks.Rewarded.OnAdRevenuePaidEvent -= OnAdRevenuePaidEvent;
        MaxSdkCallbacks.Banner.OnAdRevenuePaidEvent -= OnAdRevenuePaidEvent;
        MaxSdkCallbacks.MRec.OnAdRevenuePaidEvent -= OnAdRevenuePaidEvent;
    }
}

Integração do Unity LevelPlay (IronSource)

Acompanhe a receita no nível de impressão da ironSource e de redes mediadas usando o SDK da IronSource.

Requisitos:

  • Implementar o IronSource SDK do Unity (consulte o Guia de introdução)
  • Ativar o sinalizador ARM SDK Postbacks no seu painel IronSource
  • Definir o ouvinte de dados de impressão para receber callbacks de receita

Saiba mais: Consulte a documentação sobre receita de anúncios do IronSourcepara obter detalhes completos sobre a configuração.

Implementação

Inscreva-se no site ImpressionDataReadyEvent para capturar e enviar dados de receita.

C# 
using UnityEngine;
using Singular;

public class IronSourceRevenueTracking : MonoBehaviour
{
    void Start()
    {
        // Ensure the listener is added before initializing the SDK
        IronSourceEvents.onImpressionDataReadyEvent += ImpressionDataReadyEvent;
        
        // Initialize the IronSource SDK here if not already done
        // IronSource.Agent.init("YOUR_IRONSOURCE_APP_KEY");
    }
    
    private void ImpressionDataReadyEvent(IronSourceImpressionData impressionData)
    {
        if (impressionData != null)
        {
            // Ensure revenue value is valid
            double? revenue = impressionData.revenue;
            
            if (revenue.HasValue && revenue.Value > 0)
            {
                // Create SingularAdData object with appropriate values
                SingularAdData adData = new SingularAdData(
                    "IronSource",
                    "USD", // IronSource typically reports in USD
                    revenue.Value
                );
                
                // Send the Ad Revenue data to Singular
                SingularSDK.AdRevenue(adData);
                
                // Log the data for debugging
                Debug.Log($"Ad Revenue reported to Singular: AdPlatform: {adData.AdPlatform}, " +
                         $"Currency: {adData.Currency}, Revenue: {adData.Revenue}");
            }
            else
            {
                Debug.LogError($"Invalid revenue value: {revenue}");
            }
        }
        else
        {
            Debug.LogError("Impression data is null");
        }
    }
    
    void OnDestroy()
    {
        // Detach the callback to prevent memory leaks
        IronSourceEvents.onImpressionDataReadyEvent -= ImpressionDataReadyEvent;
    }
}

Integração com o TradPlus

Capture a receita de anúncios da mediação do TradPlus usando o ouvinte de impressão global.

Requisitos:

  • Adicionar o ouvinte global de impressões de anúncios através de TradplusAds.Instance().AddGlobalAdImpression()
  • Tratar a chamada de retorno OnGlobalAdImpression para receber dados de receitas
  • Converter eCPM de miliunidades para moeda padrão (dividir por 1000)

Implementação

Registar um ouvinte de impressões global para controlar todas as impressões de anúncios e receitas.

C# 
using UnityEngine;
using Singular;
using System.Collections.Generic;
using System.Globalization;

public class TradPlusRevenueTracking : MonoBehaviour
{
    private const string TAG = "TradPlusRevenue";
    
    void Start()
    {
        // Add Global Ad Impression Listener
        TradplusAds.Instance().AddGlobalAdImpression(OnGlobalAdImpression);
    }
    
    void OnGlobalAdImpression(Dictionary<string, object> adInfo)
    {
        // Ensure adInfo is not null
        if (adInfo == null)
        {
            Debug.LogError($"{TAG}: AdInfo is null");
            return;
        }
        
        // Ensure eCPM is present and valid
        if (!adInfo.ContainsKey("ecpm") || adInfo["ecpm"] == null)
        {
            Debug.LogError($"{TAG}: eCPM value is null or missing");
            return;
        }
        
        // Parse the eCPM value
        if (!double.TryParse(adInfo["ecpm"].ToString(), NumberStyles.Float | NumberStyles.AllowThousands, 
            CultureInfo.InvariantCulture, out double revenue))
        {
            Debug.LogError($"{TAG}: Failed to parse eCPM value");
            return;
        }
        
        // Convert eCPM to revenue (eCPM is in milli-units)
        revenue = revenue / 1000.0;
        
        // Validate the revenue value
        if (revenue <= 0)
        {
            Debug.LogError($"{TAG}: Ad Revenue value out of expected range: {revenue}");
            return;
        }
        
        // Create SingularAdData object with the necessary fields
        SingularAdData data = new SingularAdData(
            "TradPlus",
            "USD",
            revenue
        );
        
        // Send the Ad Revenue data to Singular
        SingularSDK.AdRevenue(data);
        
        // Log the data for debugging purposes
        Debug.Log($"{TAG}: Ad Revenue reported to Singular: AdPlatform: {data.AdPlatform}, " +
                 $"Currency: {data.Currency}, Revenue: {data.Revenue}");
    }
}

Integração genérica (outras plataformas)

Integrar qualquer plataforma de mediação utilizando a interface genérica SingularAdData.

Requisitos:

  • Acesso aos dados de receita no nível de impressão da sua plataforma de mediação
  • Valor da receita em unidades monetárias padrão (não micros)
  • Código de moeda ISO 4217 (por exemplo, USD, EUR, INR)

Exatidão dos dados: Valide os dados de receita e moeda antes de enviar para a Singular. Dados incorretos não podem ser corrigidos após o envio.

Implementação

Crie um objeto SingularAdData com o nome da plataforma, a moeda e a receita e, em seguida, chame SingularSDK.AdRevenue().

C# 
using UnityEngine;
using Singular;

public class GenericAdRevenueTracking : MonoBehaviour
{
    // Function to report ad revenue to Singular
    public void ReportAdRevenue(string adPlatform, string currency, float revenue)
    {
        // Validate the input: ensure revenue is positive and currency is not null or empty
        if (revenue > 0 && !string.IsNullOrEmpty(currency))
        {
            // Create a SingularAdData object with the validated data
            SingularAdData data = new SingularAdData(
                adPlatform,
                currency,
                revenue
            );
            
            // Send the ad revenue data to Singular
            SingularSDK.AdRevenue(data);
            
            // Log the reported data for debugging
            Debug.Log($"Ad Revenue reported to Singular: Platform = {adPlatform}, " +
                     $"Currency = {currency}, Revenue = {revenue}");
        }
        else
        {
            // Log a warning if validation fails
            Debug.LogWarning($"Invalid ad revenue data: Platform = {adPlatform}, " +
                           $"Revenue = {revenue}, Currency = {currency}");
        }
    }
    
    // Example usage
    void ExampleUsage()
    {
        // Report revenue from a custom mediation platform
        ReportAdRevenue("MyMediationPlatform", "USD", 0.05f);
    }
}

Teste e validação

Verificar relatórios de receita

Teste a implementação da receita de anúncios para garantir que os dados fluam corretamente para a Singular.

  1. Verifique os logs: Verifique se os logs de retorno de chamada de receita aparecem com valores e moeda corretos no Unity Console
  2. Testar anúncios: Carregue e exiba anúncios de teste para acionar eventos de receita
  3. Verificação do painel: Confirmar se a receita aparece no painel do Singular dentro de 24 horas
  4. Precisão de dados: Validar se os valores da receita correspondem aos relatórios da plataforma de mediação

Solução de problemas: Se a receita não aparecer no Singular, verifique se:

  • A atribuição de receita de anúncios está activada na sua conta Singular
  • Os valores de receita são maiores que 0
  • Os códigos de moeda são códigos ISO 4217 válidos
  • O nome da plataforma corresponde ao formato esperado pela Singular
  • Os manipuladores de eventos são registados corretamente antes do carregamento dos anúncios