Publisher Integration Guide
Overview
Our ad serving API implements the IAB OpenRTB 2.6 specification, the industry standard protocol for programmatic advertising. By adhering to OpenRTB standards, we ensure seamless integration with existing publisher systems and maintain compatibility with the broader programmatic ecosystem. This standardization significantly reduces development overhead and allows publishers to leverage existing OpenRTB-compliant infrastructure.
Getting Started
Creating Ad Placements
Begin by navigating to https://app.nativeads.ai/inventory. This management console allows publishers to create and configure ad placements and access detailed reporting. To create a new placement:
- Navigate to the Inventory section
- Click "New Placement"
- Configure the placement settings:
- Description: Detailed context about the placement location and purpose
- Dimensions: Supported image dimensions for the native ad
- Placement parameters (e.g. min CPM)
- Submit the configuration to receive a unique placement ID
The placement ID is a crucial identifier that must be included in the bid request payload's `tagid` field. This enables our system to properly route and optimize ad delivery for your specific placement.
Integration Details
Ad Serving API Specification
Endpoint Information
- Endpoint: https://api.nativeads.ai/v1/ad-serving/get-ad
- Method: POST
- Content-Type: application/json
Request Format
The following payload is based on:
The provided links provide a thorough description of all fields and attributes. We support targeting options (demographic, geographic, contextual, device) through the bid request fields.
If users who have consented to personalized advertising, publishers can include contextual signals in content.keywords (e.g. genre, theme of current content), user demographics in user.yob and user.gender, publisher-specific user interests and attributes in user.keywords, precise location in device.geo.lat and device.geo.lon.
For users who have opted out of personalized advertising, publishers should only pass contextual signals, general geo information and basic device information.
Here’s an example complete payload with inline explanations of each field.
{
"id": "32f94228-52d3-4bce-be88-5dd1d799ae4f", // Unique ID for this bid request
"wlang": ["en", "es"], // Whitelist of accepted creative languages - crucial for ensuring delivered ads match audience language capabilities
"bcat": [ // Blocked advertiser categories using IAB taxonomy
"IAB7-3", // Sensitive categories publisher wants to exclude
"IAB23", // Gambling
"IAB25-2" // Politics
],
"cattax": 2, // Specifying we're using IAB Content Taxonomy 2.0 for all category-related fields
"badv": [ // Block list of advertiser domains
"competitor1.com",
"unwantedadvertiser.com",
"excludedcompany.com"
],
"imp": [{
"id": "1",
"tagid": "nativeads-placement-456789", // Unique identifier for this placement in our system - REQUIRED
"bidfloor": 5.00,
"bidfloorcur": "USD",
"secure": 1, // Flag to indicate if the impression requires secure HTTPS URL creative assets
"native": {
"ver": "1.2", // Version of the Native payload
"context": 1, // Context type ID (e.g. video gallery)
"contextsubtype": 12, // Primarily video content
"plcmttype": 1, // In the feed of content
"plcmtcnt": 3, // Number of identical placements being offered in the same feed/stream
"assets": [{
"id": 1,
"required": 1,
"img": {
"type": 3, // Main image
"wmin": 400,
"hmin": 600,
"mimes": ["image/jpeg", "image/png"]
}
}]
}
}],
"app": {
"id": "ctv-app-123",
"name": "StreamingApp",
"bundle": "com.publisher.streamingapp",
"cat": ["IAB1-7"],
"ver": "2.5.1",
"publisher": {
"id": "pub-123",
"name": "Publisher Name",
"domain": "publisher.com"
},
"content": {
"livestream": 0, // Whether the content is live
"language": "en",
"context": 1, // Type of content (e.g. video)
"keywords": [ // Content-specific keywords for contextual targeting
"romance",
"christmas",
"premium-content",
]
}
},
"device": {
"devicetype": 3, // CTV
"geo": {
"country": "USA",
"type": 2,
"region": "CA",
"city": "San Francisco", // City-level targeting for local advertising
"zip": "94103",
"lat": 37.7749, // Precise latitude for geo-targeting
"lon": -122.4194 // Precise longitude for geo-targeting
},
"os": "Android TV",
"language": "en"
},
"user": {
"yob": 1985, // Year of birth for age targeting
"gender": "M", // Gender for demographic targeting
"keywords": [ // Publisher-specific keywords about the user for personalization (interests, etc.)
"sports-fan",
"tech-enthusiast",
"food-lover",
],
"geo": {
"country": "USA",
"region": "CA",
"city": "San Francisco",
"zip": "94103",
"lat": 37.7749,
"lon": -122.4194
}
},
"regs": {
"coppa": 0,
"gdpr": 0,
"us_privacy": "1YNN"
}
}
Response Format
Our system returns OpenRTB-compliant bid responses containing:
- Creative assets
- Tracking URLs for various events
{
"id": "32f94228-52d3-4bce-be88-5dd1d799ae4f", // Echo of the bid request ID to enable response matching
"bidid": "abc123-winning-bid", // Unique ID for this winning bid for tracking/auditing
"cur": "USD", // Currency of the bid price, matching what was allowed in request
"seatbid": [{ // Array containing single seatbid with winning bid
"bid": [{
"id": "1", // Unique ID for this bid
"impid": "1", // Matches impression ID from request
"price": 12.50, // Winning bid price in CPM
// Win notice URL - called by publisher when bid wins auction
"nurl": "https://api.nativeads.ai/v1/win/abc123-winning-bid",
// Billing notice URL - called by publisher when impression is billable
"burl": "https://api.nativeads.ai/v1/bill/abc123-winning-bid",
// The native ad markup object, containing all creative and tracking details
"adm": {
"ver": "1.2", // Native Ads Specification version
"link": {
"url": "https://adv.com/2je02", // Landing URL of the unit
"fallback": "https://adv.com/29h3", // Fallback URL
"clicktrackers": [ // Array of third-party click tracking URLs
"https://tracker.com/track" // 3P click tracker
]
},
// Assets array containing creative specifications
"assets": [{
"id": 1,
"required": 1,
"img": {
"type": 3, // Main image
"url": "https://cdn.nativeads.ai/123456.jpg", // Our optimized creative URL
"w": 400, // Width matching publisher's requirement
"h": 600 // Height matching publisher's requirement
}
}],
// Event tracking configurations
"eventtrackers": [
{
"event": 1, // Impression event
"method": 1, // Image pixel tracking method
"url": "https://api.nativeads.ai/v1/impression/d92h83"
},
{
"event": 2, // Viewable impression (MRC 50%)
"method": 1, // Image pixel tracking method
"url": "https://api.nativeads.ai/v1/viewable/d92h83"
},
{
"event": 1, // Impression event - 3P's tracker
"method": 1, // Image pixel tracking method
"url": "https://3p.com/impression/290jd"
}
]
},
// Additional metadata about the ad
"crid": "creative-123456", // NativeAds creative ID
"adomain": ["brand.com"], // Advertiser's domain for publisher validation
"cat": ["IAB1-1"], // Creative category for publisher validation
// Indicating this is a native creative
"mtype": 4 // 4 = Native as per OpenRTB 2.6 spec
}]
}],
// Notify publisher if this is a test bid (0 = real bid)
"test": 0
}
Integration Requirements
Creative Rendering
The response provides all necessary creative assets and specifications:
- Image URL for the native ad creative
- Dimensions matching placement requirements
- Click-through URL
Event Tracking
Publishers must implement the following tracking mechanisms:
- Fire all tracking URLs when the creative becomes viewable
- Fire all click-tracking and viewability URLs on user interaction
Support and Resources
For assistance and support, please email: support@nativeads.ai