Prebid.js Bidder on Prebid + Prebid Server Bidder on Prebid
# Mobile SDKThe Mobile SDK should be considered legacy functionality. It's not used for new implementations.
Information on the mobile Adhese SDK's can be found on the following GitHub pages: Android: [https://github.com/adhese/ava](https://github.com/adhese/ava) iOS: [https://github.com/adhese/avi](https://github.com/adhese/avi) # Request API: JSON endpoint (old) For integrations where you don't want to use an SDK or other library, we provide the request endpoint so you can build the request URLs yourself. Both GET and POST requests are supported, but there is a slight difference between them. ## POST endpoint This endpoint provides access to the ad server and gateway functionality for server applications. This functionality allows implementers to send an HTTP POST request to their Adhese endpoint, returning an array of ads for the requested ad slots. The POST body can contain a number of parameters, the structure of which is documented below. The API is public and requires no authentication. Any client-side framework that can interpret a JSON response can request the same endpoint. ### Endpoint URL To obtain the endpoint URL for your account, contact [Adhese Support](https://documentation.adhese.org/books/introduction/page/adhese-support). Default look of the endpoint URL: ```html https://ads-{customer}.adhese.com/json/ ``` ### Request Type HTTP POST request over an HTTPS connection. In a production environment, no cookies are needed; all data is passed in the request body. For debugging purposes, add a ‘set-cookie’ header with the value ‘debugKey=\[any\_value\]’. This will make all activity from your requests available in [Gateway Debug Logging](https://documentation.adhese.org/books/adhese-gateway/page/adhese-gateway#bkmrk-gateway-debug-loggin).Do not use this debug cookie for production requests. If used on a large scale, it will add significant latency to your responses.
### POST Body The body of your POST request can contain JSON following a fixed structure. There are three main properties. ``` { "slots": [ { "slotname": "some_slot" }, ... ], "parameters": { "kw": [ "cheese", "wine" ], ... }, "user": { "ext": { "eids": [] } } } ``` #### slots An array of slot objects containing all the ad units required for a given page or state of the end-user application. At least one slot is required. Each slot contains at least a 'slotname', which is a unique identifier for a specific advertisement placement. This string is stored in the Adhese database and used for targeting campaigns. ``` "slots": [ { "slotname": "some_slot" }, { "slotname": "another_slot" } ] ``` #### parameters An object that contains a set of properties and their corresponding array of values. The purpose of this object is to define one or more attributes that tell you something about the page, user, context, etc. The parameter keys are fixed two-character codes defined in your Adhese account. The value is always an array of strings. All parameter properties are optional. You can leave them out if they are empty or irrelevant, or send an empty array as value. ``` "parameters": { "kw": [ "cheese", "wine" ], "mi": [ "ABCDEF123456" ] } ``` *In the example above, “kw“ is used for “search keyword“and “mi” for “member id.”* #### slot level parameters A slot can also contain a 'parameters' attribute that follows the same structure. Parameters can be defined at both the request and slot levels. The values of these parameters will be merged for each corresponding slot. ``` "slots": [ { "slotname": "some_slot", "parameters": { "ps": "top" } }, { "slotname": "another_slot", "parameters": { "ps": "bottom" } } ] ``` #### user The user property is reserved for situations where external ID providers are available, and their identifiers need to be transferred to buyers further down the line. This is mainly useful in an open market context. For more info, please contact our Support Team. ### Example of a complete request body ``` { "slots": [ { "slotname": "homepage_banner" }, { "slotname": "homepage_rectangle_top" }, { "slotname": "homepage_rectangle_bottom" }, { "slotname": "homepage_halfpage", "parameters": { ... } } ], "parameters": { // Example user ID "id": [ "1234567890ABCD" ], // Example product categories "ct": [ "computers", "laptops" ], // search keywords "kw": [ "cheese", "wine" ] } } ``` ### Response Codes #### 200 All is OK. If no advertisements are available, an empty array will be in the response body. #### 454 No slots were added to the request body, so no advertisements can be returned. An error message containing the message' slots cannot be empty' is added to the response as header ‘x-adhese-bad-request’. #### 442 A duplicate slotname has been used for one or more slots. An error message is added to the response as header ‘x-adhese-bad-request’ containing message ‘request contains duplicate slots: \[list of duplicate slots\]’ #### 500 Internal server error. Further information could be available in the debug log if it was a debug request or via Adhese Support. ### Response ObjectTo be moved to its own page
The response object contains a number of attributes. A full description can be found here: [https://github.com/adhese/sdk#response-object-structure](https://github.com/adhese/sdk#response-object-structure). The relevant attributes for a server-side integration are the following: ## slotName A string containing the name of the slot for which this response is intended. When requesting multiple slots simultaneously, this can be used as a key to link the responses to the slots you have added to the request body. ## tag The ad markup used to render the advertisement on the client is returned as a string and can be of any type interpretable by the client or requester. For typical web and display advertising, the markup is usually a fragment of HTML that can be inserted into a container on the page. For video or audio advertising, the markup is usually a VAST-compliant XML document. For native advertising, the markup typically comprises a JSON object containing all the elements required by a client application or browser script to render the ad correctly.The markup can contain JSON as a string, which the application consuming the responses must parse to get the actual JSON.
## width The ad container width in pixels is needed for the ad to display as intended. ## height The ad container height in pixels is needed for the ad to display as intended. ## trackedImpressionCounter The client application can call a unique URL when the ad is added to a page, even if it is not yet visible and the user has to scroll to see it. The call to the URL can be asynchronous, and the response can be ignored. The call to this URL registers a 'paid impression' for a specific ad, as defined by the IAB. ## viewableImpressionCounter The client application can call a unique URL when the ad is visible in the viewport for at least 50% and for at least one second. The call to the URL can be asynchronous, and the response can be ignored. A call to this URL will register a 'viewable impression', a metric defined by the IAB and used in digital advertising. ## clickTag The clickTag attribute contains a unique URL that can be used to create a link that is counted as a 'click' on the ad and redirects the user to the ad's landing page. When implemented in an application that does not use links or URLs, the clickTag URL can register a click while ignoring the response, just like the impression counters. ## Event trackingTo be moved to its own page
### Creating an Event Tracking URL You can create unique URLs based on the JSON output to register any event related to the ad once it is rendered on screen. A tracking event URL structure looks like this: ``` https://[ad_request_host]/track-[your_event_string]/[response.id]/sl[response.slotID]/II[response.impressionID] ``` ### Adding an Event Tracking URL to a template In an Advar or HTML5 template, event-tracking URLs can be created using [server-side request parameters](https://documentation.adhese.org/books/integrations-and-delivery/page/server-side-request-parameters). A tracking event would then look like this: ``` https://[adheseDomain:ad_host]/track-[your_event_string]/[adheseLogID]/sl[adheseReplace:sl]/II[adheseReplace:II] ``` ## Example of a full response object ``` [ { "dm": "dmDMGo2g0c0;ADV0", "adType": "714x224", "adFormat": "714x224", "timeStamp": "1642511791000", "share": "0", "priority": "0", "orderId": "2", "adspaceId": "2", "adspaceKey": "CI-ADH-12345678", "body": "", "trackingUrl": "", "tracker": "https://ads-demo.adhese.com/track/121//sl6/brChrome/brChrome97/brOSX/brdesktop/dtdesktop/ogcontrol/II19656e55-a3cd-4a39-8ed5-28f575a2e9b1/tlnone/ctaardappel-groente-fruit/ctkruiden-knoflook-pepers/umknown/kwkaas/om0/cuc/cxveel-gebruikt:snel/cxkeuken:italiaans/cxmomenten:wat_eten_we_vandaag/id1234567890ABCD/miAH0099887766/A2127.68.78.84/?t=1642610778623", "extraField1": "", "extraField2": "", "altText": "", "height": "224", "width": "714", "tag": "{ '_links': { 'self': { 'href': 'https://ads-demo.adhese.com/raylene//sl6/brChrome/brChrome97/brOSX/brdesktop/dtdesktop/ogcontrol/II19656e55-a3cd-4a39-8ed5-28f575a2e9b1/tlnone/ctaardappel-groente-fruit/ctkruiden-knoflook-pepers/umknown/kwkaas/om0/cuc/cxveel-gebruikt:snel/cxkeuken:italiaans/cxmomenten:wat_eten_we_vandaag/id1234567890ABCD/miAH0099887766/A2127.68.78.84/ad121-4/UR/acties/' } }, 'resourceType': 'Editorial', 'type': 'HalfWidthSmallResponsiveEditorial', 'position': { 'x': 'left', 'y': 'top' }, 'contentSize': 'half', 'color': 'drop', 'text': { 'title': 'Maak kans op een exclusieve Bud Dreams Jacket', 'body': 'Bekijk de actie' }, 'images': [ { 'title': '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 endpoint ```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 | Similar to the basic JSON GET endpoint, the stack request can contain target information by adding a prefix followed by a value. More values can be separated 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 endpoint ```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 | Similar to the basic JSON GET endpoint, the stack request can contain target information by adding a prefix followed by a value. More values can be separated with a ; | No |
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 for your slots 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. ## Endpoint URL Each Adhese account has its own endpoint. The default pattern is: ``` https://ads-[customer].adhese.com/json/ ``` ## Making a POST request Send a **POST request over HTTPS** with a JSON body (structure below). This is the recommended method for all new integrations.The endpoint also accepts **GET requests,** where the slots and parameters are encoded in the URL path instead of a body. We prefer the POST request but documentation can be retrieved
### 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/request-target-parameters). ### 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. ## Making a GET request The GET version of the ad request contains the same information as the POST version, **slot level parameters are however not supported.** Example request ```html https://ads-[account].adhese.com/json/sl_sdk_example_-leaderboard/ctsports;soccer?t=244.18664863333106 ```| Section | Meaning | Details |
| https://ads-\[account\].adhese.com | Ads domain | 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/ | Endpoint identifier | |
| /sl\[location code\]-\[format code\]/ | Slots | This section can be added more than once. Each placement starts with the prefix 'sl', followed by the full slot code. |
| /ctsports;soccer/ | Target(s) | 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\] | Timestamp | A timestamp to avoid caching issues |
| Code | Meaning | Details |
|---|---|---|
| `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. |