广告收入归属

将广告收入与为您的应用程序带来用户的特定营销活动联系起来，全面了解营销活动成本、应用程序内收入和广告收入，从而准确衡量投资回报率。

概述

什么是广告收入归因

广告收入归属将移动应用程序的广告收入与产生用户的营销活动联系起来，通过将用户获取成本与包括广告货币化在内的终生收入联系起来，使您能够衡量真实的营销活动绩效。

• 营销活动投资回报率：在统一的报告中查看营销活动成本、应用内购买和广告收入，计算广告支出的真实回报。
• 网络优化：将广告收入数据发送回广告网络，以改进竞价算法和广告系列性能
• 数据源：支持来自 AdMob、AppLovin MAX、Unity LevelPlay (IronSource) 和 TradPlus 等中介平台的用户级和印象级数据。

有关完整的详细信息，请参阅广告收入归因常见问题解答。

实施要求

广告收入跟踪需要与您的调解平台 SDK 集成，并配置收入回调。

1. SDK 版本：更新至最新的 Singular Cordova SDK 版本
2. 调解平台：为您的中介平台集成与 Cordova 兼容的 SDK，或使用第三方插件（AdMob、AppLovin MAX、IronSource 或 TradPlus
3. 收入回调：实施平台特定的付费事件处理程序，以获取印象级收入数据
4. 验证逻辑：在向 Singular 发送数据前添加收入和货币验证

SDK 方法

cordova.plugins.SingularCordovaSdk.adRevenue

向 Singular 报告广告收入数据，包括平台、货币和收入金额，以便归因于用户的获取活动。

方法签名：

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

参数：

• adData.adPlatform：中介平台名称（例如，"AdMob"、"AppLovin"、"IronSource"、"TradPlus
• adData.currency：货币：ISO 4217 三字母货币代码（如 "USD"、"EUR
• adData.revenue：以指定货币计算的收入金额（必须大于 0

有关完整的方法文档，请参阅adRevenue 参考资料。

AdMob 集成

使用付费事件回调实施 AdMob 广告收入跟踪，以便在所有广告格式中提供印象级收入报告。

前提条件

• 在您的 AdMob 账户中启用广告收入报告。请参阅AdMob 支持
• Cordova 不受 Google 官方支持，需要第三方插件。建议将AdMob Plus作为 cordova-plugin-admob-free 的后续版本。请参阅入门指南

实施概述

在加载广告格式（App Open、Banner、Interstitial、Native、Rewarded）时，配置一个付费事件处理程序，当广告产生收入时触发。 从事件数据中提取收入值和货币，验证这两个值并发送给 Singular。

AdMob 奖励广告示例

加载和跟踪有奖广告

为有奖广告配置事件侦听器，并捕获付费事件以跟踪收入。

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();
}
        

实施注意事项：

• 收入转换：AdMob 返回的收入单位为微米（百万分之一）--除以 1,000,000 转换为美元
• 数据验证：发送前确保收入大于 0 且存在货币代码
• 事件处理：注册所有生命周期事件（加载、显示、取消、错误），以实现完整的广告管理
• 预加载：退出后立即加载下一个广告，最大限度地减少等待时间

直接平台报告

对于未集成中介平台的情况或自定义广告实施，可直接使用验证数据报告广告收入。

手动广告收入报告

创建辅助功能

创建一个具有全面验证功能的可重复使用函数，用于报告来自任何来源的广告收入。

// 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);

验证功能：

• 平台验证：确保平台名称非空且经过修剪
• 货币验证：验证三个字母的 ISO 4217 代码格式并转换为大写字母
• 收入验证：检查正数，排除 NaN 和无穷大
• 错误处理Try-catch 块可防止崩溃，并提供详细的错误记录

最佳实践

数据验证

实施强大的验证，防止不正确的数据进入 Singular 分析。

• 正收入：发送前始终验证收入大于零
• 有效货币：使用 ISO 4217 代码并验证非空字符串
• 平台一致性：在整个应用程序中使用一致的平台名称（例如，始终使用 "AdMob"，而不是 "Admob "或 "ADMOB"）。
• 类型检查：验证数据类型是否与预期值相匹配（数字表示收入，字符串表示货币/平台
• 空值检查：适当处理空值、未定义值和空值

货币处理

确保多地区应用程序和不同广告网络的货币报告准确无误。

• 验证平台货币：检查您的调解平台文档中的默认货币（大多数使用美元
• 统一格式：始终使用大写三个字母的 ISO 4217 代码
• 无转换：以广告网络提供的货币报告收入，不要转换货币
• 每个网络使用的货币：不同的广告网络可能使用不同的货币报告，请分别核实

平台特定考虑因素

处理收入报告格式和单位方面的平台差异。

• AdMob：使用 AdMob Plus 时，在所有平台上以微米为单位报告收入--除以 1,000,000 换算成美元
• TradPlus：以毫单位报告的 eCPM--除以 1,000 换算成美元
• AppLovin：以美元为单位报告收入--直接使用数值
• IronSource：以美元为单位报告收入--直接使用价值

错误处理和日志记录

实施全面的日志记录，用于调试和监控广告收入跟踪。

• 验证失败：在验证失败时记录详细的错误信息，包括收到的实际值
• 成功日志：在开发过程中记录成功的收入报告，以验证集成
• 生产日志记录：在生产过程中减少日志冗长度，同时保留错误日志
• 调试模式：实施调试标志，切换详细日志，以便排除故障

测试和验证

在部署到生产环境之前，验证广告收入跟踪的实施情况。

测试清单

验证测试

1. 加载测试广告：使用中介平台的测试广告单元 ID 验证广告加载情况
2. 验证收入回调：确认付费事件处理程序在测试广告产生收入时触发
3. 检查数据格式：验证收入值的正确转换（AdMob 将微元转换为美元
4. 验证货币代码：确保货币代码符合预期格式（美元、欧元等
5. 监控控制台日志：查看控制台输出的成功收入报告和错误
6. 测试错误场景：故意传递无效数据，以验证验证逻辑是否捕获错误

单一仪表板验证

实施后，验证数据是否正确显示在 Singular 面板中。

1. 等待处理：在 24-48 小时内处理初始数据并将其显示在报告中
2. 检查广告收入报告：导航至 Singular 面板中的广告收入归因报告
3. 验证广告系列归属：确认正确收购活动的收入属性
4. 验证货币：确保收入以正确的货币显示
5. 监控平台细分：检查平台名称（AdMob 等）是否正确显示