Atribuição de receita de anúncios

Rastreie a receita de anúncios proveniente de plataformas de mediação e a atribua às campanhas de marketing que adquiriram seus usuários, oferecendo visibilidade completa do ROI sobre custos de campanha, compras dentro do aplicativo e monetização por anúncios.

Visão geral

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

A atribuição de receita de anúncios conecta a receita de anúncios de aplicativos móveis com as campanhas de aquisição de usuários que geraram as instalações, permitindo medir a rentabilidade real das campanhas, incluindo a monetização por anúncios.

Principais benefícios:

Visão unificada de ROI: Veja os custos de campanha, a receita in-app e a receita de anúncios em um único dashboard
Otimização de campanha: Envie os dados de receita de anúncios de volta para as redes de anúncios para melhorar o lance e a segmentação
Mensuração de LTV: Calcule o valor de vida completo do usuário incluindo a monetização por anúncios

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

Saiba mais: Consulte o FAQ de atribuição de receita de anúncios para detalhes completos sobre configuração, relatórios e resolução de problemas.

Requisitos de implementação

Diretrizes essenciais

Parâmetros obrigatórios do SingularAdData: Os argumentos do construtor adPlatform, currency, e revenue são todos obrigatórios. Se algum estiver ausente, vazio ou inválido, o SDK descarta silenciosamente a chamada para Singular.adRevenue() sem lançar uma exceção nem retornar um erro. Singular.adRevenue() também ignora silenciosamente quando o SDK ainda não foi inicializado — sempre confirme que Singular.init() foi executado antes de chamá-lo.

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.
Valide antes de enviar: Sempre valide os dados de receita e moeda antes de chamar Singular.adRevenue() . Dados incorretos não podem ser corrigidos após o envio.
Diferenças entre plataformas: Alguns SDKs reportam a receita em micros (divida por 1.000.000), enquanto outros reportam em unidades de moeda padrão. Consulte a documentação da sua plataforma.

Etapas de configuração

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

Atualize o SDK: Certifique-se de estar usando a versão mais recente do SDK da Singular.
Escolha a integração: Selecione abaixo a integração de plataforma de mediação que corresponde à sua configuração.
Implemente os callbacks: Adicione listeners de eventos pagos específicos da plataforma para capturar os dados de receita.
Valide os dados: Teste o relatório de receita e verifique se os dados aparecem no dashboard da Singular.

Integrações de plataforma

Integração com AdMob

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

Requisitos:

Habilite o rastreamento de eventos pagos na sua conta do AdMob (consulte Suporte do AdMob )
Implemente o Google Mobile Ads SDK para Android (consulte Guia de introdução )

Relatório de receita por plataforma: O AdMob reporta a receita de forma diferente por plataforma. O Android retorna a receita em micros (por exemplo, $0,005 = 5000). Divida adValue.valueMicros por 1.000.000 para converter para unidades de moeda padrão antes de enviar para a Singular.

Implementação

Defina um listener de eventos pagos ao carregar anúncios para capturar os dados de receita e enviá-los para a 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 com AppLovin MAX

Compartilhe a receita de anúncios em nível de impressão usando a AppLovin Impression-Level User Revenue API.

Requisitos:

Implemente o AppLovin MAX SDK (consulte Guia da Impression-Level Revenue API )
Inscreva-se no tópico max_revenue_events via AppLovin Communicator

Implementação

Trate as mensagens de receita por meio 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 com Unity LevelPlay (IronSource)

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

Requisitos:

Implemente o ironSource SDK (consulte Guia de introdução )
Habilite a flag ARM SDK Postbacks no seu dashboard do IronSource
Defina um listener de dados de impressão para receber os callbacks de receita

Saiba mais: Consulte a Documentação de receita de anúncios do IronSource para detalhes completos de configuração.

Implementação

Implemente o callback de sucesso de 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 TradPlus

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

Requisitos:

Defina o listener global de impressões via TradPlusSdk.setGlobalImpressionListener()
Trate o callback onImpressionSuccess para receber os dados de receita
Converta o eCPM de miliunidades para a moeda padrão (divida por 1000)

Implementação

