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 normalmente vêm de 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:

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
Validar antes de enviar: Valide sempre os dados da receita e da moeda antes de ligar para Singular.adRevenue(). Os dados incorrectos não podem ser corrigidos após o envio
Diferenças de plataforma: Alguns SDKs informam a receita em micros (dividir por 1.000.000), enquanto outros informam em unidades monetárias padrão. Verifique a documentação da sua plataforma

Passos de configuração

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

Atualizar o SDK: Verifique se você está usando a versão mais recente do Singular SDK
Escolher integração: Selecione a integração da plataforma de mediação abaixo que corresponde à sua configuração
Implementar retornos de chamada: Adicione ouvintes de eventos pagos específicos da plataforma para capturar dados de receita
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:

Ativar o seguimento de eventos pagos na sua conta AdMob (consulte Suporte AdMob)
Implementar o SDK do Google Mobile Ads para Android (consulte o Guia de introdução)

Relatório de receita da plataforma: A AdMob reporta as receitas de forma diferente consoante a plataforma. O Android apresenta a receita em micros (por exemplo, $0,005 = 5000). Divida adValue.valueMicros por 1.000.000 para converter em unidades monetárias padrão antes de enviar para o Singular.

Implementação

Defina um ouvinte de evento pago ao carregar anúncios para capturar dados de receita e enviá-los para o Singular.

import com.singular.sdk.Singular
import com.singular.sdk.SingularAdData
import com.google.android.gms.ads.AdRequest
import com.google.android.gms.ads.rewarded.RewardedAd
import com.google.android.gms.ads.rewarded.RewardedAdLoadCallback

private const val AD_UNIT_ID = "YOUR_AD_UNIT_ID"

class AdManager(private val context: Context) {
    private var rewardedAd: RewardedAd? = null

    fun loadRewardedAd() {
        val adRequest = AdRequest.Builder().build()
        
        RewardedAd.load(context, AD_UNIT_ID, adRequest, 
            object : RewardedAdLoadCallback() {
                override fun onAdLoaded(ad: RewardedAd) {
                    rewardedAd = ad
                    
                    // Set full screen content callback
                    rewardedAd?.fullScreenContentCallback = 
                        object : FullScreenContentCallback() {
                            override fun onAdShowedFullScreenContent() {
                                Log.d("AdManager", "Rewarded ad displayed")
                            }
                            
                            override fun onAdDismissedFullScreenContent() {
                                Log.d("AdManager", "Rewarded ad dismissed")
                            }
                        }
                    
                    // Set paid event listener for revenue tracking
                    rewardedAd?.setOnPaidEventListener { adValue ->
                        // Convert revenue from micros to standard units
                        val revenue = adValue.valueMicros / 1_000_000.0
                        val currency = adValue.currencyCode
                        
                        // Validate revenue data before sending
                        if (revenue > 0 && !currency.isNullOrEmpty()) {
                            val data = SingularAdData(
                                "AdMob",
                                currency,
                                revenue
                            )
                            
                            Singular.adRevenue(data)
                            Log.d("AdManager", "Ad revenue sent: $revenue $currency")
                        } else {
                            Log.w("AdManager", "Invalid revenue: $revenue $currency")
                        }
                    }
                }
                
                override fun onAdFailedToLoad(error: LoadAdError) {
                    Log.e("AdManager", "Ad failed to load: ${error.message}")
                }
            })
    }
}

import com.singular.sdk.Singular;
import com.singular.sdk.SingularAdData;
import com.google.android.gms.ads.AdRequest;
import com.google.android.gms.ads.rewarded.RewardedAd;
import com.google.android.gms.ads.rewarded.RewardedAdLoadCallback;

private static final String AD_UNIT_ID = "YOUR_AD_UNIT_ID";

public class AdManager {
    private RewardedAd rewardedAd;
    private Context context;
    
    public AdManager(Context context) {
        this.context = context;
    }
    
    public void loadRewardedAd() {
        AdRequest adRequest = new AdRequest.Builder().build();
        
        RewardedAd.load(context, AD_UNIT_ID, adRequest, 
            new RewardedAdLoadCallback() {
                @Override
                public void onAdLoaded(RewardedAd ad) {
                    rewardedAd = ad;
                    
                    // Set full screen content callback
                    rewardedAd.setFullScreenContentCallback(
                        new FullScreenContentCallback() {
                            @Override
                            public void onAdShowedFullScreenContent() {
                                Log.d("AdManager", "Rewarded ad displayed");
                            }
                            
                            @Override
                            public void onAdDismissedFullScreenContent() {
                                Log.d("AdManager", "Rewarded ad dismissed");
                            }
                        });
                    
                    // Set paid event listener for revenue tracking
                    rewardedAd.setOnPaidEventListener(new OnPaidEventListener() {
                        @Override
                        public void onPaidEvent(AdValue adValue) {
                            // Convert revenue from micros to standard units
                            double revenue = adValue.getValueMicros() / 1_000_000.0;
                            String currency = adValue.getCurrencyCode();
                            
                            // Validate revenue data before sending
                            if (revenue > 0 && currency != null && !currency.isEmpty()) {
                                SingularAdData data = new SingularAdData(
                                    "AdMob",
                                    currency,
                                    revenue
                                );
                                
                                Singular.adRevenue(data);
                                Log.d("AdManager", "Ad revenue sent: " + revenue + " " + currency);
                            } else {
                                Log.w("AdManager", "Invalid revenue: " + revenue + " " + currency);
                            }
                        }
                    });
                }
                
                @Override
                public void onAdFailedToLoad(LoadAdError error) {
                    Log.e("AdManager", "Ad failed to load: " + error.getMessage());
                }
            });
    }
}

