SDK de React Native - Seguimiento de ingresos publicitarios

Seguir
Avatar
Jared Ornstead
Updated
Documento

Atribución de ingresos publicitarios

Conecte los ingresos por publicidad a las campañas de marketing específicas que llevaron a los usuarios a su aplicación, proporcionando una visibilidad completa de los costes de campaña, los ingresos dentro de la aplicación y los ingresos por publicidad para una medición precisa del ROI.

Visión general

Qué es la atribución de ingresos publicitarios

Ad Revenue Attribution vincula los ingresos publicitarios de las aplicaciones móviles a las campañas de marketing que generaron usuarios, lo que le permite medir el verdadero rendimiento de la campaña al conectar los costes de adquisición de usuarios con los ingresos de por vida, incluida la monetización de los anuncios.

  • ROI de la campaña: Vea el coste de la campaña, las compras dentro de la aplicación y los ingresos publicitarios en informes unificados para calcular el verdadero retorno de la inversión publicitaria.
  • Optimización de la red: Envíe los datos de ingresos publicitarios a las redes publicitarias para mejorar los algoritmos de puja y el rendimiento de las campañas.
  • Fuentes de datos: Admite datos a nivel de usuario y a nivel de impresión de plataformas de mediación como AdMob, AppLovin MAX, Unity LevelPlay (IronSource) y TradPlus.

Para más información, consulte las preguntas frecuentes sobre la atribución de ingresos publicitarios.

Consideracionesimportantes:

  1. Códigos de moneda: Utilice códigos de moneda ISO 4217 de tres letras (USD, EUR, INR). La mayoría de las plataformas de mediación informan en USD; verifique la divisa de su plataforma antes de la implementación.
  2. Precisión de los datos: Valide los datos de ingresos y divisas antes de enviarlos a Singular. Los datos incorrectos no pueden corregirse retroactivamente.

Requisitos de implementación

El seguimiento de los ingresos publicitarios requiere la integración con el SDK de su plataforma de mediación y la configuración de las retrollamadas de ingresos.

  1. Versión del SDK: Actualizar a la última versión del SDK de Singular React Native.
  2. Plataforma de mediación: Integrar el SDK de React Native para su plataforma de mediación (AdMob, AppLovin MAX, IronSource o TradPlus).
  3. Revenue Callbacks: Implemente manejadores de eventos pagados específicos de la plataforma para capturar datos de ingresos a nivel de impresión
  4. Lógica de validación: Añada validación de ingresos y divisas antes de enviar los datos a Singular

Método SDK

Singular.adRevenue

Envía los datos de ingresos publicitarios a Singular con la plataforma, la divisa y el importe de los ingresos para su atribución a la campaña de adquisición del usuario.

Firmadel método: 

static adRevenue(data: {
    adPlatform: string;
    currency: string;
    revenue: number;
}): void

Parámetros:

  • adPlatform: Nombre de la plataforma de mediación (por ejemplo, "AdMob", "AppLovin", "IronSource", "TradPlus").
  • divisa: Código de moneda ISO 4217 de tres letras (por ejemplo, "USD", "EUR")
  • ingresos: Importe de los ingresos en la divisa especificada (debe ser mayor que 0)

Para ver la documentación completa del método, consulte la referencia adRevenue.

Integraciones de plataformas

Integración con AdMob

Implemente el seguimiento de ingresos publicitarios de AdMob utilizando las devoluciones de llamada de eventos pagados del SDK de Google Mobile Ads para obtener informes de ingresos a nivel de impresión.

Requisitos previos

Descripción general de la implementación

Cuando cargue formatos de anuncios (App Open, Banner, Interstitial, Native, Rewarded), configure un controlador de eventos de pago que se active cuando los anuncios generen ingresos. Extraiga el valor de los ingresos y la divisa de los datos del evento, valide ambos valores y envíelos a Singular.

