Ad Revenue Attribution

Connect ad revenue to specific marketing campaigns that brought users to your app, providing complete visibility into campaign costs, in-app revenue, and ad revenue for accurate ROI measurement.

Overview

What is Ad Revenue Attribution

Ad Revenue Attribution ties mobile app ad revenue to the marketing campaigns that generated users, enabling you to measure true campaign performance by connecting user acquisition costs with lifetime revenue including ad monetization.

• Campaign ROI: View campaign cost, in-app purchases, and ad revenue in unified reports to calculate true return on ad spend
• Network Optimization: Send ad revenue data back to ad networks to improve bidding algorithms and campaign performance
• Data Sources: Supports user-level and impression-level data from mediation platforms including AdMob, AppLovin MAX, Unity LevelPlay (IronSource), and TradPlus

For complete details, see the Ad Revenue Attribution FAQ.

Implementation Requirements

Ad revenue tracking requires integration with your mediation platform SDK and configuration of revenue callbacks.

1. SDK Version: Update to the latest Singular Cordova SDK version
2. Mediation Platform: Integrate the Cordova-compatible SDK for your mediation platform or use a third-party plugin (AdMob, AppLovin MAX, IronSource, or TradPlus)
3. Revenue Callbacks: Implement platform-specific paid event handlers to capture impression-level revenue data
4. Validation Logic: Add revenue and currency validation before sending data to Singular

SDK Method

cordova.plugins.SingularCordovaSdk.adRevenue

Report ad revenue data to Singular with platform, currency, and revenue amount for attribution to the user's acquisition campaign.

Method Signature:

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

Parameters:

• adData.adPlatform: Mediation platform name (e.g., "AdMob", "AppLovin", "IronSource", "TradPlus")
• adData.currency: ISO 4217 three-letter currency code (e.g., "USD", "EUR")
• adData.revenue: Revenue amount in the specified currency (must be greater than 0)

For complete method documentation, see adRevenue reference.

AdMob Integration

Implement AdMob ad revenue tracking using paid event callbacks for impression-level revenue reporting across all ad formats.

Prerequisites

• Enable ad revenue reporting in your AdMob account. See AdMob Support
• Cordova is not officially supported by Google and requires a third-party plugin. AdMob Plus is recommended as the successor to cordova-plugin-admob-free. See the Getting Started Guide

Implementation Overview

When loading ad formats (App Open, Banner, Interstitial, Native, Rewarded), configure a paid event handler that triggers when ads generate revenue. Extract the revenue value and currency from the event data, validate both values, and send to Singular.

AdMob Rewarded Ad Example

Load and Track Rewarded Ads

Configure event listeners for rewarded ads and capture paid events for revenue tracking.

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

Implementation Notes:

• Revenue Conversion: AdMob returns revenue in micros (millionths)—divide by 1,000,000 to convert to dollars
• Data Validation: Ensure revenue is greater than 0 and currency code exists before sending
• Event Handling: Register all lifecycle events (load, show, dismiss, error) for complete ad management
• Preloading: Load the next ad immediately after dismissal to minimize wait times

Direct Platform Reporting

For scenarios without mediation platform integration or for custom ad implementations, report ad revenue directly using validated data.

Manual Ad Revenue Reporting

Create Helper Function

Build a reusable function with comprehensive validation for reporting ad revenue from any source.

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

Validation Features:

• Platform Validation: Ensures platform name is non-empty and trimmed
• Currency Validation: Verifies three-letter ISO 4217 code format and converts to uppercase
• Revenue Validation: Checks for positive number, excludes NaN and Infinity
• Error Handling: Try-catch block prevents crashes and provides detailed error logging

Best Practices

Data Validation

Implement robust validation to prevent incorrect data from reaching Singular analytics.

• Positive Revenue: Always verify revenue is greater than zero before sending
• Valid Currency: Use ISO 4217 codes and verify non-empty strings
• Platform Consistency: Use consistent platform names across your app (e.g., always "AdMob", not "Admob" or "ADMOB")
• Type Checking: Verify data types match expected values (number for revenue, string for currency/platform)
• Null Checks: Handle null, undefined, and empty values appropriately

Currency Handling

Ensure accurate currency reporting for multi-region apps and diverse ad networks.

• Verify Platform Currency: Check your mediation platform documentation for default currency (most use USD)
• Consistent Format: Always use uppercase three-letter ISO 4217 codes
• No Conversion: Report revenue in the currency provided by the ad network—do not convert currencies
• Currency Per Network: Different ad networks may report in different currencies—verify each separately

Platform-Specific Considerations

Handle platform differences in revenue reporting formats and units.

• AdMob: Revenue reported in micros—divide by 1,000,000 to convert to dollars on all platforms when using AdMob Plus
• TradPlus: eCPM reported in milli-units—divide by 1,000 to convert to dollars
• AppLovin: Revenue reported in dollars—use value directly
• IronSource: Revenue reported in dollars—use value directly

Error Handling and Logging

Implement comprehensive logging for debugging and monitoring ad revenue tracking.

• Validation Failures: Log detailed error messages when validation fails, including actual values received
• Success Logging: Log successful revenue reports during development to verify integration
• Production Logging: Reduce logging verbosity in production while maintaining error logs
• Debug Mode: Implement a debug flag to toggle detailed logging for troubleshooting

Testing and Validation

Verify ad revenue tracking implementation before deploying to production.

Testing Checklist

Validation Tests

1. Load Test Ads: Use test ad unit IDs from your mediation platform to verify ad loading
2. Verify Revenue Callbacks: Confirm paid event handlers trigger when test ads generate revenue
3. Check Data Formats: Verify revenue values convert correctly (micros to dollars for AdMob)
4. Validate Currency Codes: Ensure currency codes match expected format (USD, EUR, etc.)
5. Monitor Console Logs: Review console output for successful revenue reports and errors
6. Test Error Scenarios: Intentionally pass invalid data to verify validation logic catches errors

Singular Dashboard Verification

After implementation, verify data appears correctly in your Singular dashboard.

1. Wait for Processing: Allow 24-48 hours for initial data to process and appear in reports
2. Check Ad Revenue Reports: Navigate to ad revenue attribution reports in Singular dashboard
3. Verify Campaign Attribution: Confirm revenue attributes to correct acquisition campaigns
4. Validate Currency: Ensure revenue appears in correct currency
5. Monitor Platform Breakdown: Check that platform names (AdMob, etc.) appear correctly