Integração AppLovin MAX

Partilhe a receita de anúncios ao nível da impressão utilizando a API AppLovin Impression-Level User Revenue.

Requisitos:

Implementar o AppLovin MAX SDK (consulte o Guia da API de receita no nível de impressão)
Subscrever o tópico max_revenue_events através do AppLovin Communicator

Implementação

Tratar mensagens de receitas através do callback do AppLovin Communicator.

import com.singular.sdk.Singular
import com.singular.sdk.SingularAdData
import com.applovin.communicator.AppLovinCommunicatorMessage

override fun onMessageReceived(message: AppLovinCommunicatorMessage) {
    // Check for revenue events topic
    if (message.topic == "max_revenue_events") {
        val adData: Bundle? = message.messageData
        
        // Extract and validate revenue value
        val revenueValue = adData?.getDouble("revenue", 0.0) ?: 0.0
        
        if (revenueValue > 0) {
            val data = SingularAdData(
                "AppLovin",
                "USD",  // AppLovin typically reports in USD
                revenueValue
            )
            
            Singular.adRevenue(data)
            Log.d("AppLovin", "Ad revenue sent: $revenueValue USD")
        } else {
            Log.w("AppLovin", "Invalid revenue value: $revenueValue")
        }
    }
}

import com.singular.sdk.Singular;
import com.singular.sdk.SingularAdData;
import com.applovin.communicator.AppLovinCommunicatorMessage;

@Override
public void onMessageReceived(AppLovinCommunicatorMessage message) {
    // Check for revenue events topic
    if ("max_revenue_events".equals(message.getTopic())) {
        Bundle adData = message.getMessageData();
        
        // Extract and validate revenue value
        double revenueValue = (adData != null) ? 
            adData.getDouble("revenue", 0.0) : 0.0;
        
        if (revenueValue > 0) {
            SingularAdData data = new SingularAdData(
                "AppLovin",
                "USD",  // AppLovin typically reports in USD
                revenueValue
            );
            
            Singular.adRevenue(data);
            Log.d("AppLovin", "Ad revenue sent: " + revenueValue + " USD");
        } else {
            Log.w("AppLovin", "Invalid revenue value: " + revenueValue);
        }
    }
}

Integração do Unity LevelPlay (IronSource)

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

Requisitos:

Implementar o SDK do ironSource (consulte o Guia de Introdução)
Ativar o sinalizador ARM SDK Postbacks no painel do 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

Implemente o callback de sucesso dos dados de impressão para capturar e enviar a receita.

import com.singular.sdk.Singular
import com.singular.sdk.SingularAdData
import com.ironsource.mediationsdk.impressionData.ImpressionData

fun onImpressionDataSuccess(impressionData: ImpressionData?) {
    // Validate impression data
    if (impressionData == null) {
        Log.d("IronSource", "No impression data available")
        return
    }
    
    // Extract and validate revenue
    val revenue = impressionData.revenue?.toDouble() ?: 0.0
    if (revenue <= 0) {
        Log.w("IronSource", "Invalid revenue: $revenue")
        return
    }
    
    // Create and send ad revenue data
    val data = SingularAdData(
        "IronSource",
        "USD",  // IronSource typically reports in USD
        revenue
    )
    
    Singular.adRevenue(data)
    Log.d("IronSource", "Ad revenue sent: $revenue USD")
}

import com.singular.sdk.Singular;
import com.singular.sdk.SingularAdData;
import com.ironsource.mediationsdk.impressionData.ImpressionData;

public void onImpressionDataSuccess(ImpressionData impressionData) {
    // Validate impression data
    if (impressionData == null) {
        Log.d("IronSource", "No impression data available");
        return;
    }
    
    // Extract and validate revenue
    double revenue = (impressionData.getRevenue() != null) ?
        impressionData.getRevenue().doubleValue() : 0.0;
        
    if (revenue <= 0) {
        Log.w("IronSource", "Invalid revenue: " + revenue);
        return;
    }
    
    // Create and send ad revenue data
    SingularAdData data = new SingularAdData(
        "IronSource",
        "USD",  // IronSource typically reports in USD
        revenue
    );
    
    Singular.adRevenue(data);
    Log.d("IronSource", "Ad revenue sent: " + revenue + " USD");
}

Integração com o TradPlus

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

Requisitos:

