# 10 — Video advertising system

## Origin

Searchmercials's video-ad pipeline is a **retrofit** onto the legacy Hyperseek engine. Git history (commits referencing "videoads") spans 2023–2024 and touches: search integration, detail pages, category filters, bid-location selection.

Representative commits (newest → oldest):
```
fbc2968  update for videoads - search with category
d06e32b  update for videoads - detail page
6cb196e  update for videoads - search
79c7de5  update for videoads - search
(earlier)  update for videoads
```

## Components

### Player
- **Assets directory**: `httpdocs/search/Player/`
- **Client script**: `httpdocs/includes/playvideo.js`
- **Legacy artifact**: `httpsdocs/validation/flv/video.flv` — sample FLV file, pre-HTML5 era

The exact player library used was not identified during the analysis pass; read `Player/` to determine whether it's:
- video.js (with videojs.ima plugin + videojs-contrib-ads)
- JW Player
- A custom in-house HTML5 `<video>` wrapper
- Legacy OSMF / Flash fallback (FLV presence hints at this lineage)

The YouPortal platform console errors (see user conversation history: `ima3.js`, `videojs.ima.min.js`, `videojs.ads.min.js`, VMAP `<AdTagURI>` missing) strongly suggest **video.js + Google IMA**, and that stack likely applies here too because the two platforms share client patterns.

### Ad decisioning
- **Bidding DB tables**: `iweb_hs_featured`, `iweb_sponsor_boxes`
- **Bid storage**: per-category / per-geography rows in `iweb_accounts` linked tables
- **Serving entry**: `httpdocs/search/inlinehor-media.php` (horizontal inline media slot)

### Click + impression tracking
- **Click log**: `httpdocs/r.php` → `iweb_jh_click_log`
- **Aggregation**: `iweb_jh_click_summary`, `iweb_jh_affiliate_summary`
- **Bot filtering**: `classes_new/minibots.class.php` intercepts traffic from known crawlers before billing

## Ad call flow (reconstructed)

```
User loads search results page
  └─ httpdocs/search/results.php
       ├─ selects candidate ads from iweb_hs_featured / iweb_sponsor_boxes
       ├─ bot-filter via minibots.class.php
       ├─ renders player via httpdocs/search/Player/
       └─ player JS (httpdocs/includes/playvideo.js) requests ad
            └─ [player stack] fetches VMAP / VAST
                  │
                  ▼
            plays pre-roll → main content

User clicks ad
  └─ r.php?id=<listing_id>&url=<dest>
        ├─ INSERT into iweb_jh_click_log
        ├─ debit iweb_accounts.balance
        └─ 302 → dest
```

## Known issues and open questions

### 1. Player stack identification
Needed before any further work:

```bash
ls -la /var/www/html/Searchmercials/httpdocs/search/Player/
head -50 /var/www/html/Searchmercials/httpdocs/includes/playvideo.js
```

Expected to reveal either a video.js bundle (look for `videojs.min.js`, `videojs-ima.min.js`, `ima3.js`) or a JW Player signature (`jwplayer.js`, `jwplayer.core.js`).

### 2. Ad-source configuration
The user has seen console errors on the sibling YouPortal site:
```
Error preloading and updating adTagUrl: Failed to find <AdTagURI> element in VMAP
```
This means the configured VMAP URL is returning a document without any `<AdTagURI>` child, which can happen when:
- The ad-server returns an empty VMAP (no inventory available)
- The URL points at a GAM (Google Ad Manager) endpoint that hasn't been fully configured
- Ad-blockers are intercepting the response

If Searchmercials uses the same VMAP / ad-tag URL config, this error is present here too. Locate the VMAP/VAST URL configuration (probably in a JS bootstrap or a PHP-rendered `<script>` tag) and verify it returns a real `<AdTagURI>`.

### 3. `videojs-contrib-ads has not seen a loadstart event 5 seconds after being initialized`
Indicates the IMA plugin is attached **after** the videojs player has already resolved its initial source, instead of in the same microtask. Caused by late script inclusion or deferred plugin init. Fix: ensure the IMA plugin script is on the page **before** the `videojs(...)` constructor runs.

### 4. Flash / FLV residue
`httpsdocs/validation/flv/video.flv` plus FLV-era assumptions in older code paths should be audited. Adobe Flash reached EOL 2020. Any browser-side Flash dependency is already dead; remove server-side FLV generation unless there's still an RTMP/on-prem consumer.

## Recommendations

1. **Audit `Player/`** and document the actual stack in this file (supersede the "unknown" notes above)
2. **Verify VMAP endpoint** returns non-empty inventory; if using Google Ad Manager, confirm the line items are active
3. **Move IMA plugin init** into the same synchronous block as `videojs(el, opts)` to kill the `loadstart` warning
4. **Remove FLV** — convert any legacy FLV samples to MP4/HLS; delete Flash-specific serving code
5. **Add impression deduplication** — if not already present, track impressions in a separate `iweb_jh_impression_log` so impressions and clicks don't compete for the same write path
6. **Consolidate tracking** — the duplicate `r.php` in `httpdocs/` and `httpsdocs/` plus `search/r.php` creates three write paths for the same log; funnel through one canonical handler

## Cross-reference with YouPortal

YouPortal doesn't currently run a video-ads pipeline, but if the two platforms ever share a click log or ad-inventory API, document the boundary in [05-integrations.md](05-integrations.md).