Diferencia de plataforma: AdMob informa de los ingresos de forma diferente según la plataforma. Android informa de los ingresos en micros (por ejemplo, 0,005 dólares aparece como 5.000), lo que requiere la división entre 1.000.000. iOS informa de los ingresos directamente en dólares (0,005). Ajuste la lógica de conversión en función de la detección de la plataforma.

Ejemplo de anuncio con recompensa de AdMob

Cargue un anuncio recompensado con AdMob y capture eventos pagados para realizar un seguimiento de los ingresos.

New ArchitectureOld Architecture 
// TurboModule direct API (React Native 0.76+ New Architecture)
import React, { useEffect } from 'react';
import NativeSingular from 'singular-react-native/jsNativeSingular';
import { RewardedAd, AdEventType } from 'react-native-google-mobile-ads';
import { Platform } from 'react-native';

const AD_UNIT_ID = 'ca-app-pub-xxxxxxxxxxxxx/yyyyyyyyyy';

export default function AdMobRevenueTracker() {
  useEffect(() => {
    loadRewardedAd();
  }, []);

  const loadRewardedAd = () => {
    // Create RewardedAd instance
    const rewardedAd = RewardedAd.createForAdRequest(AD_UNIT_ID);

    // Set up event listener for ad events
    rewardedAd.addAdEventListener((type, error, data) => {
      if (type === AdEventType.LOADED) {
        console.log('Rewarded ad loaded');
      } else if (type === AdEventType.ERROR) {
        console.error('Rewarded ad failed to load:', error);
      } else if (type === AdEventType.PAID_EVENT) {
        // Handle paid event with revenue data
        handleAdRevenue(data);
      }
    });

    // Load the ad
    rewardedAd.load();
  };

  const handleAdRevenue = (data) => {
    const { value, currencyCode } = data;

    // Validate revenue and currency
    if (!value || value <= 0) {
      console.error('Invalid ad revenue value:', value);
      return;
    }

    if (!currencyCode || currencyCode.trim() === '') {
      console.error('Invalid currency code:', currencyCode);
      return;
    }

    // Convert revenue based on platform
    let revenue;
    if (Platform.OS === 'android') {
      // Android reports in micros - convert to dollars
      revenue = value / 1_000_000.0;
    } else {
      // iOS reports in dollars directly
      revenue = value;
    }

    const adRevenueData = {
      adPlatform: 'AdMob',
      currency: currencyCode,
      revenue: revenue
    };

    // Send to Singular
    NativeSingular.adRevenue(adRevenueData);

    console.log('Ad Revenue reported to Singular:', adRevenueData);
  };

  return null;
}

Notas de implementación:

  • Detección de plataforma: Utilice Platform.OSpara determinar la lógica de conversión (Android divide por 1.000.000, iOS utiliza el valor directamente).
  • Validación de ingresos: Asegúrese de que los ingresos son superiores a 0 antes de enviar
  • Validación de moneda: Verificar que el código de moneda no está vacío
  • Registro de errores: Registre los datos no válidos para depuración sin enviarlos a Singular

Integración con AppLovin MAX

Implemente el seguimiento de ingresos publicitarios de AppLovin MAX mediante la API de ingresos de usuario a nivel de impresión para obtener informes de ingresos en tiempo real en todos los formatos publicitarios.

Requisitos previos

  • Integre el SDK React Native de AppLovin MAX. Consulte la Guía de introducción
  • Habilitar Impression-Level User Revenue API en el panel de control de AppLovin.

Descripción general de la implementación

Configure escuchadores de ingresos de anuncios para cada formato de anuncio (Interstitial, Rewarded, Banner, MRec, App Open) para capturar eventos de ingresos. Extraiga los ingresos de adInfo.revenue y envíelos a Singular con la divisa específica de la plataforma (normalmente USD).

Seguimiento de ingresos de AppLovin MAX

Configure escuchas de ingresos globales para todos los formatos de anuncios de AppLovin MAX.

