Search Ad Link - Technical Overview

⚠️ Important: This use case demonstrates sponsored brand suggestions in autocomplete scenarios. As users type, branded suggestions appear in the dropdown. When clicked, the suggestion opens the brand's landing page in a new tab - no complex animations or chat interface.

📺 Live Demo: See this implementation in action at https://demo-aura.affinity.net/search-ad-link

Executive Summary

This document outlines how search publishers can integrate sponsored brand suggestions into autocomplete experiences using standard IAB Native Ads 1.2 format. As users type in the search box, branded suggestions appear in the dropdown alongside organic suggestions. When users click a branded suggestion, they are directly navigated to the brand's landing page in a new tab - providing a simple, effective monetization solution for search platforms.

Key Benefits:

Simple Integration: Straightforward click-through behavior
Direct Navigation: Opens brand landing page in new tab
Industry Standard: Uses OpenRTB 2.6 + IAB Native Ads 1.2 specification
Easy Integration: Works with existing ad tech ecosystem (DSPs, SSPs, ad servers)
Click-Based Revenue: Revenue from clicks to brand sites
Privacy-First: Contextual targeting without PII requirements
Low Complexity: No chat interface or complex animations
Familiar Format: Standard autocomplete suggestion format users expect

Compare With:

Homepage Tile Link - Similar click-through behavior but for browser homepage tiles instead of search autocomplete

Use Case Example

User Action: User types "shoes" in search box

Autocomplete Dropdown Appears:

┌─────────────────────────────────────────────────────────┐
│ Search: shoes                                     [🔍] │
├─────────────────────────────────────────────────────────┤
│ Suggestions:                                            │
│                                                         │
│ ┌─────────────────────────────────────────────────┐   │
│ │ [🏪] Nike                                  [Ad] │   │
│ │      nike.com                                   │   │
│ └─────────────────────────────────────────────────┘   │
│                                                         │
│ ┌─────────────────────────────────────────────────┐   │
│ │ [🏪] Adidas                                [Ad] │   │
│ │      adidas.com                                 │   │
│ └─────────────────────────────────────────────────┘   │
│                                                         │
│ ┌─────────────────────────────────────────────────┐   │
│ │ [🏪] Zappos                                [Ad] │   │
│ │      zappos.com                                 │   │
│ └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

User Clicks Nike Suggestion:

Click tracker fires (max 50ms)
New tab opens with Nike landing page
User lands on Nike site to browse/shop

Result: Simple, direct navigation to brand's website

Why IAB Native Ads for Autocomplete Suggestions?

1. Industry Standard

Built on OpenRTB 2.6 and IAB Native Ads 1.2 specification
No custom integrations needed for each brand
Works with existing ad tech ecosystem (DSPs, SSPs, ad servers)
Broad support across the advertising industry

2. Structured Brand Presentation

Brands provide structured data via native assets
Standard asset types ensure consistency and quality
Brand name, logo, and display URL clearly defined

3. Privacy-First Design

No PII required in bid requests
Contextual targeting based on search keywords
GDPR/CCPA compliant by design

4. Click-Based Analytics

Track clicks when users select brand suggestion
Standard tracking mechanisms across all publishers

5. Quality Control

IAB Native specification defines asset requirements
Validation ensures quality before serving
Publisher controls which brands to display

Architecture Overview

Key Points:

Search platform provides the interface - The search platform renders the autocomplete dropdown
Affinity AI Bid API provides branded suggestions - standard OpenRTB auction
Direct navigation - Click opens brand URL in new tab
Click tracking - Standard click tracking via OpenRTB

IAB Native Ads Asset Mapping

Search Ad Native Assets

Following IAB Native Ads 1.2 specification, search ads use these standard asset types:

Required Assets:

IAB Asset Type	ID	Data Type	Purpose
Title	1	-	Ad headline
Data (Desc)	2	type: 2	Ad description

Optional Assets:

IAB Asset Type	ID	Data Type	Purpose
Data (Sponsor)	3	type: 1	Advertiser name/domain
Data (CTA)	4	type: 12	Call-to-action text

Native Request Structure

The native request follows IAB Native Ads 1.2 specification:

