Ad View Event

The Ad View Event is sent through the /webhook endpoint and tracks ad impressions for attribution.

Endpoint

POST /webhook

When to Call

Send an ad view event every time a user views an ad:

Rewarded video ads
Interstitial ads
Banner ad impressions
Native ad views

Timing: Send this event when the ad impression is confirmed by your ad network. For rewarded videos, send after the user completes the video.

Example Request

curl -X POST https://analytics.geeklab.app/webhook \
  -H "Content-Type: application/json" \
  -H "geeklab-api-key: your_api_key" \
  -d '{
    "type": "custom.ad",
    "created_at": "2024-10-10 10:20:00",
    "creativeToken": "abc123def456",
    "device_name": "MacBook Pro",
    "device_model": "MacBookPro18,3",
    "os_system": "macOS 14.5",
    "utc_offset": "-07:00",
    "retention_day": "0",
    "payload": {
      "ad_id": "rewarded_level_complete",
      "name": "Level Complete Reward",
      "source": "rewarded_video",
      "media_source": "admob",
      "channel": "paid",
      "watch_time": 30,
      "reward": true,
      "value": 0.015,
      "currency": "usd",
      "total_ad_value": 0.045
    }
  }'

Response

Error Responses

400 Bad Request - Missing required fields

401 Unauthorized - Invalid API key

Ad Type Examples

Rewarded Video Ad

{
  "type": "custom.ad",
  "payload": {
    "ad_id": "rewarded_extra_life",
    "name": "Extra Life Reward Ad",
    "source": "rewarded_video",
    "media_source": "unity_ads",
    "channel": "paid",
    "watch_time": 30,
    "reward": true,
    "value": 0.025,
    "currency": "usd",
    "total_ad_value": 0.07
  }
}

Interstitial Ad

{
  "type": "custom.ad",
  "payload": {
    "ad_id": "interstitial_level_end",
    "name": "Level End Interstitial",
    "source": "interstitial",
    "media_source": "applovin",
    "channel": "paid",
    "watch_time": 5,
    "reward": false,
    "value": 0.008,
    "currency": "usd",
    "total_ad_value": 0.078
  }
}

{
  "type": "custom.ad",
  "payload": {
    "ad_id": "banner_bottom",
    "name": "Bottom Banner",
    "source": "banner",
    "media_source": "admob",
    "channel": "paid",
    "watch_time": 0,
    "reward": false,
    "value": 0.0005,
    "currency": "usd",
    "total_ad_value": 0.0785
  }
}

Field Guidelines

Calculating Ad Value

Value calculation: Use estimated revenue from your ad network. This is typically eCPM / 1000 for a single impression.

Example calculations:

eCPM of $15.00 → value: 0.015
eCPM of $25.00 → value: 0.025
eCPM of $0.50 → value: 0.0005

Common Media Sources

Media Source	Value
Google AdMob	`admob`
Unity Ads	`unity_ads`
AppLovin	`applovin`
ironSource	`ironsource`
Meta Audience Network	`meta_an`
Vungle	`vungle`

Ad Source Types

Source Type	Value	Description
Rewarded Video	`rewarded_video`	User watches for reward
Interstitial	`interstitial`	Full-screen between content
Banner	`banner`	Persistent display ad
Native	`native`	Integrated content ad
App Open	`app_open`	Shown on app launch

Ad Revenue Attribution

Ad view events enable powerful analytics in Audiencelab:

ARPDAU - Average revenue per daily active user
Ad revenue by source - Compare performance across ad networks
Ad revenue by creative - See which acquisition sources drive best ad revenue
Fill rates - Track ad inventory utilization
eCPM trends - Monitor ad revenue performance over time

Best Practices

Track all impressions - Include every ad view, even low-value banners
Use accurate eCPM values - Update values based on your ad network reports
Consistent ad IDs - Use the same ad_id for the same placement
Include watch time - Accurate watch time helps analyze engagement
Track rewards accurately - Set reward: true only when reward was granted

Integration Tips

Mediation Platforms

If using ad mediation (ironSource, MAX, etc.), track the winning network in media_source:

{
  "media_source": "admob",  // The actual network that served the ad
  "source": "rewarded_video"
}

Batch Processing

While real-time tracking is preferred, if you must batch ad events:

Include accurate timestamps for each event
Don't delay more than a few hours
Maintain event order within batches

Ad view events complete your monetization tracking alongside purchase events. Together, they provide a complete picture of user lifetime value and help optimize both your acquisition and monetization strategies.