New ArchitectureOld Architecture 
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
import {
  InterstitialAd,
  RewardedAd,
  BannerAd,
  MRecAd,
  AppOpenAd
} from 'react-native-applovin-max';

// Currency constant - AppLovin typically reports in USD
const CURRENCY = 'USD';

// Generic handler for ad revenue
const handleAdRevenue = (adInfo) => {
  if (!adInfo) {
    console.error('AdInfo is null or undefined');
    return;
  }

  const revenue = adInfo.revenue;

  // Validate revenue
  if (!revenue || revenue <= 0) {
    console.error('Invalid revenue value:', revenue);
    return;
  }

  const adRevenueData = {
    adPlatform: 'AppLovin',
    currency: CURRENCY,
    revenue: revenue
  };

  // Send to Singular
  NativeSingular.adRevenue(adRevenueData);

  console.log('AppLovin ad revenue reported:', adRevenueData);
};

// Set up listeners for each ad type
export const setupAppLovinRevenueTracking = () => {
  InterstitialAd.addAdRevenuePaidListener(handleAdRevenue);
  RewardedAd.addAdRevenuePaidListener(handleAdRevenue);
  BannerAd.addAdRevenuePaidListener(handleAdRevenue);
  MRecAd.addAdRevenuePaidListener(handleAdRevenue);
  AppOpenAd.addAdRevenuePaidListener(handleAdRevenue);

  console.log('AppLovin MAX revenue tracking initialized');
};

Notas de implementación:

  • Todos los formatos de anuncios: Registre escuchas para todos los tipos de anuncios que utilice su aplicación (Interstitial, Rewarded, Banner, MRec, App Open).
  • Divisa: AppLovin suele informar de los ingresos en USD; compruébelo en su panel de control.
  • Gestor compartido: Utilice una única función de gestión de ingresos para todos los formatos de anuncios a fin de garantizar una validación coherente.

Integración de Unity LevelPlay (IronSource)

Implemente el seguimiento de ingresos publicitarios de IronSource utilizando la API del SDK de ingresos a nivel de impresión (ILR) para datos a nivel de impresión de IronSource Ads y redes mediadas.

Requisitos previos

Descripción general de la implementación

Suscríbase al emisor de eventos onImpressionDataSuccess para recibir datos de impresiones. Extraiga los ingresos de impressionData.revenue y envíelos a Singular con la divisa USD.

Seguimiento de ingresos de IronSource

Configurar el receptor de eventos para las devoluciones de llamada de datos de impresión de IronSource.

New ArchitectureOld Architecture 
// TurboModule direct API (React Native 0.76+ New Architecture)
import { NativeModules, NativeEventEmitter } from 'react-native';
import NativeSingular from 'singular-react-native/jsNativeSingular';

const { IronSourceModule } = NativeModules;
const ironSourceEventEmitter = new NativeEventEmitter(IronSourceModule);

const AD_PLATFORM = 'IronSource';
const CURRENCY = 'USD'; // IronSource typically reports in USD

export const setupIronSourceRevenueTracking = () => {
  ironSourceEventEmitter.addListener('onImpressionDataSuccess', (impressionData) => {
    // Validate impression data
    if (!impressionData) {
      console.error('No impression data available');
      return;
    }

    const revenue = impressionData.revenue;

    // Validate revenue value
    if (!revenue || revenue <= 0) {
      console.error('Invalid revenue value:', revenue);
      return;
    }

    const adRevenueData = {
      adPlatform: AD_PLATFORM,
      currency: CURRENCY,
      revenue: revenue
    };

    // Send to Singular
    NativeSingular.adRevenue(adRevenueData);

    console.log('IronSource ad revenue reported:', adRevenueData);
  });

  console.log('IronSource revenue tracking initialized');
};