{
  "ver": "1.2",
  "assets": [
    {
      "id": 1,
      "required": 1,
      "title": {
        "len": 100
      }
    },
    {
      "id": 2,
      "required": 1,
      "data": {
        "type": 2,
        "len": 300
      }
    },
    {
      "id": 3,
      "required": 0,
      "data": {
        "type": 1,
        "len": 50
      }
    },
    {
      "id": 4,
      "required": 0,
      "data": {
        "type": 12,
        "len": 30
      }
    }
  ]
}

Key Points:

Asset ID 1: Ad title/headline (required, max 100 chars)
Asset ID 2: Ad description (required, max 300 chars, data type 2)
Asset ID 3: Advertiser name/domain (optional, max 50 chars, data type 1)
Asset ID 4: CTA text (optional, max 30 chars, data type 12)

OpenRTB Integration

Note: We use standard OpenRTB 2.6 with IAB Native Ads 1.2 for search ads.

Bid Request Structure

Your search platform sends standard OpenRTB 2.6 bid requests with native ad placement:

{
  "id": "search-ad-req-001",
  "imp": [
    {
      "id": "imp-1",
      "native": {
        "request": "{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":100}},{\"id\":2,\"required\":1,\"data\":{\"type\":2,\"len\":300}},{\"id\":3,\"required\":0,\"data\":{\"type\":1,\"len\":50}},{\"id\":4,\"required\":0,\"data\":{\"type\":12,\"len\":30}}]}"
      },
      "bidfloor": 0.1,
      "bidfloorcur": "USD"
    }
  ],
  "site": {
    "id": "search-platform.com",
    "domain": "demo-aura.affinity.net",
    "page": "https://demo-aura.affinity.net/search-ad-link",
    "keywords": "best wireless headphones"
  },
  "device": {
    "language": "en",
    "geo": {
      "country": "US"
    }
  }
}

Key Request Components:

Request ID: Unique identifier for the bid request
Impressions: Array of impression objects (one per ad slot)
Native Request: JSON-encoded IAB Native Ads 1.2 specification
Site: Publisher site information with search keywords
Device: User device and geo information for targeting

Bid Response Structure

Advertisers respond with standard IAB Native Ads 1.2 format:

{
  "id": "search-ad-req-001",
  "seatbid": [
    {
      "seat": "advertiser-network",
      "bid": [
        {
          "id": "ad-001",
          "impid": "imp-1",
          "price": 1.25,
          "adm": "{\"native\":{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"text\":\"Premium Wireless Headphones - Free Shipping\"}},{\"id\":2,\"data\":{\"type\":2,\"value\":\"Shop top-rated wireless headphones with fast delivery. Great deals on Sony, Bose & more.\"}},{\"id\":3,\"data\":{\"type\":1,\"value\":\"amazon.com\"}},{\"id\":4,\"data\":{\"type\":12,\"value\":\"Shop Now\"}}],\"link\":{\"url\":\"https://amazon.com/headphones?ref=aura\"},\"imptrackers\":[\"https://track.example.com/imp?id=123\"]}}",
          "crid": "ad-creative-001",
          "adomain": ["amazon.com"]
        }
      ]
    }
  ],
  "cur": "USD"
}

Native Response Breakdown:

The adm field contains a JSON-encoded IAB Native Ads 1.2 response:

Link: Click destination URL - REQUIRED for navigation
Assets:
- Asset 1 (Title): Ad headline - "Premium Wireless Headphones - Free Shipping"
- Asset 2 (Data/Description): Ad description (data type 2)
- Asset 3 (Data/Sponsor): Advertiser name - "amazon.com" (data type 1)
- Asset 4 (Data/CTA): Call-to-action - "Shop Now" (data type 12)
Impression Trackers: Array of impression tracking URLs

Important: The link.url field is required for this use case as it specifies where to navigate when the ad is clicked. The native response can be in the adm field directly or wrapped in a native object for legacy compatibility.

Ad Display Integration

Parsing Native Ad Response

Your search platform extracts ad information from the IAB Native Ads 1.2 assets:

Parse the JSON-encoded adm field from the bid response
Handle both wrapped ({native: {...}}) and unwrapped formats
Extract native assets by ID:
- Asset ID 1 (Title) → Ad headline
- Asset ID 2 (Data type 2) → Ad description
- Asset ID 3 (Data type 1) → Advertiser name/domain (optional)
- Asset ID 4 (Data type 12) → CTA text (optional)
- Link URL → Click destination URL (REQUIRED)
- Impression trackers → Array of tracking URLs
Validate all URLs are HTTPS
Validate link.url is present (required for navigation)
Sanitize text content to prevent XSS
Render ad in search results