Definir o ouvinte global de impressões através de TradPlusSdk.setGlobalImpressionListener()
Tratar a chamada de retorno onImpressionSuccess 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.

import com.singular.sdk.Singular
import com.singular.sdk.SingularAdData
import com.tradplus.ads.mgr.GlobalImpressionManager
import com.tradplus.ads.base.bean.TPAdInfo

// Set global impression listener
TradPlusSdk.setGlobalImpressionListener(
    object : GlobalImpressionManager.GlobalImpressionListener {
        override fun onImpressionSuccess(tpAdInfo: TPAdInfo?) {
            // Validate ad info
            if (tpAdInfo == null) {
                Log.w("TradPlus", "AdInfo is null")
                return
            }
            
            // Convert eCPM from milli-units to dollars
            val revenue = tpAdInfo.ecpm.toDouble() / 1000.0
            
            // Validate revenue
            if (revenue <= 0) {
                Log.w("TradPlus", "Invalid revenue: $revenue")
                return
            }
            
            // Create and send ad revenue data
            val data = SingularAdData(
                "TradPlus",
                "USD",
                revenue
            )
            
            Singular.adRevenue(data)
            Log.d("TradPlus", "Ad revenue sent: $revenue USD")
        }
    }
)

import com.singular.sdk.Singular;
import com.singular.sdk.SingularAdData;
import com.tradplus.ads.mgr.GlobalImpressionManager;
import com.tradplus.ads.base.bean.TPAdInfo;

// Set global impression listener
TradPlusSdk.setGlobalImpressionListener(
    new GlobalImpressionManager.GlobalImpressionListener() {
        @Override
        public void onImpressionSuccess(TPAdInfo tpAdInfo) {
            // Validate ad info
            if (tpAdInfo == null) {
                Log.w("TradPlus", "AdInfo is null");
                return;
            }
            
            // Validate eCPM is not null
            if (tpAdInfo.getEcpm() == null) {
                Log.w("TradPlus", "eCPM is null");
                return;
            }
            
            // Convert eCPM from milli-units to dollars
            double revenue = tpAdInfo.getEcpm().doubleValue() / 1000.0;
            
            // Validate revenue
            if (revenue <= 0) {
                Log.w("TradPlus", "Invalid revenue: " + revenue);
                return;
            }
            
            // Create and send ad revenue data
            SingularAdData data = new SingularAdData(
                "TradPlus",
                "USD",
                revenue
            );
            
            Singular.adRevenue(data);
            Log.d("TradPlus", "Ad revenue sent: " + revenue + " USD");
        }
    }
);

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 Singular.adRevenue().

import com.singular.sdk.Singular
import com.singular.sdk.SingularAdData

fun reportAdRevenue(adPlatform: String, currency: String, revenue: Double) {
    // Validate revenue
    if (revenue <= 0) {
        Log.w("AdRevenue", "Invalid revenue: $revenue")
        return
    }
    
    // Validate currency
    if (currency.isEmpty()) {
        Log.w("AdRevenue", "Invalid currency: $currency")
        return
    }
    
    // Create ad revenue data object
    val data = SingularAdData(
        adPlatform,
        currency,
        revenue
    )
    
    // Send to Singular
    Singular.adRevenue(data)
    Log.d("AdRevenue", "Revenue sent: $revenue $currency from $adPlatform")
}

// Example usage
reportAdRevenue("MyMediationPlatform", "USD", 0.05)

import com.singular.sdk.Singular;
import com.singular.sdk.SingularAdData;

public void reportAdRevenue(String adPlatform, String currency, double revenue) {
    // Validate revenue
    if (revenue <= 0) {
        Log.w("AdRevenue", "Invalid revenue: " + revenue);
        return;
    }
    
    // Validate currency
    if (currency == null || currency.isEmpty()) {
        Log.w("AdRevenue", "Invalid currency: " + currency);
        return;
    }
    
    // Create ad revenue data object
    SingularAdData data = new SingularAdData(
        adPlatform,
        currency,
        revenue
    );
    
    // Send to Singular
    Singular.adRevenue(data);
    Log.d("AdRevenue", "Revenue sent: " + revenue + " " + currency + 
        " from " + adPlatform);
}

// Example usage
reportAdRevenue("MyMediationPlatform", "USD", 0.05);

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.

Verifique os logs: Verifique se os logs de retorno de chamada de receita aparecem com os valores e a moeda corretos
Testar anúncios: Carregue e exiba anúncios de teste para acionar eventos de receita
Verificação do painel: Confirmar se a receita aparece no painel do Singular dentro de 24 horas
Precisão dos 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

SDK do Android - Controlo de receitas de anúncios

Atribuição de receitas de anúncios

Visão geral

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

Requisitos de implementação

Diretrizes críticas

Passos de configuração

Integrações de plataforma

Integração com a AdMob

Implementação

Integração AppLovin MAX

Implementação

Integração do Unity LevelPlay (IronSource)

Implementação

Integração com o TradPlus

Implementação

Integração genérica (outras plataformas)

Implementação

Teste e validação

Verificar relatórios de receita