It is not possible to use Adhese macros such as `[adheseReplace:xx]` or `
Ensure that the filenames only contain alphanumeric characters, dots, and underscores. Other characters may cause issues when Adhese processes the file!
Steps for creating and uploading a new template: 1. Locally, create a new folder in which to store all files 2. Choose a name for the template: **\[name\].zip** 3. Create a **descr.json** file and store it in the main directory of your folder. The content has to be constructed in the same way you would create a regular advar template. (See step 6 of [creating a new advar](https://documentation.adhese.org/books/templating/page/advar-templates#bkmrk-create-a-new-advar-t)) 4. Create an **index.html** file - which will be the starting point for the HTML5 ad - and store it in the main directory of your folder 5. Make sure to **incorporate** **clickthrough logic**. Adhese relies on it to track clicks correctly. You can do this by adding the following line of code to your **index.html** file. Adhese will add its click tracking URL to this variable, after which you can use it in the rest of your clickthrough logic. ```javascript ``` 6. Optionally you can store CSS, JS and images in separate files & folders within the main directory.All links in the HTML5 creative, such as the link to an image within the ad, need to use a relative path, for example: /graphics/ad-image.png or <img src="/graphics/ad-image.png">. This enables the ad to be self-contained and, therefore, to run independently or to render without a network connection. External libraries and web fonts can be an exception to this guideline.
7. Zip the content of the folder (not the folder itself) and **change the name of the zip** to the name of the template 8. Upload the template in the Adhese UI under *Admin > Formats and templates > HTML5 templates,* 9. Test the template by creating a creative and checking the preview of the banner ### Troubleshooting HTML5 Templates If an HTML5 template can't be uploaded for some reason, you'll get an error message: [](https://documentation.adhese.org/uploads/images/gallery/2025-02/rDOAAqkvnajYN1V1-schermafdruk-van-2025-02-21-12-58-35.png) In the case above, hidden files might block Adhese from properly unzipping the archive: [](https://documentation.adhese.org/uploads/images/gallery/2025-02/xilX0LY8p1YT27pA-schermafdruk-van-2025-02-21-13-52-42.png) [](https://documentation.adhese.org/uploads/images/gallery/2025-02/ktFjHchQTyjTAd21-schermafdruk-van-2025-02-21-13-53-00.png) When creating an archive on Mac OS, a hidden \_\_MACOSX folder might be created. These files must be removed for the upload to succeed (you may need to unzip, delete and re-zip the files). [](https://documentation.adhese.org/uploads/images/gallery/2025-02/fw10iRzfm81Wf1kg-schermafdruk-van-2025-02-21-13-09-02.png) In the case above, the zip file has been renamed. If the zip file does not match the advar name in the descr.json file, rename the zip file to match the advar name in the descr.json file, and the archive can be uploaded. # Template Repository The Template Repository lets you control Template files and Advar templates using a Git version control system. Once this option is enabled, you can - store your templates in your own version control system - maintain a detailed history of your changes - effortlessly switch between different versions of your templates - edit templates in your preferred IDE - check out a specific branch in your Adhese account.Changes in the checked-out version on your Adhese account will be applied to **all relevant creatives** and will be pushed online with the next publish.
[](https://documentation.adhese.org/uploads/images/gallery/2024-10/MiX3h1eIMQJ3BvqO-schermafdruk-van-2024-10-28-09-44-54.png) ### Directory Structure The main directory of your repository can be used to store all 'regular' templates. In most implementations these are no longer used and can therefor be ignored. More relevant are the advar templates and the 'HTML5' advar templates. Both types will be stored in separate folders: "**advar\_templates**" and "**html5\_templates**". [](https://documentation.adhese.org/uploads/images/gallery/2025-03/zE4DKuQHZYym1FzG-image.png) #### Advar templatesMore info about advar templates can be found [here](https://documentation.adhese.org/books/templating/page/advar-templates)
Each advar template consists of 2 files: 1. The file that contains the actual response template. This file can be made out of HTML, JSON or XML code. It will depend on the type of integration the template will be used for. The extension can be .txt or something that matches the content of the template. 2. A description file that contains the form used to create an advar creative. This file will contain specific JSON markup. More info on this can be found [here](https://documentation.adhese.org/books/templating/page/advar-templates). The file needs to have **the same name as the first file, followed by the extension .descr** . [](https://documentation.adhese.org/uploads/images/gallery/2025-03/eiZK974dcTj9mhfe-image.png) #### HTML5 templatesMore info about HTML5 templates can be found [here](https://documentation.adhese.org/books/templating/page/html5-templates)
HTML5 templates are stored as compressed folders using the .zip extension. Each HTML5 template has their own HTML, CSS and JS structure within that folder and need to have a description file named descr.json in the main directory. [](https://documentation.adhese.org/uploads/images/gallery/2025-03/Bcl6xQfATQfWUudg-image.png) ### Usage The Template Repository screen shows two panels. On the left, you can see a summary of the Git commits currently used. It contains the Git hash, the branch, and the date and message when it was committed. On the right, you see a text field and button to change the commit for checkout: 1. Enter branch name or Git hash to use (e.g. origin/master) 2. Press *Checkout* button The specified Git commit will be checked out. All the template changes will be applied in the next publish phase. ### Activation To activate this option, please get in touch with our Support department. You will also need to provide the following information: - the URL of your Git repository, this needs to be accessible from the outside (e.g.| Parameter | Description |
|---|---|
| [adheseExpand: <ID>] | |
| [adheseReplace: <ID>] | Is replaced by the values sent with the corresponding ID from the request. |
| [adheseLogID] | A unique number used for reporting. |
| [adheseRequestData] | All parameters used in the ad request. |
| [adheseRequestDataFlat] | Contains the full request as it is sent to the ad server but replaces all semicolon-separated values by a /prefixValue/ clause. |
| [adheseSetExpandPrefix: <prefix>] | |
| [adheseTimestampNowMs] | Unix timestamp at the moment of sending the response, the number of milliseconds since 1970-01-01 0:00:00. |
| [adheseAdditionalRequestParameters:<target>] | This parameter can contain additional parameters that are added to the targets of the request, for example, dmADV <ADHESE_ADVERTISER_ID>;OR <ADHESE_ORDER_ID>. |
| [adheseEnv:<KEY>] | This parameter is replaced by the environment variable <KEY> of the request, for example [adheseEnv:HTTP_HOST]. See [http://en.wikipedia.org/wiki/Common_Gateway_Interface](http://en.wikipedia.org/wiki/Common_Gateway_Interface) for an overview of all environment variables. |
| [adheseReplace:SL] | The value of the string identification for the requested position. |
| [adheseReplace:A2] | The value of the identification cookie. |
| [adheseDomain:ad_host], [adheseDomain:click_host], [adheseDomain:pool_host], [adheseDomain:track_host] | Contains the incoming host for the request. Usefull for 1st domain implementations with multiple domains. |
When working with **advar** **templates** & advar creatives, you need to **use the 2ND (and higher)** macro's when adding macro's related to **uploaded creative files.** Examples are <ADHESE\_EXT\_2ND>, <ADHESE\_SWF\_SRC\_2ND>
| **Parameter** | **URIENCODED** | **Description** |
|---|---|---|
| <ADHESE\_ADSPACE\_COMMENT> | <ADHESE\_ADSPACE\_COMMENT\_URIENCODED> | The comment of the booking. |
| <ADHESE\_ADSPACE\_END> | The end date of a booking. | |
| <ADHESE\_ADSPACE\_ID> | The unique ID of the booking. | |
| <ADHESE\_ADSPACE\_KEY> | <ADHESE\_ADSPACE\_KEY\_URIENCODED> | The external reference or key of a booking. |
| <ADHESE\_ADSPACE\_START> | The start date of a booking. | |
| <ADHESE\_ADVERTISER\_ID> | The ID of the selected Advertiser company | |
| <ADHESE\_ALT\_TEXT> | <ADHESE\_ALT\_TEXT\_URIENCODED> | The content of the alt text field. |
| <ADHESE\_BODY> | <ADHESE\_BODY\_URIENCODED> | The body of the creative (if available). |
| <ADHESE\_CLICK\_TAG> | <ADHESE\_CLICK\_TAG\_URIENCODED> | The click tag of a creative (including URL). |
| <ADHESE\_CONFIGURABLE\_TRACKER\_URL> | <ADHESE\_CONFIGURABLE\_TRACKER\_URL\_URIENCODED> | If configured, the tracking URL that has been configured in the configuration. |
| <ADHESE\_CREATIVE\_ID> | The unique ID of the link between the booking and the creative. | |
| <ADHESE\_CREATIVE\_NAME> | <ADHESE\_CREATIVE\_NAME\_URIENCODED> | The name of the creative. |
| <ADHESE\_DELIVERY\_MULTIPLES> | <ADHESE\_DELIVERY\_MULTIPLES\_URIENCODED> | The delivery multiples value of the booking. |
| <ADHESE\_DELIVERY\_MULTIPLES\_GROUP\_ID> | <ADHESE\_DELIVERY\_MULTIPLES\_GROUP\_ID\_URIENCODED> | The group ID for the delivery multiples, if needed. |
| <ADHESE\_DURATION>, <ADHESE\_DURATION\_2ND>, <ADHESE\_DURATION\_3RD>, <ADHESE\_DURATION\_4TH>, <ADHESE\_DURATION\_5TH>, <ADHESE\_DURATION\_6TH> | The duration of the uploaded video files in seconds. | |
| <ADHESE\_DURATON\_MS>, <ADHESE\_DURATON\_MS\_2ND>, <ADHESE\_DURATON\_MS\_3RD>, <ADHESE\_DURATON\_MS\_4TH>, <ADHESE\_DURATON\_MS\_5TH>, <ADHESE\_DURATON\_MS\_6TH> | The duration of the uploaded video files in milliseconds. | |
| <ADHESE\_EXT>, <ADHESE\_EXT\_2ND>, <ADHESE\_EXT\_3RD>, <ADHESE\_EXT\_4TH>, <ADHESE\_EXT\_5TH>, <ADHESE\_EXT\_6TH> | <ADHESE\_EXT\_URIENCODED>, <ADHESE\_EXT\_2ND\_URIENCODED>, <ADHESE\_EXT\_3RD\_URIENCODED>, <ADHESE\_EXT\_4TH\_URIENCODED>, <ADHESE\_EXT\_5TH\_URIENCODED>, <ADHESE\_EXT\_6TH\_URIENCODED> | The file extension of each uploaded file. |
| <ADHESE\_EXTRA\_FIELD\_1> | <ADHESE\_EXTRA\_FIELD\_1\_URIENCODED> | The content of the extra field 1. |
| <ADHESE\_EXTRA\_FIELD\_2> | <ADHESE\_EXTRA\_FIELD\_2\_URIENCODED> | The content of the extra field 2. |
| <ADHESE\_FORMAT> | <ADHESE\_FORMAT\_URIENCODED> | The format of the booking. |
| <ADHESE\_HEIGHT\_LARGE\_3RD>, <ADHESE\_WIDTH\_LARGE\_3RD> | The dimensions of the third file that is uploaded. | |
| <ADHESE\_HEIGHT\_LARGE\_4TH>, <ADHESE\_WIDTH\_LARGE\_4TH> | The dimensions of the fourth file that is uploaded. | |
| <ADHESE\_HEIGHT\_LARGE\_5TH>, <ADHESE\_WIDTH\_LARGE\_5TH> | The dimensions of the fifth file that is uploaded. | |
| <ADHESE\_HEIGHT\_LARGE\_6TH>, <ADHESE\_WIDTH\_LARGE\_6TH> | The dimensions of the sixth file that is uploaded. | |
| <ADHESE\_LIB\_ID> | The unique ID of a creative in Adhese. This ID can be used to make JavaScript functions unique. | |
| <ADHESE\_ORDER\_ID> | ||
| <ADHESE\_ORDER\_NAME> | <ADHESE\_ORDER\_NAME\_URIENCODED> | The name of the campaign. |
| <ADHESE\_ORDER\_PRIORITY> | <ADHESE\_ORDER\_PRIORITY\_URIENCODED> | |
| <ADHESE\_POOL\_PATH> | <ADHESE\_POOL\_PATH\_URIENCODED> | The location of where the ad is located on the server. |
| <ADHESE\_POSITION> | <ADHESE\_POSITION\_URIENCODED> | The position of the booking. |
| <ADHESE\_PRIORITY> | <ADHESE\_PRIORITY\_URIENCODED> | The priority of the campaign. |
| <ADHESE\_SHARE> | <ADHESE\_SHARE\_URIENCODED> | Deprecated. |
| <ADHESE\_SWF\_SRC>, <ADHESE\_SWF\_SRC\_2ND>, <ADHESE\_SWF\_SRC\_3RD>, <ADHESE\_SWF\_SRC\_4TH>, <ADHESE\_SWF\_SRC\_5TH>, <ADHESE\_SWF\_SRC\_6TH> | <ADHESE\_SWF\_SRC\_URIENCODED>, <ADHESE\_SWF\_SRC\_2ND\_URIENCODED>, <ADHESE\_SWF\_SRC\_3RD\_URIENCODED>, <ADHESE\_SWF\_SRC\_4TH\_URIENCODED>, <ADHESE\_SWF\_SRC\_5TH\_URIENCODED>, <ADHESE\_SWF\_SRC\_6TH\_URIENCODED> | The target URLs of the uploaded files, will be empty in case not uploaded. |
| <ADHESE\_TAG> | <ADHESE\_TAG\_URIENCODED> | The complete HTML code of an ad: object/embed code in case of a .swf file, JavaScript in case of third-party code, or img link tags in case of a static image. |
| <ADHESE\_TEMPLATE\_CODE> | <ADHESE\_TEMPLATE\_CODE\_URIENCODED> | The code of the template for the position of the booking. |
| <ADHESE\_TEMPLATE\_CODE\_EXPORT> | <ADHESE\_TEMPLATE\_CODE\_EXPORT\_URIENCODED> | The export code of the template of the creative. |
| <ADHESE\_TRACKING\_URL> | <ADHESE\_TRACKING\_URL\_URIENCODED> | The URL for tracking 3rd party impressions. |
| <ADHESE\_URL> | <ADHESE\_URL\_URIENCODED> | The target URL or landing page of the ad, as determined by the user. |
| <ADHESE\_IMPRESSION\_TRACKING\_URL> | <ADHESE\_IMPRESSION\_TRACKING\_URL\_URIENCODED> | The URL to count trackable impressions |
| <ADHESE\_VIEWABLE\_TRACKING\_URL> | <ADHESE\_VIEWABLE\_TRACKING\_URL\_URIENCODED> | The URL to count viewable impressions. |
| <ADHESE\_WIDTH>, <ADHESE\_HEIGHT> | The dimensions of the first uploaded file. | |
| <ADHESE\_WIDTH\_LARGE>,<ADHESE\_HEIGHT\_LARGE> | The dimensions of the second file that is uploaded. |
The sequence value is **stripped from** the response when the adpod or stack response is rendered.
#### Templates **VAST If `sequence=0`, the ad is preferred to be placed first in a pod. If `sequence=-1`, the ad prefers to be placed last in a pod. If `sequence=1` it prefers the second place and so on. This ordering happens after the ads are selected, so there is no guarantee that an ad with `sequence=0` will always be first in the pod (unless if it is the highest priority of all possible options). ```xmlThe sequence field must be added to the **main structure** of the JSON template. The order logic will not work if the field is added inside a nested object in the JSON structure.
```json { "sequence": 0, "example field": "some value" } ``` # Runtime time string replacement and encoding Adhese contains a number of scripts that can be added to any kind of template and will be interpreted at runtime. This allows you to create complex templates where variables can be transformed or encoded via the adheseScript tags. The scripts are useful for URL encoding, JavaScript escaping, string replacement and other similar tasks. Tags in the format `[adheseScript...]` have a corresponding `[/adheseScript]`. Each tag applies some modifications to the text in between these tags. Note that it is possible to nest these tags to apply multiple operations to the same text. The tags are then applied one at a time, with the inner ones being applied first and then the outer ones. Example of nested tags: ``` [adheseScriptBase64Decode] [adheseScriptReplace:-:l]he--o wor-d[/adheseScript] [/adheseScript] ``` Let's look at some tags in more detail. # Non-escaping script tags ## adheseScriptReplace Searches the enclosed input text for the first parameter and replaces it with the second parameter. Search and replace is done with literal text, not with regex. ``` [adheseScriptReplace:-:l]he--o wor-d[/adheseScript] ``` This results in ``` hello world ``` ## adheseScriptLower Puts the enclosed input text in lowercase. ``` [adheseScriptLower]FOOBAR[/adheseScript] ``` results in ``` foobar ``` ## adheseScriptBase64Decode Applies Base64 decoding to the enclosed input text. ``` [adheseScriptBase64Decode]What a nice string of characters[/adheseScript] ``` results in ``` V2hhdCBhIG5pY2Ugc3RyaW5nIG9mIGNoYXJhY3RlcnM= ``` ## adheseScriptUriEncode Applies UriEncoding to the enclosed input text. ``` [adheseScriptUriEncode]What a nice string of characters[/adheseScript] ``` results in ``` What%20a%20nice%20string%20of%20characters ``` # Escaping script tags By default, some escaping is applied to any `[adhese...]` tags. If multiple tags are nested inside each other, the default escaping will only be applied once, after the final tag is executed. The default escaping does the following: ``` ' → \' " → \" \ → \\ ]]> → ]]]]> \b \t \n \r \f unicode characters outside the range 32, 0x7f ``` This should be sufficient for the majority of use cases. However, there may be edge cases where additional control over escaping is required. This can be achieved by utilising one of the tags outlined below. For example: - When used within XML without CDATA tags (although we recommend the use of CDATA tags instead of more complex escaping techniques) - When multiple payloads are nested within each other, a single round of escaping is not enough. The default escaping process would protect against the injection of malicious code into the JavaScript, but an attacker would be able to inject malicious code into the inner HTML. To ensure security, this tag must be escaped twice. ``` var foo = "