Notas de implementación:

  • Emisor de eventos nativo: IronSource utiliza el sistema de eventos nativo de React Native para las devoluciones de llamada de impresión
  • ARM Postbacks: Verifique que el indicador de ARM SDK Postbacks esté habilitado en el panel de IronSource.
  • Suscripción a eventos: Configure la escucha antes de inicializar el SDK de IronSource

Integración de TradPlus

Implemente el seguimiento de ingresos publicitarios de TradPlus mediante escuchas de impresiones globales para capturar datos de eCPM de impresiones publicitarias.

Requisitos previos

  • Integre el SDK TradPlus React Native con su aplicación.
  • Configure las unidades de anuncios TradPlus en su panel de control

Descripción general de la implementación

Suscribirse al evento onImpressionSuccess para recibir datos de impresiones de anuncios. Extraiga el valor eCPM de tpAdInfo.ecpm, conviértalo de milis a dólares (divídalo por 1000) y envíelo a Singular.

Conversión de eCPM: TradPlus informa del eCPM en mili-unidades. Divida el valor de eCPM por 1000 para convertirlo a importes en dólares antes de enviarlo a Singular.

Seguimiento de ingresos de TradPlus

Configure el receptor de eventos para las devoluciones de llamada de éxito de impresión de TradPlus.

New ArchitectureOld Architecture 
// TurboModule direct API (React Native 0.76+ New Architecture)
import { NativeModules, NativeEventEmitter } from 'react-native';
import NativeSingular from 'singular-react-native/jsNativeSingular';

const { TradPlusModule } = NativeModules;
const tradPlusEventEmitter = new NativeEventEmitter(TradPlusModule);

const AD_PLATFORM = 'TradPlus';
const CURRENCY = 'USD'; // TradPlus typically reports in USD

export const setupTradPlusRevenueTracking = () => {
  tradPlusEventEmitter.addListener('onImpressionSuccess', (tpAdInfo) => {
    // Validate ad info
    if (!tpAdInfo) {
      console.error('AdInfo is null');
      return;
    }

    // eCPM is reported in milli-units - convert to dollars
    if (!tpAdInfo.ecpm || typeof tpAdInfo.ecpm !== 'number') {
      console.error('Invalid eCPM value:', tpAdInfo.ecpm);
      return;
    }

    const revenue = tpAdInfo.ecpm / 1000.0;

    // Validate revenue after conversion
    if (revenue <= 0) {
      console.error('Revenue out of expected range:', revenue);
      return;
    }

    const adRevenueData = {
      adPlatform: AD_PLATFORM,
      currency: CURRENCY,
      revenue: revenue
    };

    // Send to Singular
    NativeSingular.adRevenue(adRevenueData);

    console.log('TradPlus ad revenue reported:', adRevenueData);
  });

  console.log('TradPlus revenue tracking initialized');
};

Notas de implementación:

  • Formato de eCPM: TradPlus informa del eCPM en mili-unidades; divídalo siempre por 1000 antes de enviarlo a Singular.
  • Comprobación de tipo: Verificar que eCPM es un número antes de la conversión
  • Validación post-conversión: Validar que los ingresos son mayores que 0 después de la división

Integración genérica

Implemente el seguimiento de ingresos publicitarios para plataformas de mediación personalizadas o integraciones directas utilizando el método genérico adRevenue().

Cuándo utilizar la integración genérica

  • Plataformas de mediación personalizadas no cubiertas por integraciones estándar
  • Integraciones directas de redes publicitarias sin mediación
  • Cálculos de ingresos publicitarios del lado del servidor reenviados a la aplicación
  • Pruebas de seguimiento de ingresos publicitarios con datos simulados

Ejemplo de implementación genérica

Cree una función reutilizable para informar de los ingresos publicitarios de cualquier fuente con la validación adecuada.

New ArchitectureOld Architecture 
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

