> For the complete documentation index, see [llms.txt](https://docs.admoai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.admoai.com/changelog/readme.md).

# Changelog

All notable changes to the Admoai Decision Engine API will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)

{% updates format="full" %}
{% update date="2025-11-01" %}

## 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)

#### 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

#### Fixed

* Improved timezone inference from IP geolocation
* Enhanced error messages for invalid geo-targeting
* Fixed edge case in custom targeting CEL expression evaluation

#### Performance

* Optimized video metadata extraction
* Reduced VAST XML generation overhead with pre-computed templates
* Improved tracking URL generation performance (batch processing)

#### Documentation

* Complete API reference for v2025-11-01
* Video ads implementation guide with code examples (JavaScript, Swift, Kotlin)
* VAST 4.2 compliance documentation
  {% endupdate %}

{% update date="2025-01-01" %}

## 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

#### Security

* **Tracking token encryption**: AES-256-GCM encryption for tracking payloads
* **Token expiration**: Configurable TTL (default: 3600 seconds)
  {% endupdate %}
  {% endupdates %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.admoai.com/changelog/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.