Registre um listener global de impressões para rastrear todas as impressões de anúncios e a receita.

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 ecpm = tpAdInfo.ecpm ?: run {
                Log.w("TradPlus", "eCPM is null")
                return
            }
            val revenue = 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)

Integre qualquer plataforma de mediação usando a interface genérica SingularAdData .

Requisitos:

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

Precisã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 então 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);

Enriquecendo os dados de anúncios com atributos adicionais

SingularAdData expõe setters encadeáveis para metadados em nível de impressão. Use-os para enriquecer o evento com detalhes de placement, ad unit, agrupamento de mediação e precisão quando sua plataforma de mediação os fornecer. Os atributos definidos por esses métodos aparecem nos relatórios da Singular e nos postbacks posteriores.

Método	Descrição
`withNetworkName(String networkName)`	Sobrescreve o nome da rede (o padrão é a plataforma de anúncios passada ao construtor). Use na mediação quando a rede subjacente for diferente da plataforma de mediação.
`withAdType(String adType)`	Formato do anúncio (por exemplo, `"Rewarded"`, `"Interstitial"`, `"Banner"`).
`withAdGroupType(String adGroupType)`	Categorização do grupo de anúncios definida pela sua plataforma de mediação.
`withImpressionId(String impressionId)`	Identificador único da impressão, usado para deduplicação e conciliação.
`withAdPlacementName(String adPlacementName)`	Nome legível do placement (por exemplo, `"level_complete"`).
`withAdUnitId(String adUnitId)`	Identificador do ad unit específico da plataforma (por exemplo, `"ca-app-pub-..."` para AdMob).
`withAdUnitName(String adUnitName)`	Nome legível do ad unit.
`withAdGroupId(String adGroupId)`	Identificador do grupo de anúncios da plataforma de mediação.
`withAdGroupName(String adGroupName)`	Nome legível do grupo de anúncios.
`withAdGroupPriority(String adGroupPriority)`	Prioridade atribuída ao grupo de anúncios na cascata de mediação.
`withPrecision(String precision)`	Indicador de precisão da receita (por exemplo, `"publisher_provided"`, `"estimated"`, `"exact"`) quando a plataforma oferecer suporte.
`withPlacementId(String placementId)`	Identificador de placement específico da plataforma.
`withLimitDataSharing(boolean shouldLimitDataSharing)`	Sobrescreve o limite global de compartilhamento de dados para este evento de anúncio individual, por exemplo, quando um usuário optou por não receber anúncios personalizados.

Exemplo de uso em Kotlin:

val data = SingularAdData("AdMob", "USD", 0.05)
    .withAdUnitId("ca-app-pub-123456789/1234567890")
    .withAdType("Rewarded")
    .withAdPlacementName("level_complete")
    .withImpressionId("imp_abc123")
    .withPrecision("publisher_provided")

Singular.adRevenue(data)

Exemplo de uso em Java:

SingularAdData data = new SingularAdData("AdMob", "USD", 0.05)
    .withAdUnitId("ca-app-pub-123456789/1234567890")
    .withAdType("Rewarded")
    .withAdPlacementName("level_complete")
    .withImpressionId("imp_abc123")
    .withPrecision("publisher_provided");

Singular.adRevenue(data);

Testes e validação

Verificar o relatório de receita

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

Verifique os logs: Confirme que os logs do callback de receita aparecem com os valores e a moeda corretos.
Anúncios de teste: Carregue e exiba anúncios de teste para acionar os eventos de receita.
Verificação no dashboard: Confirme que a receita aparece no dashboard da Singular em até 24 horas.
Precisão dos dados: Valide se os valores de receita correspondem aos relatórios da sua plataforma de mediação.

Resolução de problemas: Se a receita não aparecer na Singular, verifique se:

A atribuição de receita de anúncios está habilitada 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 - Rastreamento de receita de anúncios

Atribuição de receita de anúncios

Visão geral

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

Requisitos de implementação

Diretrizes essenciais

Etapas de configuração

Integrações de plataforma

Integração com AdMob

Implementação

Integração com AppLovin MAX

Implementação

Integração com Unity LevelPlay (IronSource)

Implementação

Integração com TradPlus

Implementação

Integração genérica (outras plataformas)

Implementação

Enriquecendo os dados de anúncios com atributos adicionais

Testes e validação

Verificar o relatório de receita