Rendering Search Ad

Display the search ad above or alongside organic results:

Display URL: From Asset ID 3 or extracted from link URL
AD Badge: Clear "Ad" label for transparency
Title: From Asset ID 1 (clickable, bold)
Description: From Asset ID 2 (2-3 line clamp)
Clickable Area: Entire ad is clickable

Visual Design:

┌─────────────────────────────────────────────────┐
│ [Ad] amazon.com                                 │
│ Premium Wireless Headphones - Free Shipping     │
│ Shop top-rated wireless headphones with fast    │
│ delivery. Great deals on Sony, Bose & more.     │
└─────────────────────────────────────────────────┘

Loading State:

Skeleton placeholder while loading ads
Smooth fade-in when ads load
Graceful handling if no ads returned

Click Behavior

When user clicks the sponsored ad:

Fire Click Tracker: Send beacon to click tracking URL (max 200ms wait)
Open Landing Page: Open link.url in new tab with security flags
Security: Use window.open(url, '_blank', 'noopener,noreferrer')

Implementation:

function handleAdClick(ad: SearchAd) {
  // Fire click tracker
  if (navigator.sendBeacon && ad.clickUrl) {
    const clickUrl = replaceMacros(ad.clickUrl, {
      click_id: generateClickId(),
      imp_id: ad.impId,
    })
    navigator.sendBeacon(clickUrl)
  }

  // Open advertiser URL in new tab
  setTimeout(() => {
    window.open(ad.linkUrl, '_blank', 'noopener,noreferrer')
  }, 50) // Small delay to ensure beacon fires
}

Tracking Implementation

Fire click tracking using navigator.sendBeacon() with image pixel fallback:

Click Trackers: When user clicks on brand suggestion (max 50ms wait before navigation)

Implementation Details:

Click tracking fires immediately when user selects suggestion
Uses navigator.sendBeacon() for reliable tracking
All tracking URLs validated as HTTPS
Graceful degradation if tracking fails
Small delay (50ms) ensures beacon fires before navigation

Macro Replacement:

Replace macros in tracking URLs:

{click_id} → Generate unique click ID
{imp_id} → Use impression ID from bid

User Experience Flow

1. Autocomplete Suggestions Display

User types in search box (minimum 3 characters)
Branded suggestions appear in dropdown after 300ms debounce
Each suggestion shows: brand icon, brand name, display URL, "Ad" badge
Suggestions update as user continues typing
Entire suggestion is clickable

User clicks branded suggestion
Click tracker fires (max 50ms wait)
New tab opens with brand's landing page
User lands on brand site
Dropdown closes

3. Tracking Events

Click: Fired when user clicks suggestion (before opening URL)

4. Error Handling

Graceful degradation if no suggestions returned
Loading state shown while fetching
No suggestions shown for queries <3 characters
Real API only - no mock data fallback

Benefits for Search Publishers

Revenue Generation

Performance-Based: Revenue tied to clicks to brand sites
High Intent: User typing indicates active search intent
Premium Placements: Autocomplete suggestions command premium rates
Click-Only Tracking: Simple, industry-standard tracking

User Experience

Simple Navigation: Direct path to brand content
Fast: Instant suggestions with 300ms debounce
Familiar: Standard autocomplete format users expect
Transparent: Clear "Ad" badge on branded suggestions

Technical Advantages

Industry Standard: OpenRTB 2.6 + IAB Native Ads 1.2
Easy Integration: Works with existing ad tech infrastructure
Low Complexity: Simple click-through behavior
Scalable: Handle millions of autocomplete requests per day
Broad Support: Compatible with all major ad platforms

Analytics & Optimization

Click Metrics: Track clicks via IAB mechanisms
A/B Testing: Test different suggestion layouts and ordering
Performance Data: Optimize based on click-through rates
Revenue Reporting: Standard programmatic advertising metrics

Implementation Considerations

Quality Control

Asset Validation: Ensure all required native assets are present (title, description, linkUrl)
HTTPS Validation: All URLs (landing pages, tracking) must be HTTPS
XSS Prevention: Sanitize all text content before rendering
Flexible Parsing: Handle both wrapped and unwrapped native response formats
Performance: Target <50ms per ad parsing
URL Validation: Ensure link.url is present and valid