/**
 * Report ad revenue to Singular with validation
 * 
 * @param {string} adPlatform - Name of the ad platform or mediation provider
 * @param {string} currency - ISO 4217 three-letter currency code (e.g., 'USD', 'EUR')
 * @param {number} revenue - Revenue amount in the specified currency
 */
export const reportAdRevenue = (adPlatform, currency, revenue) => {
  // Validate platform
  if (!adPlatform || adPlatform.trim() === '') {
    console.error('Invalid ad platform:', adPlatform);
    return;
  }

  // Validate currency code
  if (!currency || currency.trim() === '' || currency.length !== 3) {
    console.error('Invalid currency code:', currency);
    return;
  }

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

  const adRevenueData = {
    adPlatform: adPlatform.trim(),
    currency: currency.toUpperCase().trim(),
    revenue: revenue
  };

  // Send to Singular
  NativeSingular.adRevenue(adRevenueData);

  console.log('Ad Revenue reported to Singular:', adRevenueData);
};

// Example usage
export const trackCustomAdRevenue = () => {
  // Example: Custom mediation platform
  reportAdRevenue('CustomPlatform', 'USD', 0.05);

  // Example: Direct network integration
  reportAdRevenue('FacebookAudienceNetwork', 'EUR', 0.03);
};

Funciones de validación:

  • Validación de plataforma: Garantiza que el nombre de la plataforma no esté vacío y esté recortado.
  • Validación de divisas: Verifica el formato del código ISO 4217 de tres letras y lo convierte a mayúsculas.
  • Validación de ingresos: Comprueba si el número es positivo, excluye NaN e Infinito
  • Seguridad de tipos: La interfaz TypeScript garantiza la comprobación de tipos en tiempo de compilación

Mejores prácticas

Validación de datos

Implemente una validación robusta para evitar que datos incorrectos lleguen a Singular analytics.

  • Ingresos positivos: Compruebe siempre que los ingresos son superiores a cero antes de enviarlos
  • Moneda válida: Utilice códigos ISO 4217 y verifique que las cadenas no estén vacías.
  • Consistencia de plataforma: Utilice nombres de plataforma coherentes en toda su aplicación (por ejemplo, siempre "AdMob", no "Admob" o "ADMOB")
  • Comprobación de tipos: Verifique que los tipos de datos coincidan con los valores esperados (número para ingresos, cadena para moneda/plataforma).
  • Comprobación de nulos: Maneje adecuadamente los valores nulos, indefinidos y vacíos.

Crítico: Los datos de ingresos publicitarios incorrectos no pueden corregirse retroactivamente en Singular. Valide siempre los datos antes de llamar a Singular.adRevenue().

Gestión de divisas

Asegúrese de que los informes de divisas son precisos para aplicaciones multiregión y diversas redes publicitarias.

  • Verifique la moneda de la plataforma: Compruebe la documentación de su plataforma de mediación para conocer la divisa predeterminada (la mayoría utiliza USD).
  • Formato coherente: Utilice siempre códigos ISO 4217 de tres letras en mayúscula.
  • Sin conversión: Comunique los ingresos en la divisa proporcionada por la red publicitaria; no convierta divisas.
  • Divisa por red: Diferentes redes publicitarias pueden informar en diferentes monedas; verifique cada una por separado.

Consideraciones específicas de la plataforma

Tenga en cuenta las diferencias entre plataformas en cuanto a formatos y unidades de informes de ingresos.

  • AdMob Android: Los ingresos se informan en micros; divídalos por 1.000.000 para convertirlos a dólares.
  • AdMob iOS: Ingresos en dólares: utilice el valor directamente sin conversión.
  • TradPlus: eCPM reportado en mili-unidades-dividir por 1.000 para convertir a dólares
  • AppLovin: ingresos en dólares, valor de uso directo
  • IronSource: Ingresos en dólares - valor de uso directo

Gestión de errores y registro

