Documentation

Marketing

Advertisements

Advertisement Management

Pro Feature — The advertisement system is available in the Pro and Agency tiers.

Unfold CMS includes a built-in advertisement management system with template-defined zones, multiple display strategies, country-based targeting, scheduling, and impression tracking.

Overview

The ad system uses a zone-based architecture:

Templates define zones — Ad placement areas declared in template.json
Admins create advertisements — Upload ad creatives with targeting options
Advertisements are assigned to zones — With optional weight for rotation
Templates render zones — Using the @ad_zone Blade directive

Template Zones

Templates declare available ad zones in their template.json file:

{
    "ad_zones": [
        {
            "key": "header_banner",
            "name": "Header Banner",
            "size": "728x90",
            "type": "banner"
        },
        {
            "key": "sidebar_rectangle",
            "name": "Sidebar Rectangle",
            "size": "300x250",
            "type": "sidebar"
        },
        {
            "key": "footer_banner",
            "name": "Footer Banner",
            "size": "728x90",
            "type": "footer"
        }
    ]
}

When a template is activated, the CMS automatically syncs these zones to the database. Template-managed zones are marked as such and cannot be deleted through the admin panel.

Zone Types

Type	Description
`banner`	Full-width banner areas
`sidebar`	Sidebar ad placements
`popup`	Overlay/modal ads
`footer`	Footer area ads

Common Ad Sizes

Name	Dimensions	Use Case
Leaderboard	728x90	Header, between content
Medium Rectangle	300x250	Sidebar, in-content
Large Rectangle	336x280	Sidebar, in-content
Skyscraper	160x600	Sidebar
Wide Skyscraper	300x600	Sidebar
Mobile Banner	320x50	Mobile header/footer

Creating Advertisements

Navigate to Marketing > Advertisements in the admin panel.

Advertisement Fields

Field	Description
Name	Internal name for identification
Type	Image, HTML, or script-based ad
Content	Ad creative (image upload, HTML code, or script)
Link URL	Click-through destination URL
Zones	Which zones to display in
Weight	Priority weight for rotation (higher = shown more often)
Status	Active or inactive
Start Date	When to start showing (optional)
End Date	When to stop showing (optional)
Countries	Country-based targeting (optional)

Display Strategies

When multiple ads are assigned to a zone, the system selects which ad to display:

Strategy	Description
Random	Randomly selects from active ads
Weighted	Favors ads with higher weight values
Sequential	Cycles through ads in order

Country-Based Targeting

The ad system supports a 3-tier country classification for geographic targeting:

Tier	Description	Example
Tier 1	Premium markets	US, UK, Canada, Australia
Tier 2	Mid-range markets	Brazil, India, Mexico
Tier 3	Emerging markets	All other countries

You can assign ads to specific countries or tiers, or leave blank to show globally.

Date Scheduling

Ads can be scheduled with start and end dates:

Start date only — Ad becomes active on this date, runs indefinitely
End date only — Ad runs until this date
Both dates — Ad runs within the date range
Neither — Ad runs immediately with no end date

The system checks date eligibility when selecting ads for display.

Rendering Ads in Templates

Using the @ad_zone Directive

{{-- Render an ad zone --}}
@ad_zone('header_banner')

{{-- Check if a zone has active ads before rendering --}}
@hasAdZone('sidebar_rectangle')
    <div class="ad-container">
        @ad_zone('sidebar_rectangle')
    </div>
@endhasAdZone

The @ad_zone directive:

Looks up the zone by key
Finds eligible advertisements (active, within date range, matching country)
Selects an ad based on the display strategy
Renders the ad HTML
Tracks an impression

Impression Tracking

Every time an ad is displayed, the system records an impression. View impression statistics in the admin panel under the advertisement detail page.

Admin Panel

Zone Management

Navigate to Marketing > Ad Zones to:

View all zones (template-managed and custom)
Toggle zone active/inactive status
View which ads are assigned to each zone
Create custom zones (not template-managed)

Template-managed zones are synced automatically when the template loads. Their configuration (name, size, type) comes from the template and cannot be edited in the admin panel.