---
metadata:
- name: generator
content: Diplodoc Platform v5.55.0
alternate:
- https://yandex.com/support/adfox/en/ad-inventory/settings/template.md
- https://yandex.com/support/adfox/ru/ad-inventory/settings/template.md
- href: en/ad-inventory/settings/template.md
type: text/markdown
title: Markdown version
- href: ../../llms.txt
type: text/markdown
title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/support/adfox/en/llms.txt
# Templates
A template is a code (JSON, JavaScript, HTML, or XML) that defines the banner appearance and features on the site. The template code contains variables whose values are taken from the parameters of the selected banner.
You can add multiple different templates for one banner type. For example, a placement with the **240 × 400** banner type can also display banners with the **Image** or **Video banner** template.
Templates may be:
- Predefined: Templates created in Adfox and ready for use. For these templates to work correctly, follow the [technical requirements](https://yandex.com/support/adfox/en/banners/specs/index.md).
- Custom: Templates added by Adfox users with custom code.
{% note info %}
Templates for banner types can be added by the account administrator or assistant with the appropriate permissions. For more information about configuring access rights, see [Account types](https://yandex.com/support/adfox/en/settings/users/index.md#access).
{% endnote %}
## How to add predefined templates {#predefined-template}
1. Open the **Settings** → **Banner types** → **Custom** tab. Select [Nondimensional](*non-dim) or [XML](*xml).
1. Create a new banner type or select an existing one for which you want to add a template.
1. To add a template, click **Templates** next to the desired template type.
1. Click **Use preset**.
1. Select a predefined template from the list and click .
{% note warning %}
For a banner in a campaign where impressions are counted using the **Impression (IMS)**, **Viewable Impression (IMS)**, or **Viewable impression, Yandex (IMS)** method, you can select templates labeled as IMS . These templates support [viewability counting](https://yandex.com/support/adfox/en/campaigns/impressions-method.md#viewability) and advanced [anti-fraud](https://yandex.com/support/adfox/en/statistics/ims-compliance.md#fraud) controls for impressions and clicks.
{% endnote %}
1. At the bottom of the page that opens, click **Add**.
{% note info %}
If you add the same predefined template to the banner type more than once, **copy N** is automatically added to the template name, where `N` is the template copy number.
{% endnote %}
In all predefined templates, ad creative parameters are automatically submitted to the state register (provided [ad labeling has been enabled](https://yandex.com/support/adfox/en/labeling/token.md#step-5) for this banner). When adding banners with this template, you'll see the  icon next to the field for your creative.
To stop sending data to the state register for a banner, click the icon. It will turn gray: . When copying a banner with enabled labeling, it will be disabled for a child banner. If you need to enable labeling, you can do it manually.
{% cut "How to disable submitting creative data at the template level" %}
In the template parameters, find the line with the additional variable responsible for the file or code of the creative, and set the **Marking** parameter to `Do not use in marking`.
{% endcut %}
## How to create custom templates {#custom-template}
To add a template that works correctly for an ad tag with the context.js library:
1. Write the HTML code of the banner:
```html
```
1. In the Adfox interface, go to the banner type where you want to add a new template: go to **Settings** → **Banner types** → **Custom**. Select **Nondimensional** or **XML**.
1. Click **Templates** next to the desired banner type. Click **Use preset** and then click  next to the **Code forwarding [context]** template.
1. In the template parameters, find the **Additional variables** section at the bottom. In the **Default value** field of the first additional variable (**HTML ad tag**), insert the HTML code of the banner.
1. We recommend that you select **Prohibit editing**.
1. If you plan to use this template to place ads for which data is submitted to the Russian state register (ERIR) through the Yandex advertising data operator, we recommend that you enable [automatic submission of creative data to the ERIR](#auto-transfer-erir).
1. Next, replace the values in the HTML code that may change from one banner to another (for example, sizes, image links, click-through links, and texts) with special [Adfox macros](#variable-adfox), simultaneously including the variables you use.
For example:
- Replace “Adfox” with the `%banner.user2%` macro in the HTML code, enable additional variable No. 2, and make it mandatory with the String type.
- Replace the link to the logo file with the `%banner.user3%` macro in the HTML code, enable additional variable No. 3, and make it mandatory with the File type.
- Replace the link to the advertiser's site with the `%request.reference_mrc%` macro in the HTML code, and enable the predefined **Transition URL** variable.
```html
```
If the format of the banner is [sticky](*sticky), manually add the layout for the “Ad” label to your ad unit code. We don't recommend enabling the “Ad” label in the banner parameters in Adfox.
1. After you replace all the necessary values with macros, save the changes in the template. You can add banners now.
### Add a template for video ads {#add-video-template}
To add a template with multi-format video support:
1. Open **Settings** → **Banner types** → **Custom** → **XML**. Add a new banner type or open the template list for an existing banner.
1. Click **Add**.
1. Enter the name of the template. Select **Format for describing a multi-format video**.
{style="border: solid 1px #cccccc"}
If you select `no`, the MP4 format with a height of up to 480 pixels is used as the main one. If you specify a `%template.media_files%` macro in the template, it's replaced with an empty string.
1. In the **Template code** block, enter the XML code of the banner with the `%template.media_files%` macro. When a banner created using this template is displayed, the `%template.media_files%` macro is replaced with a code containing a list of generated video files in different formats. This list is only generated when you upload video files via the Adfox interface. If you specify a link to a video from an external source in the banner, the macro is replaced with an empty line.
If necessary, you can add your own format descriptions in XML or JSON form, depending on the format selected for describing a multi-format video, in the `MediaFiles` tag.
When adding your own format to JSON, specify whether your tags come before or after the macro. To do this, use the following extensions:
- `%template.media_files:delimiter_after%`: A comma comes after the macro.
- `%template.media_files:delimiter_before%`: A comma comes before the macro.
- `%template.media_files%`: There's no comma.
The separator is only used if converted files are found and their descriptions are added to JSON. Otherwise, the template is replaced with an empty line. In this way, a correct template is created from a macro when there's a custom description and when a description of the converted formats in JSON may appear.
{% cut "Sample template code for describing a multi-format XML video" %}
```xml
%template.media_files%
```
When the banner is displayed, the following code is sent:
```xml
```
{% endcut %}
{% cut "Sample template code for describing a multi-format JSON video" %}
```xml
```
When the banner is displayed, the following code is sent:
```xml
```
{% endcut %}
[Sample VAST template with a macro for a multi-format XML video](https://doc-static.yandex.net/support/Adfox/vast.xsd)
{% note info %}
If you're using a template with a macro for a multi-format video, when you create a banner, the **Video resolution** field is set to **Selected automatically** by default. In this case, you can't select the video quality.
If no macro is used, the **Video resolution** field defaults to 480p. You can select a different value from the list. If you change it, Adfox will remember your choice and use the new value for any new banners created from this template.
{% endnote %}
1. Click **Add**.
### Macros for templates {#variable-adfox}
Your table can be converted to the following form according to your instructions:
{% cut "Variables in the code" %}
#|
|| **Variable description** | **Variable name in the code** ||
|| Flash video link | `%banner.get_url%` ||
|| Image link | `%banner.image_url%` ||
|| URL of the click-through (a preset variable) | `%request.reference_mrc%` ||
|| URL of the click-through (an additional variable), where `N` is the variable number from 1 to 25. This macro counts clicks and redirects to the advertiser's site | `%banner.reference_mrc_userN%` ||
|| The click-through transfer parameter (the variable name that is specified in the flash video and takes the value of the “URL of the click-through” variable) | `%banner.flash_parameter_name%` ||
|| Enabling [the **Ad**](https://yandex.com/support/adfox/en/labeling/ad-label.md) label on banners. Takes the values of `1` (the label is displayed) or `0` (the label is not displayed) | `%banner.ad_label%` ||
|| Indication of the advertiser in the **Advertisement** label. Displayed if `%banner.ad_label%` takes the value of `1` and the **Domain** field is filled in in the banner parameters | `%banner.domain:jsenc%` ||
|| [Multi-format video](#add-video-template) link. Available for banners with video ads uploaded directly to the Adfox interface | `%template.media_files%` ||
|| The “target” transmission parameter | `%banner.target_parameter_name%` ||
|| Width in pixels. To specify the width as a percentage value, use an additional variable | `%banner.width%` ||
|| Height in pixels. To specify the height as a percentage value, use an additional variable | `%banner.height%` ||
|| The “ALT” image text | `%banner.alt%` ||
|| “TARGET” links. The value is substituted from the banner parameters or from the request in the `p3` parameter | `%banner.target%` ||
|| Background color | `%banner.background_color%` ||
|| Video duration in seconds | `%banner.video_duration%` ||
|| Tracking pixel link. If you don't specify the parameter value in the banner, the "https://banners.adfox.ru/transparent.gif" value is substituted by default | `%banner.tracking_url%` ||
|| An additional variable, where `N` is the variable number from 1 to 25 | `%banner.userN%` ||
|| An event, where `N` is the event number from 1 to 30. You can use events to get information about any actions in the banner, such as banner expansion or hovering over a button | `%banner.eventN%` ||
|| ID of the banner that's selected for serving | `%banner.id%` ||
|| ID of the ad campaign that's selected for impression | `%campaign.id%` ||
|| ID of the site where the banner selected for impression is placed | `%place.id%` ||
|| ID of the section where the banner selected for impression is placed | `%section.id%` ||
|| ID of the site where the banner selected for impression is placed | `%site.id%` ||
|| Account ID | `%owner.id%` ||
|| The number obtained from the request in the `pr` parameter | `%request.page_random%` ||
|| Keywords obtained from the request in the `pk` parameter | `%request.keywords%` ||
|| Random number generator | `%system.random%` ||
|| The banner request protocol. For example, HTTP or HTTPS | `%request.protocol%` ||
|| The value obtained from the request in the `puidN` parameter, where `N` is the additional characteristic number from 1 to 63 | `%request.puidN%` ||
|| The value obtained from the request in the `eidN` parameter, where `N` is the variable number from 1 to 2 | `%request.eidN%` ||
|| The time of the banner request in UTS, the format is the number of seconds since Unix epoch | `%request.timestamp%` ||
|| The placement ID obtained from the request in the `phid` parameter | `%request.placeholder_id%` ||
|| A random number that's generated on the platform for asynchronous codes. Obtained from the request in the `pr1` parameter | `%request.place_random%` ||
|#
{% endcut %}
### Encoding of variable values {#coding-variables}
The values from the banner parameters or from the request in a parameter are inserted into the template code unchanged. But you may need to encode values for some variables.
You encode the values using suffixes that you add to the macro in the template after a colon.
There are three types of encoding:
1. **htmlenc** converts the characters `<`,`>`, and `&`.
```
%banner.user1:htmlenc%
```
Original value:
```
hello// "world", & hello 'world'! + Good morning! < Good afternoon!
```
After encoding:
```
hello// "world", & hello 'world'! + Good morning! < Good afternoon!
```
1. **urlenc** encodes strings into URLs.
```
%banner.user1:urlenc%
```
Original value:
```
hello// "world", & hello 'world'! + Good morning! < Good afternoon!
```
After encoding:
```
hello%2F%2F%20%22world%22%2C%20%26%20hello%20%27world%27%21%20%2B%20Good%20morning%21%20%3C%20Good%20afternoon%21
```
1. **jsenc** uses a backslash (`\`) to escape quotes, line breaks, and slashes.
```
%banner.user1:jsenc%
```
Original value:
```
hello// "world", & hello 'world'! + Good morning! < Good afternoon!
```
After encoding:
```
hello// \"world\", & hello \'world\'! + Good morning! < Good afternoon!
```
### Submit creative data to the state register automatically {#auto-transfer-erir}
If you use Adfox tools for [ad labeling](https://yandex.com/support/adfox/en/labeling/about.md), we recommend that you enable submitting data to the Russian state register (ERIR) for variables that are creatives at the template level. This way, when creating a banner, you'll be able to add a creative in the banner parameters (as usual) without having to fill in the creative data again in the **Creative data for ad register** section.
In preset templates, automatic data submission is enabled by default. You can manually enable or disable data submission to the ERIR both in preset and custom templates.
To set up the submission of creative data to the ERIR:
1. Open the template parameters.
1. In the line with the variable responsible for the ad creative file, select a value for the **Marking** parameter:
- **Use as URL**: If you upload a file (image or video) to this variable.
- **Use as text data**: If the variable contains text (banner title or text). For the **HTML code** variable, also select the **Use as text data** value.
{% note info %}
Don't enable data submission to the state register for the **Transition URL** variable.
{% endnote %}
1. Click **Change** at the bottom of the page.
You should now see the  icon next to the field for your creative when adding banners with this template. The icon means that the data specified in this field will be automatically submitted to the ERIR.
You can disable data submission for each specific banner. To do so, click the  icon next to the ad creative field, and the icon will turn gray (). When you copy a banner, a child banner inherits the parent banner's settings regarding submitting data to the state register.
### Prohibit editing {#edit-ban}
To extend template functionality, additional variables have the **Prohibit editing** option selected, which you can only customize when you add a template from the preset list or create a new one.
{% note info %}
If you select at least one flag when creating a template, the column is displayed in the template parameters. Otherwise, the entire column is hidden.
{% endnote %}
Variables with the “Prohibit editing” flag deselected (by default):
- In the template: When you change the default value in the template for this variable, the new value doesn't apply to previously created banners, but it does to new ones.
- In the banner: When you add a banner, the box for this variable is filled with the default value from the template and can be changed (including when you edit the banner).
When you disable a variable in the template:
- In the template: The value specified in the **Default value** field is deleted.
- In banners: The variable and its value are completely deleted from all previously created banners.
When you re-enable a variable in the template:
- In the template: You can specify another value in the **Default value** box that will only apply to newly created banners.
- In banners: The variable appears in all previously created banners with the old value that was specified in the **Default value** box at the template level before you disabled the variable. Alternatively, it gets the new value if you redefined it at the banner level.
Variables with the “Prohibit editing” flag selected:
- In the template: You can edit the default value, and the changes apply to all banners, including the previously created ones.
- In the banner: The box for this variable is filled in with the default value from the template. You can't edit it.
When you disable a variable in the template:
- In the template: The value specified in the **Default value** field is deleted. The **Prohibit editing** option remains enabled.
- In banners: The variable and its value are completely deleted from all previously created banners.
When you re-enable a variable in the template:
- In the template: You can specify a new value in the **Default value** box.
- In banners: The variable appears in all previously created banners with an empty value or with a new value specified in the **Default value** box at the template level.
#### Example of prohibited editing {#example}
> The template includes two additional variables:
>
> - user1: **Width**, default value: `100 px`, editing prohibited: `no`.
> - user2: **Bar text**: default value `Ad`, editing prohibited: `enabled`.
>
> Let's create a banner where default values apply to all variables, but the value of the **Bar text** variable can't be edited.
>
> Now we change the default values in the template:
>
> - user1: **Width**, default value: `200 px`, editing prohibited: `no`.
> - user2: **Bar text**: default value `Network ads`, editing prohibited: `enabled`.
>
> The banner automatically changes the value only for the user2 variable **Bar text**, while the value for the user1 variable stays the same:
## Set up template visibility {#viewability-template}
To open the template list, go to **Settings** → **Banner types** and click **Templates** next to the desired banner type.
The enabled templates are displayed in the available template list when you add a banner.
If you want to hide any templates from the list when creating new banners, disable the template and click **Change**. Previously added banners continue to be displayed on the site.
## How to delete templates {#delete-template}
{% note alert %}
After you delete a template, banners created with it are no longer displayed on the site.
{% endnote %}
To delete a template, go to **Settings** → **Banner types** and click **Delete** next to the template's name.
## Contact support
Send an email
[*sticky]: The banner is fixed in the browser window and stays in the viewport as the user scrolls through the page.
[*non-dim]: Such banner code can be exported in JSON format (or JavaScript/HTML).
[*xml]: The [ad tag](https://yandex.com/support/adfox/en/ad-inventory/codes/code-loader.md#xml-code) is just a request string that returns an XML code.