The full documentation can be found on [https://adhese.github.io/sdk\_typescript/](https://adhese.github.io/sdk_typescript/)
### Integration options The SDK supports multiple integration approaches, depending on your environment: #### NPM Install the SDK via NPM and integrate it into modern JavaScript or TypeScript projects. #### React Use the SDK within React applications to manage ad slots and lifecycle in a component-based way. #### Standalone JS script Include the SDK as a standalone script for simple integrations without a build step. Ideal for quick setups or environments where bundling is not available.The standalone script could be hosted and maintained by the Adhese team. Contact support if you wish to discuss this option in more detail.
### Key Features #### **Slot Management** Slots are the fundamental units for ad placement. The SDK supports three slot registration methods: - **Automatic DOM detection** - scan for elements with `adunit` class - **Pre-initialization slots** - declare slots before page load for early ad fetching - **Manual registration** - dynamically add slots via API Additional slot capabilities include: - Device-specific format selection (responsive ads via media queries) - Lazy loading with viewport detection - Dual render modes (iframe or inline) - Custom setup hooks for advanced control ##### **Configuration & Parameters** At initialization, you can set: - Account ID (required) - Targeting parameters (2-character prefixes matching your adserver configuration) - URL and referrer logging preferences - Lazy loading settings - Device type detection rules (customizable media queries) ##### **Event System** Subscribe to lifecycle events: - Slot lifecycle (add, remove, dispose) - Request/response events - Consent & parameter changes - Debug mode toggles - Impressions & viewable tracking ##### **Consent Management** Supports regulatory compliance via: - Binary consent (yes/no) - TCF API v2 integration ##### **React Integration** Dedicated React SDK provides: - `AdheseProvider` context wrapper - `useAdhese` hook for instance access - `useAdheseSlot` hook for slot creation - `AdheseSlot` component with JSX rendering support - Placeholder support during ad loading ### SDK Repository The SDK is actively maintained on GitHub and publicly available: [https://github.com/adhese/sdk\_typescript](https://github.com/adhese/sdk_typescript) # Prebid Prebid is a free and fully open source header bidding solution available to any publisher, dedicated to header bidding in the ad tech industry. Header bidding allows publishers to create a short delay in ad serving to obtain bids from multiple demand partners before deciding on which ad to display, enabling competitive pricing and higher revenue.More information on [Prebid](https://prebid.org/) | [Prebid.js Bidder](https://docs.prebid.org/dev-docs/bidders/adhese.html) | [Prebid Server Bidder](https://docs.prebid.org/dev-docs/pbs-bidders.html#adhese)
### How do Adhese and prebid work together When a publisher implements Adhese through Prebid, they're participating in a ****header bidding auction**** where multiple demand partners (including Adhese) compete to deliver ads. Here's how the process works: ##### Auction Initiation When a page loads, Prebid sends simultaneous bid requests to multiple bidders - including Adhese - rather than sequential requests. This concurrent approach is one of Prebid's key features for managing latency. All bidders (including Adhese) receive their request at roughly the same time. ##### Adhese's Role in the Auction Adhese acts as a ****bidder/SSP**** within Prebid's ecosystem. Through the Prebid adapter, Adhese receives ad requests and returns competitive bids and creatives. The adapter translates Prebid's standardized request format into Adhese's API requirements and vice versa. ##### Bid Submission & Timeout Management Publishers set a timeout value (typically 1-3 seconds) that determines how long Prebid waits for responses. Adhese must return its bid within this window. If Adhese doesn't respond in time, Prebid excludes it from that auction round. This timeout mechanism prevents slow bidders from degrading page performance. ##### Ad Selection After all bidders respond, Prebid passes the winning bid to the publisher's ad server. If Adhese wins, its creative is selected and delivered, leading to an impression in Adhese. ##### Targeting & Parameters Both Prebid and Adhese support custom targeting. Publishers can pass first-party data (like content categories, user segments, or location) through both systems, giving Adhese context for more accurate bidding. ##### Impression Tracking After an ad is selected and rendered, Adhese can track impressions and viewability through Prebid's event system, feeding performance data back to their platform. ### Bid Configuration Params| Pbjs param name | Scope | Description | Example | Type |
|---|---|---|---|---|
| `account` | required | Adhese account name | `'demo'` | `string` |
| `location` | required | Adhese location URL | `'_adhese_prebid_demo_'` | `string` |
| `format` | required | Adhese format code TAG | `'leaderboard'` | `string` |
| `data` | optional | (PBJS only) Custom target data | `{ 'ci': [9000, 9050] }` | `object` |
| `targets` | optional | (PBS only) Custom target data | `{ 'ci': [9000, 9050] }` | `object` |
To ensure that the assets are included in the response, the *Use in heads-up file* setting **must be enabled at format level**. This action can be performed by all admin users in the Adhese UI.
```html https://headsup-[customer].adhese.org/api/headsup/download-list/sl[positioncode] ```| Parameters | Value | Required |
| customer | The name of your Adhese account | Yes |
| position code | The code of the position you wish to request: \[location code\]\[optional position code\]-\[format code\]. This value is always prefixed by 'sl'. | Yes |
**1** The adserver rules still apply and will influence which campaigns are part of the response. Not all booked campaigns are necessarily part of the returned array.
**2** The **/e/stack/** endpoint must be enabled by Adhese support before it becomes available
### m/stack request ```html https://ads-[customer].adhese.com/m/stack/sl[positioncode]/[target prefix][target value]?max_ads=[amount] ```| **Parameters** | **Value** | **Required** |
| customer | The name of your Adhese account | Yes |
| position code | The code of the position you wish to request is \[location code\]-\[format code\]. This value is always prefixed by 'sl'. | Yes |
| custom target | Target data can be provided by adding a prefix followed by a value. Multiple values can be added by separating them with a `;` | No |
| max\_ads1 | The maximum number of ads you wish to request | Yes |
**1** A configuration on the adserver can be activated to ensure the max\_ads value never exceeds a specific limit. When the parameter is left empty, the configured limit will be used instead.
### e/stack request ```html https://ads-[customer].adhese.com/e/stack/sl[positioncode]/[target prefix][target value] ```| **Parameters** | **Value** | **Required** |
| customer | The name of your Adhese account | Yes |
| position code | The code of the position you wish to request is \[location code\]-\[format code\]. This value is always prefixed by 'sl'. | Yes |
| custom target | Target data can be provided by adding a prefix followed by a value. Multiple values can be added by separating them with a `;` | No |
| **Field** | **Description** |
| id | Creative URL |
| dur | Duration in milliseconds |
| proofOfPlay | Tracking URL after playback |
| error | Tracking URL for playback errors |
The sequence property is only used by the adserver and will be removed before the response is returned
# Request API: JSON endpoint The JSON endpoint is the foundation of every display integration with Adhese. It gives you direct access to the ad server and Gateway without an SDK or library: you build the request, and Adhese returns the ads as JSON. Any environment that can send an HTTPS request and parse JSON can use it. A backend service, a CMS, a mobile app, ... The Typescript Web SDK and the Prebid adapter use this same endpoint under the hood. If you use one of those, you do not need this page for implementation, but it remains the reference for what actually happens under the hood. The API is public and requires no authentication and cookies are not required for an integration to work. ## POST request ### Host Each Adhese account has its own endpoint. The default pattern is: ``` https://ads-[account].adhese.com/json/ ``` ### Request body The POST body is a JSON object with up to three top-level properties: ```json { "slots": [ { "slotname": "some_slot" }, ... ], "parameters": { "kw": [ "cheese", "wine" ], ... }, "user": { "ext": { "eids": [] } } } ```| Property | Required | Purpose |
|---|---|---|
| `slots` | **Yes** | The ad placements you are requesting |
| `parameters` | No | Request-level targeting data (page, user, context) |
| `user` | No | External user IDs for downstream buyers (open market) |
Each `slotname` may appear only once per request. Duplicates cause the request to be rejected with status `442`.
#### parameters An object of targeting attributes describing the page, user, or context. Keys are **fixed two-character codes** defined in your Adhese account; values are **always arrays of strings**. All parameters are optional — omit a key entirely, or send an empty array, when there is nothing to pass. ```json "parameters": { "kw": ["cheese", "wine"], "mi": ["ABCDEF123456"] } ``` In this example, `kw` carries search keywords and `mi` a member ID. Reserved parameter codes are listed on [Request target parameters](https://documentation.adhese.org/books/integration-setup/page/reserved-target-prefixes). #### Slot-level parameters A slot object can carry its own `parameters` property with the same structure. For each slot, request-level and slot-level parameters are **merged**. Use this for attributes that differ per placement, such as position on the page: ```json "slots": [ { "slotname": "some_slot", "parameters": { "ps": ["top"] } }, { "slotname": "another_slot", "parameters": { "ps": ["bottom"] } } ] ``` #### user Reserved for passing identifiers from external ID providers to buyers further down the chain, mainly in an open-market context: ```json "user": { "ext": { "eids": [] } } ``` If you think you need this, contact [Adhese Support](https://documentation.adhese.org/books/introduction/page/adhese-support) before implementing. #### Complete request example ```json { "slots": [ { "slotname": "homepage_banner" }, { "slotname": "homepage_rectangle_top" }, { "slotname": "homepage_rectangle_bottom" }, { "slotname": "homepage_halfpage", "parameters": { "ps": ["right"] } } ], "parameters": { "id": ["1234567890ABCD"], "ct": ["computers", "laptops"], "kw": ["cheese", "wine"] } } ``` Here `id` is a user ID, `ct` product categories, and `kw` search keywords. ## GET request The GET version of the ad request contains the same information as the POST version with one limitation: **slot level parameters are not supported.** Example request ```html https://ads-[account].adhese.com/json/sl_sdk_example_-leaderboard/ctsports;soccer?t=1784033344461 ```| Section | Description |
| https://ads-\[account\].adhese.com | The domain is either the default ads domain for your account or a configured first-party domain. More info on first-party domains can be found here. |
| /json/ | Fixed path segment selecting the JSON endpoint |
| /sl\[location code\]-\[format code\]/ | This section can be added more than once. Each placement starts with the prefix 'sl', followed by the full slot code. |
| /ctsports;soccer/ | This section can be added more than once. Each target section starts with its predefined prefix and is followed by either one value or a list of values separated by ';'. |
| ?t=\[timestamp\] | A timestamp to avoid caching issues |
| Code | Name | Description |
|---|---|---|
| `200` | OK | Body contains an array of ads. If no ads are available, the array is empty — an empty array is a **successful** response, not an error. |
| `442` | Duplicate slots | One or more `slotname` values appear more than once. Header `x-adhese-bad-request` lists the duplicates. |
| `454` | No slots | The request body contains no slots. Header `x-adhese-bad-request` contains `slots cannot be empty`. |
| `500` | Internal server error | If this was a debug request, check the debug log; otherwise contact Adhese Support. |
| Attribute | Description |
|---|---|
| `slotName` | The slot this ad belongs to. Use it as the key to match responses to the slots in your request when requesting multiple slots at once. |
| `tag` | The ad markup, returned as a string. For display ads this is typically an HTML fragment to insert into the slot's container. For video/audio it is a VAST-compliant XML document; for native ads it is a JSON object (delivered as a string that your application must parse). |
| `width` | Width of the ad container in pixels, required for correct display. |
| `height` | Height of the ad container in pixels, required for correct display. |
| `trackedImpressionCounter` | Unique URL to call when the ad is **added to the page**, even if not yet visible. Registers an IAB *paid impression*. Fire-and-forget: the call can be asynchronous and the response ignored. |
| `viewableImpressionCounter` | Unique URL to call when the ad has been **at least 50% in the viewport for at least one second**. Registers an IAB *viewable impression*. Fire-and-forget. |
| `clickTag` | Unique URL that counts a click and redirects the user to the ad's landing page. Use it as the href wrapping the creative. In applications without links, the URL can be called directly to register the click, ignoring the response. |
The easiest way to build a custom tracking URL is to take the **viewableImpressionCounter** URL and replacing the **Adhese-IABview** label with a custom one.
# Request API: AD endpoint The **AD endpoint** is used for integrations that can't parse a JSON response and require the response in a specific markup instead. It is typically used for [video and audio setups](https://documentation.adhese.org/books/adhese-products/page/vast-video-audio-advertising), where ads are requested by media players and follow the [VAST](https://iabtechlab.com/standards/vast/) protocol in XML. The API is public and requires no authentication and **cookies are not required** for an integration to work. ## Request method The AD endpoint supports **GET requests only**. As with the GET version of the JSON endpoint, **slot-level parameters are not supported**.Unlike the JSON endpoint, only one placement can be retrieved with each call
## URL structure A request URL is built from the sections below, in order. Sections marked *repeatable* can appear more than once.| Section | Repeatable | Description |
|---|---|---|
| `https://ads-[account].adhese.com` | No | The domain — either the default ads domain for your account or a configured first-party domain. See [First-party domains](#bkmrk-when-handling-errors) for more info. |
| `/ad/` | No | Fixed path segment that selects the AD endpoint. |
| `/sl[location code]-[format code]/` | No | A placement (slot). Starts with the prefix `sl`, followed by the full slot code. |
| `/ct[value];[value]/` | Yes | A target section. Starts with its predefined prefix (e.g. `ct`) and is followed by a single value or a list of values separated by `;`. Add one section per target group you want to pass. |
| `?t=[timestamp]` | No | A timestamp, used to avoid caching issues. |
| Part | Meaning |
|---|---|
| `https://ads-demo.adhese.com` | Ads domain for the `demo` account |
| `/ad/` | AD endpoint |
| `/sldemo.com_kitchen-billboard/` | Placement: prefix `sl`, location code `demo.com_kitchen`, format code `billboard` |
| `/dtdesktop/` | Target section: prefix `dt` with value `desktop` |
If no ads are available, the response contains **no ads**. This is still a successful `200` response, **not** an error.
### Response codes| Code | Name | Description |
|---|---|---|
| `200` | OK | The body contains the ads. If no ads are available, the response contains no ads — an empty response is a successful result, not an error. |
| `454` | No slots | The request contains no slots. The `x-adhese-bad-request` header contains `slots cannot be empty`. |
| `500` | Internal server error | For a debug request, check the debug log. Otherwise, contact Adhese Support. |
| Field name | Description |
| additionalCreatives | Lists the additional creatives |
| adDuration | Duration in seconds of the primary creative |
| adDuration2nd | Duration in seconds of the second creative file |
| adDuration3rd | Duration in seconds of the third creative file |
| adDuration4th | The optional duration of the fourth creative file |
| adDuration5th | The optional duration of the fifth creative file |
| adDuration6th | The optional duration of the sixth creative file |
| adFormat | the assigned format name determined by your Adhese account, e.g. wideskyscraper (the Code export field from the Admin > Formats screen) |
| adspaceEnd | The end date of the booking in UNIX timestamp |
| adspaceId | The Adhese booking ID |
| adspaceKey | An optional creative foreign key |
| adspaceStart | The start date of the booking in UNIX timestamp |
| adType | The name of the format as requested, e.g. SKY (the Code tag field from the Admin > Formats screen) |
| advertiserId | The ID of the advertiser |
| altText | Optional text to be shown as the value of the `` attribute of the container |
| auctionable | The auctionable (compete with RTB) setting of a booking, can be used for header bidding |
| body | The third-party code to be inserted in a container (if applicable) |
| clickTag | The URL of the click tag used for the counting of clicks and which should be followed by the actual target URL |
| comment | Optional free text comment |
| creativeName | The name of the creative as determined in the Adhese interface |
| deliveryGroupId | The ID of the booking or creative group for all-together or one-at-a-time bookings |
| deliveryMultiples | The type of delivery |
| dm | The ID of the delivery limitation |
| ext | The extension of the file type |
| extraField1 | Optional field used by the uploader |
| extraField2 | Second optional field used by the uploader |
| height | The height of the primary creative in pixels |
| height3rd | The height of the third creative file in pixels |
| height4th | The height of the fourth creative file in pixels |
| height5th | The height of the fifth creative file in pixels |
| height6th | The height of the sixth creative file in pixels |
| heightLarge | The height of the second creative file in pixels |
| id | The traffic ID of the link between an uploaded creative and a booking |
| impressionCounter | The URL to count a tracked impression |
| libId | The ID of the uploaded creative |
| orderId | The ID of the campaign |
| orderName | The name of the campaign |
| orderProperty | An optional comma-separated list of properties containing codes as defined by your Adhese account |
| origin | String identifying the source of the ad: JERLICIA or RUBICON |
| originData | An object containing more info related to the origin of the ad |
| poolPath | An optional path to a CDN where files for this creative can be retrieved |
| priority | The priority of the campaign |
| share | An optional number that indicates the weight of the creative |
| slotName | The value of the prefix `sl` as requested |
| swfSrc | The URL of the primary creative file |
| swfSrc2nd | The URL of the second creative file |
| swfSrc3rd | The URL of the third creative file |
| swfSrc4th | The URL of the fourth creative file |
| swfSrc5th | The URL of the fifth creative file |
| swfSrc6th | The URL of the sixth creative file |
| tag | The complete HTML code for inserting in the container |
| tagUrl | An optional URL of the tag's content |
| timeStamp | The timestamp of the latest change to this creative (can be used for caching) |
| tracker | The tracker URL that needs to be requested for counting an impressions |
| trackingUrl | The third-party tracking URL that needs to be requested when visualising the ad's creative |
| url | The click-through URL |
| viewableImpressionCounter | The URL to count a viewable impression |
| width | The width of the primary creative in pixels |
| width3rd | The width of the third creative file in pixels |
| width4th | The width of the fourth creative file in pixels |
| width5th | The width of the fifth creative file in pixels |
| width6th | The width of the sixth creative file in pixels |
| widthLarge | The width of the second creative file in pixels |