# DOOH: Digital Out Of Home

### Architecture Overview

Adhese supports DOOH through dedicated endpoints, which allow:

- Media asset distribution
- Playlist generation for screens/players
- Proof-of-play tracking
- Player-level targeting and reporting

A typical DOOH setup contains the following components:

- Screens
- Digital Signage CMS / Player
- Adhese Ad Server
- Server-side data mapping
- Reporting and Proof-of-Play Tracking

<div contenteditable="false" id="bkmrk--1">---

</div>### Implementation prerequisites

Before starting, ensure that the following are available:

#### Adhese Requirements

- Active Adhese account
- DOOH feature enabled by Adhese support
- Configured Inventory &amp; templates
- Configured player ID target

#### Player / CMS Requirements

- Ability to perform HTTP GET requests
- JSON parsing support
- Local asset caching support
- Video/image playback support
- Ability to fire tracking URLs

---

### Adhese DOOH endpoints

#### Assets Download Endpoint (Heads-up)

<p class="callout warning">Ensure that the *Use in headsup* setting is activated for all your DOOH formats. You can perform this action in the admin UI.  
[![image.png](https://documentation.adhese.org/uploads/images/gallery/2026-05/scaled-1680-/49qnR6RzS13wU6CJ-image.png)](https://documentation.adhese.org/uploads/images/gallery/2026-05/49qnR6RzS13wU6CJ-image.png)  
</p>

This is an optional endpoint used to retrieve and cache all active creative assets for a DOOH position. The response structure is fixed and cannot be customised.

Request example

```
https://headsup-[customer].adhese.org/api/headsup/download-list/sl[positioncode]
```

<details id="bkmrk-response-example-%7B-%22"><summary>Response example</summary>

```
{
  "media": [
    {
      "ad": {
        "id": "https://pool-demo.adhese.com/pool/lib/ad1.mp4",
        "mime": "video/mp4",
        "curl": "https://pool-demo.adhese.com/pool/lib/ad1.mp4",
        "checksum": "abc123"
      }
    }
  ]
}
```

</details><p class="callout info">Detailed information on the headsup endpoint can be found [here](https://documentation.adhese.org/books/integration-setup/page/request-api-headsup-endpoint)</p>

<div contenteditable="false" id="bkmrk-">---

</div>#### Playlist Endpoint

Adhese provides two stack endpoints for retrieving a playlist.

1. The /**m/stack/** endpoint, which retrieves a list with a limit on the number of ads in the response
2. The **/e/stack/** endpoint, which doesn't have a predefined limit

Request example

```ini
/m/stack/: https://ads-[customer].adhese.com/m/stack/sl[positioncode]/pi[player ID]?max_ads=[amount]
/e/stack/: https://ads-[customer].adhese.com/e/stack/sl[positioncode]/pi[player ID]
```

<details id="bkmrk-example-response-%7B-%C2%A0"><summary>Example response</summary>

```json
{
    "ads":[
        {
            "id":"https://pool-demo.adhese.com/pool/lib/562_2nd_1.mp4",
            "dur":28.07,
            "proofOfPlay":"https://ads-demo.adhese.com/track/3474/sl357/tlnone/piplayer_id/A2?1746011926824",
            "error":"https://ads-demo.adhese.com/track/3474-PLAY_ERROR_[ERRORCODE]/sl357/tlnone/piplayer_id/A2/?1746011926824"
        },
        {
            "id":"https://pool-demo.adhese.com/pool/lib/561_2nd_1.mp4",
            "dur":11.45,
            "proofOfPlay":"https://ads-demo.adhese.com/track/3444/sl357/tlnone/piplayer_id/A2?1746011926824",
            "error":"https://ads-demo.adhese.com/track/3444-PLAY_ERROR_[ERRORCODE]/sl357/tlnone/piplayer_id/A2/?1746011926824"
        },
        {
            "id":"https://pool-demo.adhese.com/pool/lib/560_2nd_1.mp4",
            "dur":18.85,
            "proofOfPlay":"https://ads-demo.adhese.com/track/3455/sl357/tlnone/piplayer_id/A2?1746011926824",
            "error":"https://ads-demo.adhese.com/track/3455-PLAY_ERROR_[ERRORCODE]/sl357/tlnone/piplayer_id/A2/?1746011926824"
        }
    ]
}
```

</details>**Common Fields**

<table id="bkmrk-field-description-id" style="width: 40.2381%; height: 178.781px;"><tbody><tr style="height: 29.7969px;"><td style="width: 29.4702%; height: 29.7969px;">**Field**</td><td style="width: 70.2062%; height: 29.7969px;">**Description**</td></tr><tr style="height: 29.7969px;"><td style="width: 29.4702%; height: 29.7969px;">id</td><td style="width: 70.2062%; height: 29.7969px;">Creative URL</td></tr><tr style="height: 29.7969px;"><td style="width: 29.4702%; height: 29.7969px;">dur</td><td style="width: 70.2062%; height: 29.7969px;">Duration in milliseconds</td></tr><tr style="height: 29.7969px;"><td style="width: 29.4702%; height: 29.7969px;">proofOfPlay</td><td style="width: 70.2062%; height: 29.7969px;">Tracking URL after playback</td></tr><tr style="height: 29.7969px;"><td style="width: 29.4702%; height: 29.7969px;">error</td><td style="width: 70.2062%; height: 29.7969px;">Tracking URL for playback errors</td></tr></tbody></table>

<p class="callout info">The response structure consists of an array of *ads*, each containing several objects. The object structure is linked to the Advar template that was used to create the campaigns. This template is maintained either in Adhese itself or in the configured GitHub repository for your account. </p>

<p class="callout info">Detailed information on the stack endpoint can be found [here](https://documentation.adhese.org/books/integration-setup/page/request-api-stack-endpoint)</p>

##### Player ID target

You can provide extra target information through the request by adding extra target sections to the URL: **/\[prefix\]\[value\]/.** One example of such a target is the player ID, which has the prefix 'pi', as shown in the above example. This ID can be used for:

- Player/screen level targeting and reporting
- Location-based targeting and reporting

##### Providing extra target / reporting data

Player / store location and other custom metadata can be provided server-side by uploading a **player =&gt; metadata mapping** in Adhese.  
  
Each metadata property will be linked to its own target prefix. This data will be mapped automatically to incoming requests based on the player ID and will become available for targeting and reporting purposes.

<p class="callout warning">Adhese requires the player ID prefix - or any other target prefixes - to be configured by support.</p>

<div contenteditable="false" id="bkmrk--4">---

</div>### Operational Recommendations

##### Asset Caching

Always cache assets locally to:

- Reduce bandwidth
- Avoid playback interruptions
- Improve offline resilience

#### Offline Mode

Players should continue playback using:

- Last valid playlist
- Cached creatives

### Troubleshooting

<table id="bkmrk-issue-possible-cause"><tbody><tr><td>**Issue**</td><td>**Possible Cause**</td></tr><tr><td>Empty media array</td><td>No active campaigns or targeting-related issues</td></tr><tr><td>Endpoint redirects</td><td>DOOH endpoints not enabled</td></tr><tr><td>Headsup endpoint empty</td><td>No active campaigns or *Use in heads-up* format config disabled</td></tr><tr><td>Playback errors</td><td>Unsupported codec or corrupt file</td></tr><tr><td>No reporting</td><td>Proof-of-play URL not triggered</td></tr></tbody></table>