Privacy & Compliance

No PII Required: Contextual targeting only
GDPR Compliant: User consent management
CCPA Compliant: Privacy string support
IAB Guidelines: Follow IAB Native Ads disclosure requirements
Clear Labeling: Mark ads with "Ad" label for transparency

Performance

Low Latency: 1000ms timeout for bid request
Debouncing: 300ms debounce delay to reduce API calls
Async Tracking: Fire click tracking asynchronously with sendBeacon
Graceful Degradation: Handle no-bid responses gracefully
Performance Targets:
- Bid request construction: <10ms
- Bid API response: <1000ms
- Suggestion parsing: <50ms per suggestion
- Click tracking: <50ms
- URL open: Immediate after tracking
- Dropdown display: <100ms after typing stops

Security

New Tab Security: Use noopener,noreferrer flags when opening URLs
URL Validation: Validate all URLs before opening
XSS Prevention: Sanitize all text content
HTTPS Only: Reject non-HTTPS URLs

Demo Implementation

A complete working demo is available at https://demo-aura.affinity.net/search-ad-link:

Features:

Real Affinity AI Bid API integration (no mock data)
IAB Native Ads 1.2 format parsing
Autocomplete dropdown with branded suggestions
300ms debounce for API calls
Click tracking with sendBeacon
Keyboard navigation (arrow keys, enter, escape)
Responsive design (desktop and mobile)
Security flags for new tab opening

Demo Behavior:

Type minimum 3 characters to trigger suggestions
Branded suggestions appear in dropdown
Click suggestion to navigate to brand site
Click tracking fires before navigation

Real Implementation:

Affinity AI Bid API integration
OpenRTB 2.6 protocol
IAB Native Ads 1.2 parsing
Click tracking with sendBeacon
Branded suggestions from real advertisers

AI Search SEM Text Ads - More advanced integration with organic results
AI Search Product Ads - Visual product cards with images
AI Search LLM Weaving - Weave sponsored text into LLM responses
Homepage Tile Link - Simple click-through for browser homepage tiles

OpenRTB Components

Request Format - OpenRTB 2.6 bid request format
Response Format - OpenRTB 2.6 bid response format
Native Object - Native ad request structure

External Standards

OpenRTB 2.6 Specification - IAB Tech Lab
IAB Native Ads 1.2 - IAB Tech Lab

Version History

v1.0 (2025-12-24): Initial use case guide
- IAB Native Ads 1.2 specification for search ads
- Direct click-through navigation
- Demo implementation details

Conclusion

IAB Native Ads enable search publishers to monetize autocomplete/SiteSuggest experiences through simple, effective click-through advertising. This approach ensures:

Industry Standard: OpenRTB 2.6 + IAB Native Ads 1.2
Easy Integration: Works with all major ad platforms
Simple UX: Direct navigation to brand landing pages
Low Complexity: No complex animations or chat interfaces
Strong Revenue: Click-based monetization
Privacy-First: Contextual targeting without PII
Responsive Design: Adapts to all screen sizes
Familiar Pattern: Standard autocomplete behavior users expect

By using standard IAB Native Ads 1.2, you can generate revenue from autocomplete suggestions while providing users with direct access to brand content in a familiar, non-disruptive way.

Executive Summary​

Use Case Example​

Why IAB Native Ads for Autocomplete Suggestions?​

1. Industry Standard​

2. Structured Brand Presentation​

3. Privacy-First Design​

4. Click-Based Analytics​

5. Quality Control​

Architecture Overview​

IAB Native Ads Asset Mapping​

Search Ad Native Assets​

Native Request Structure​

OpenRTB Integration​

Bid Request Structure​

Bid Response Structure​

Ad Display Integration​

Parsing Native Ad Response​

Rendering Search Ad​

Click Behavior​

Tracking Implementation​

User Experience Flow​

1. Autocomplete Suggestions Display​

2. Suggestion Click → Direct Navigation​

3. Tracking Events​

4. Error Handling​

Benefits for Search Publishers​

Revenue Generation​

User Experience​

Technical Advantages​

Analytics & Optimization​

Implementation Considerations​

Quality Control​

Privacy & Compliance​

Performance​

Security​

Demo Implementation​

Related Use Cases​

Related Documentation​

OpenRTB Components​

External Standards​

Version History​

Conclusion​