Skip to main content

Bidon Reporting API

Introduction​

The Bidon Reporting API provides a comprehensive event tracking system that logs various activities within the advertising ecosystem. These events are sent to Kafka topics and can be used for analytics, debugging, and performance monitoring.

The API captures detailed information about user interactions, auction processes, bidding activities, and outcomes, enabling you to gain insights into your advertising performance and make data-driven decisions.

Kafka Topics​

Bidon uses two main Kafka topics for event reporting:

  • ad_events: Contains all primary advertising-related events including user interactions, auction processes, and bidding activities.
  • notification_events: Contains notification-related events sent to demand partners, such as win/loss notifications.

Event Types and Kafka Topics​

Ad Events (Topic: ad_events)​

All primary event types are sent to the ad_events topic:

Event TypeDescription
auction_requestLogged when initiating an auction request process.
bid_requestLogged when sending a bid request to a network.
bidLogged upon receiving a bid response from the network corresponding to a bid request.
stats_requestLogged when a statistics collection request is initiated.
demand_requestLogged during CPM-based demand requests in the statistics collection.
client_bidLogged for real-time bidding (RTB) client bids during statistics collection.
configLogged during configuration handler processes.
winLogged when an advertisement successfully wins an auction.
lossLogged when an advertisement loses an auction.
clickLogged when a user clicks an advertisement.
showLogged when an advertisement is shown to a user.
rewardLogged when a user receives a reward after interacting with an advertisement.

Notification Events (Topic: notification_events)​

The notification_events topic is used for notification callbacks to demand partners. These are not directly tied to the event types above, but are generated as a result of certain events:

  • When a bid wins an auction (NURL notifications)
  • When a bid loses an auction (LURL notifications)
  • When an ad is shown (BURL notifications)
  • When a bid times out (timeout notifications)

Event Structures​

Common Fields​

All events include these common fields:

{
  "timestamp": 1648123456.789,
  "event_type": "string",
  "bundle": "com.example.app",
  "ad_type": "banner",
  "auction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

AdEvent Structure​

The AdEvent structure is used for all primary events sent to the ad_events topic:

{
  // Common fields
  "timestamp": 1648123456.789,
  "event_type": "bid_request",
  "bundle": "com.example.app",
  "ad_type": "banner",
  "auction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  
  // Event-specific fields
  "ad_format": "string",
  "auction_configuration_id": 123,
  "auction_configuration_uid": 456,
  "status": "SUCCESS",
  "impid": "imp-123",
  "demand_id": "admob",
  "bidding": true,
  "ad_unit_uid": 789,
  "ad_unit_label": "main_banner",
  "ecpm": 2.5,
  "price_floor": 1.0,
  "raw_request": "string",
  "raw_response": "string",
  "error": "string",
  "timing_map": {
    "auction": [1648123456000, 1648123456100],
    "fill": [1648123456100, 1648123456200]
  },
  "external_winner_demand_id": "string",
  "external_winner_ecpm": 3.0,
  
  // Device and user information
  "manufacturer": "Apple",
  "model": "iPhone13,4",
  "os": "ios",
  "os_version": "15.4",
  "connection_type": "wifi",
  "device_type": "phone",
  "session_id": "session-123",
  "session_uptime": 300,
  "framework": "unity",
  "framework_version": "3.0.0",
  "plugin_version": "1.0.0",
  "package_version": "2.1.0",
  "sdk_version": "1.2.3",
  "idfa": "00000000-0000-0000-0000-000000000000",
  "idg": "string",
  "idfv": "string",
  "tracking_authorization_status": "authorized",
  "coppa": false,
  "gdpr": false,
  "country_code": "US",
  "city": "San Francisco",
  "ip": "192.168.1.1",
  "country_id": 1,
  "segment_id": "segment-123",
  "segment_uid": 456,
  "ext": "string",
  "mediation_mode": "string",
  "session": {
    "id": "session-123",
    "launch_ts": 1648123000,
    "launch_monotonic_ts": 0,
    "start_ts": 1648123100,
    "start_monotonic_ts": 100,
    "ts": 1648123456,
    "monotonic_ts": 456,
    "memory_warnings_ts": [1648123200],
    "memory_warnings_monotonic_ts": [200],
    "ram_used": 1024,
    "ram_size": 4096,
    "storage_free": 10240,
    "storage_used": 2048,
    "battery": 0.75,
    "cpu_usage": 0.2
  }
}

NotificationEvent Structure​

The NotificationEvent structure is used for notification events sent to the notification_events topic:

{
  "timestamp": 1648123456.789,
  "event_type": "NURL",  // Can be NURL, LURL, BURL, TimeoutURL
  "bundle": "com.example.app",
  "ad_type": "banner",
  "auction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "demand_id": "admob",
  "imp_id": "imp-123",
  "loss_reason": 0,
  "ecpm": 2.5,
  "first_price": 2.5,
  "second_price": 2.0,
  "url": "https://example.com/win?price=2.5",
  "template_url": "https://example.com/win?price=${AUCTION_PRICE}",
  "error": ""
}

Reporting Metrics Definitions​

MetricDefinitionCalculation
Waterfall Request CountCount of all auction requestsCount events where event_type = 'auction_request'
Network Request CountCount of all network-related requestsCount events where event_type IN ('bid_request', 'demand_request')
Bid CountCount of all bids receivedCount events where event_type = 'bid' OR (event_type = 'demand_request' AND status IN ('WIN', 'LOSE'))
Fill CountCount of all successfully completed bid or CPM demand requestsCount events where event_type IN ('client_bid', 'demand_request') AND status IN ('WIN', 'LOSE')
Win CountCount of successful advertisement displays after statistics requestCount events where event_type = 'stats_request' AND status = 'SUCCESS'
External Loss CountCount of externally logged lossesCount events where event_type = 'loss'

Event Type Clarifications​

bid_request vs. bid​

  • bid_request: Represents sending a bid request to an external network.
  • bid: Represents receiving an actual bid response from the external network.

demand_request vs. client_bid​

  • demand_request: Used for CPM-based demand requests (non-bidding).
  • client_bid: Used for real-time bidding (RTB) client bids.