# Zones & Embed



## What is a Zone?

A **Zone** is a defined ad placement on your website – for example a leaderboard banner in the
page header or a rectangle in the sidebar. Each zone has a unique embed code that you include on your site.

When a visitor loads the page, the AdServer decides which campaign (and therefore which ad) to serve in the
zone – based on priority, budget, pacing, and fraud checks.

> A zone can be assigned to multiple campaigns. Exactly one campaign is selected per request.

## Zone fields

| Field | Required | Description |
| --- | --- | --- |
| `name` | Yes | Internal name of the ad slot (e.g. "Header Banner" or "Sidebar Rectangle"). |
| `description` | No | Optional description for internal purposes. |
| `width / height` | Yes | Dimensions of the ad slot in pixels. The rendered ad container has exactly this size. |
| `max_impressions_per_session` | No | Session cap: maximum impressions per visitor session (0 = unlimited). Stored via cookie (requires consent). |
| `fallback_html` | No | HTML5 shown when the zone is active but no ad is running. Useful for house ads or placeholder content. |
| `is_active` | No | Inactive zones return an empty response (or the fallback HTML if configured). |

## Zone Assignment (campaign linking)

A **Zone Assignment** connects a campaign to a zone. A zone can be assigned to multiple campaigns.
The **priority** (1–10) determines the order of campaign selection.

| Field | Description |
| --- | --- |
| `zone` | The target zone of this assignment. |
| `campaign` | The assigned campaign. |
| `priority` | Integer 1–10. Higher priority = preferred when budget allows. |

> If multiple campaigns share the same priority, the system picks randomly among them (weighted).

## Embed code integration

After creating a zone you'll find the embed code in the Setup Wizard or on the zone detail page. It looks like this:

`<script src="https://your-server.com/go/sn/42.js" async></script>`

Insert the script tag at the position in your page where the ad should appear:

`<!-- Ad area header -->
<div style="text-align: center;">
<script src="https://your-server.com/go/sn/42.js" async></script>
</div>`

> Recommended
>
> - Place directly in the body area
> - Keep the `async` attribute
> - Only one script tag per zone position

> Avoid
>
> - Script in `<head>` without `defer`
> - Including the same script more than once
> - Embedding the script inside an `iframe`

## Ad selection on page load

When the browser executes the script tag, it sends a request to the AdServer. The server goes through the following steps:

1. **Identify zone** – The zone ID from the URL is resolved and checked to see if the zone is active.
2. **Fraud check** – IP address, user agent, and rate limit are checked. Suspicious requests return an empty response.
3. **Session cap check** – Has the visitor reached the maximum impression count for this zone? If yes: empty response (requires consent cookie).
4. **Select campaign** – All active campaigns for the zone are filtered by priority and budget availability, then selected by weighted random.
5. **Select ad** – One ad from the active ads of the chosen campaign is picked by weighted random selection.
6. **Log impression & render** – The impression is stored in the `HourlyStats` model and the ad is returned as JavaScript.