Implemente un registro exhaustivo para depurar y supervisar el seguimiento de los ingresos publicitarios.

  • Fallos de validación: Registre mensajes de error detallados cuando falle la validación, incluidos los valores reales recibidos.
  • Registro de éxitos: Registre los informes de ingresos correctos en desarrollo con la plataforma, la divisa y el importe.
  • Supervisión de la producción: Utilice servicios de seguimiento de errores (Sentry, Bugsnag) para supervisar los fallos de validación en producción.
  • Anomalías de ingresos: Alerta sobre valores de ingresos inusualmente altos o bajos que puedan indicar problemas de integración
  • Cobertura de plataformas: Supervise qué plataformas publicitarias notifican ingresos para asegurarse de que todas están integradas correctamente.

Estrategia de pruebas

Verifique la implementación del seguimiento de ingresos publicitarios antes de la implementación de producción.

  1. Anuncios de prueba: Utilice unidades de anuncios de prueba de su plataforma de mediación durante el desarrollo.
  2. Validar eventos: Compruebe en el panel de Singular los eventos de ingresos publicitarios tras las impresiones de anuncios de prueba.
  3. Verificación de divisas: Confirme que los códigos de moneda aparecen correctamente en los informes de Singular
  4. Precisión de la plataforma: Asegúrese de que los nombres de las plataformas sean coherentes y reconocibles en los informes
  5. Importes de ingresos: Verificar que los importes de ingresos coinciden con los rangos esperados para los bloques de anuncios de prueba
  6. Multiplataforma: Pruebe tanto en iOS como en Android para verificar la lógica de conversión específica de la plataforma

Optimización del rendimiento

Minimice el impacto en el rendimiento del seguimiento de ingresos publicitarios en su aplicación.

  • Procesamiento asíncrono: Las retrollamadas de ingresos se ejecutan de forma asíncrona, sin bloquear el hilo principal.
  • Validación mínima: Mantenga la lógica de validación simple y rápida (comprobaciones de tipo, comprobaciones de rango)
  • Consideración de lotes: Para aplicaciones de gran volumen, considere el procesamiento por lotes si su backend de análisis lo admite.
  • Gestión de errores: Utilice bloques try-catch para evitar que los errores de seguimiento de ingresos bloqueen la aplicación.

Verificación y resolución de problemas

Verificación de la implementación

Confirme que los datos de ingresos publicitarios fluyen correctamente a Singular.

  1. Habilite los anuncios de prueba: Configure el modo de prueba en su plataforma de mediación
  2. Activar impresiones: Muestre anuncios de prueba y active eventos pagados
  3. Comprobar registros: Verifique que los registros de seguimiento de ingresos aparezcan en la consola con los valores correctos
  4. Verificación del panel de control: Compruebe los eventos de ingresos publicitarios en el panel de Singular (puede tardar entre 15 y 30 minutos)
  5. Detalles del evento: Verifique la moneda, la plataforma y los importes de los ingresos en los detalles del evento de Singular.

Problemas comunes

  • No hay eventos de ingresos: Compruebe que los controladores de eventos de pago se registran antes de cargar los anuncios y que el SDK de mediación se inicializa correctamente.
  • Cero ingresos: Compruebe la lógica de conversión específica de la plataforma (micros a dólares para Android AdMob, milis a dólares para TradPlus).
  • Moneda incorrecta: Compruebe que el código de moneda coincide con lo que indica la plataforma de mediación (consulte la documentación de la plataforma).
  • Nombre de plataforma incorrecto: Utilice nombres de plataforma coherentes que coincidan con las plataformas reconocidas por Singular.
  • Ausencia de eventos: Asegúrese de que Singular SDK se inicializa antes de que se produzcan eventos de ingresos publicitarios.
  • Eventos duplicados: Verifique que los controladores de eventos pagados se registren una sola vez, no en cada carga de anuncios

Recursos adicionales: Para obtener información detallada, consulte las preguntas frecuentes sobre la atribución de ingresos publicitariosy la referencia de métodos del SDK de React Native.