search
rssRSS feed

clock-rotate-leftChangelog

New updates and improvements

All notable changes to the Admoai Decision Engine API will be documented in this file. The format is based on Keep a Changelogarrow-up-right

hashtag
v2025-11-01

Destination Targeting Support

  • Added a Ad new segmentation filter, allowing to filter ads based on the destination of the user.

Three delivery modes for video ads:

  • json: Full creative content including video URL and tracking beacons (custom players)

  • vast_tag: Signed URL to fetch VAST 4.2 XML from renderer service (standard players)

  • vast_xml: Inline base64-encoded VAST 4.2 XML document (offline/air-gapped)

Six video milestone tracking events:

  • start: Video playback begins

  • first_quartile: 25% of duration reached

  • midpoint: 50% of duration reached

  • third_quartile: 75% of duration reached

  • complete: Video playback completes

  • skip: User skips the video

Video metadata in response:

  • duration: Video duration in seconds

  • aspect_ratio: Video aspect ratio (e.g., "16:9")

  • is_skippable: Whether the video can be skipped

  • skip_offset_seconds: When skip button becomes available

VAST 4.2 compliance:

  • IAB-compliant VAST XML generation

  • Support for Linear video ads

  • VideoClicks with ClickTracking and ClickThrough

  • Companion ads support

  • Admoai-specific extensions (metadata, advertiser info)

Skip button configuration:

  • HH:MM:SS format (e.g., "00:00:05")

  • Percentage format (e.g., "25%")

VAST tag URL signing:

  • HMAC-SHA256 signature for security

  • TTL-based expiration

  • Tamper-proof payload encoding

New Request Parameters

  • placements[].format: Ad format filter ("native", "video")

New Response Fields (Video Ads Only)

  • delivery: Video delivery mode ("json", "vast_tag", "vast_xml")

  • vast: VAST delivery object

  • vast.tagUrl: VAST tag URL (vast_tag mode)

  • vast.xmlBase64: Base64-encoded VAST XML (vast_xml mode)

  • tracking.videoEvents: Array of video milestone tracking URLs

  • metadata.format: Ad format ("video")

  • metadata.duration: Video duration (seconds)

  • metadata.aspect_ratio: Video aspect ratio

  • metadata.is_skippable: Skip availability

  • metadata.skip_offset_seconds: Skip offset (seconds)

Open Measurement (OMID) Support

  • Third-party Verification: Added support for Open Measurement SDK (OMID) to enable viewability and measurement verification via external providers (e.g., IAS, DoubleVerify, Moat).

  • Standardized Signal Delivery: Support for OMID verification resources across both Native and Video formats.

New Response Fields

  • verificationScriptResources: Array of verification objects including vendorKey, scriptUrl, and verificationParameters. (Included in JSON for Native ads and Video JSON mode; for other video modes, resources are embedded within the VAST XML).

Tracking Behavior (Video Ads)

  • VAST Tag/XML delivery modes: Tracking beacons (impressions, clicks, videoEvents) are empty arrays in JSON response; tracking lives in VAST XML instead

  • Player click event: Excluded from JSON tracking.clicks for VAST modes (included in VAST XML <VideoClicks>)

Response Structure

  • Video ads always include delivery field

  • Video ads always include vast field (empty object for JSON delivery)

  • Native ads omit delivery and vast fields (backward compatible)

hashtag
Security

  • VAST tag URL signing: HMAC-SHA256 signature prevents tampering

  • Timestamp validation: VAST tag URLs expire after configurable TTL

  • Tracking token encryption: Prevents tracking URL manipulation

hashtag
Fixed

  • Improved timezone inference from IP geolocation

  • Enhanced error messages for invalid geo-targeting

  • Fixed edge case in custom targeting CEL expression evaluation

hashtag
Performance

  • Optimized video metadata extraction

  • Reduced VAST XML generation overhead with pre-computed templates

  • Improved tracking URL generation performance (batch processing)

hashtag
Documentation

  • Complete API reference for v2025-11-01

  • Video ads implementation guide with code examples (JavaScript, Swift, Kotlin)

  • VAST 4.2 compliance documentation

hashtag
v2025-01-01

Core Features

  • Native ad support: Text, image, and rich media creatives

  • Template system: Flexible ad template configuration

  • Content localization: Language-aware content delivery via Accept-Language header

  • Click and impression tracking: Encrypted tracking tokens with expiration

Targeting Capabilities

  • Geo-targeting: Country, city, region targeting using GeoNames database

  • Location targeting: GPS coordinate-based targeting with radius matching

  • Custom targeting: CEL expression-based custom attribute targeting

  • Dayparting: Time-of-day and day-of-week ad scheduling

Ad Selection

  • Priority-based selection: Multi-tier ad prioritization by weight

  • Weighted random selection: Probabilistic ad rotation based on weights

  • Frequency capping: Per-user impression limits

  • GDPR compliance: EU user detection and consent-based frequency capping

API Endpoints

  • POST /v1/decision: Request ad decision for placements

  • GET /v1/tracking: Track ad events (impression, click, custom)

Request Parameters

  • placements[]: Array of placement requests

  • key: Placement identifier (required)

  • count: Number of ads to return (1-10, default: 1)

  • advertiserId: Filter by advertiser public ID

  • templateId: Filter by template public ID

  • targeting: Targeting parameters

  • geo: GeoName IDs array

  • location: Latitude/longitude pairs with radius

  • custom: Custom attribute key-value pairs

  • user: User context

  • id: User identifier (for frequency capping)

  • ip: IP address (for geo-inference)

  • timezone: IANA timezone

  • consent.gdpr: GDPR consent status

  • device: Device context (OS, model, manufacturer, etc.)

  • app: Application context (name, version, bundle ID)

Response Structure

  • success: Boolean success indicator

  • data: Array of placement decisions

  • placement: Placement key

  • creatives: Array of creative objects

    • contents: Creative content fields

    • advertiser: Advertiser information

    • template: Template configuration

    • tracking: Tracking URLs

    • metadata: Ad metadata

  • errors: Array of error objects

  • warnings: Array of warning objects

Error Handling

  • Validation errors: 422 Unprocessable Entity with detailed error codes

  • Structured error responses: Error code, message, and contextual details

  • Warning system: Non-fatal warnings for degraded experience (e.g., missing language)

Version System

  • Header-based versioning: X-Decision-Version header for API version selection

  • Default version: Falls back to 2025-01-01 if no version header provided

hashtag
Security

  • Tracking token encryption: AES-256-GCM encryption for tracking payloads

  • Token expiration: Configurable TTL (default: 3600 seconds)

Last updated