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 substituted from the parameters of the banner selected for impressions.

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 templates.

Templates for banner types are added by the account administrator. Templates can be:

Predefined: Templates that are created in Adfox and ready for use. For these banner templates to work correctly, follow the technical requirements.
Custom: Templates that are developed by the Adfox client independently.

How to add predefined templates

Open Settings → Banner types → Custom → Nondimensional or XML.
Create a new banner type or select an existing one for which you want to add a template.
Add the template. To do this, click Templates.
Click Use preset.
Select a predefined template from the list and click .

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 and advanced anti-fraud controls for impressions and clicks.
At the bottom of the page that opens, click Add.

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.

In all predefined templates, ad creative parameters are automatically submitted to the state register (provided ad labeling has been enabled for this banner). When adding banners with such a template, you'll see the icon next to the field for the creative. To stop sending data to the state register for a banner, click the icon. It will turn gray: . When copying a banner with labeling enabled, it will be disabled for a child banner. If you need to enable labeling, you can do it manually.

How to disable submitting creative data at the template level

To disable submitting creative data to the state register (ERIR), go to the template parameters, find the line with the additional variable responsible for the file or code of the creative, and select Do not use in marking for the Marking parameter.

How to create a custom template

Add a custom template

To add a template that works correctly for an ad tag with the context.js library:

Write the HTML code of the banner.

For example:

<div style="max-width:500px;">
  <h1 style="text-align: center;"><a style="text-decoration: none; color:red;" href="https://adfox.ru/ru/">Adfox</a></h1>
  <div style="display: inline-flex; padding-left: 5px;">
    <a href="https://adfox.ru/ru/product/adfox_sites/" target="_blank" style="text-decoration: none; color:red; padding-left: 5px;">
      <img src="https://adfox.ru/ru/product/adfox_sites/">Adfox. Site ads placement and management</a>
  </div>
</div>

In the Adfox interface, go to the banner type where you want to add a new template. Add the Code forwarding [context] template from the predefined list.
Open the template parameters.
In the Default value field of the first additional variable (HTML ad tag), insert the HTML code of the banner.
We recommend that you select Prohibit editing.
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.
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, 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.
```
<div style="max-width:500px;">
  <h1 style="text-align: center;"><a href="%request.reference_mrc%">%banner.user2%</a></h1>
  <div style="display: inline-flex; padding-left: 5px;">
    <a href="%request.reference_mrc%" target="_blank" padding-left: 5px;">
      <img src="%banner.user3%">Adfox. Site ads placement and management</a>
  </div>
</div>
```
If the format of the banner is 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.
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

To add a template with multi-format video support:

Open Settings → Banner types → Custom → XML. Add a new banner type or open the template list for an existing banner.
Click Add.
Enter the name of the template. Select Multi-format video description format.

If you select no, the MP4 format with a height of up to 480 pixels is used as the default one. If you specify a %template.media_files% macro in the template, it's replaced with an empty string.

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.

Sample template code for describing a multi-format XML video

<xml>
  <someTag>
    <MediaFiles>
      %template.media_files% <!-- multi-format video macro -->
    </MediaFiles>
  </someTag>
<xml>

When the banner is displayed, the following code is sent:

<xml>
  <someTag>
    <MediaFiles>
      <!-- The multi-format video macro expands into a list of converted formats -->
      <MediaFile type="video/mp4" width="480" height="240" bitrate="322" delivery="progressive" isScalable="true" keepAspectRatio="true">
        <![CDATA[http://strm.yandex.ru/video1]]>
      </MediaFile>
      <MediaFile type="video/mp4" width="560" height="320" bitrate="441" delivery="progressive" isScalable="true" keepAspectRatio="true">
        <![CDATA[http://strm.yandex.ru/video2]]>
      </MediaFile>
      <MediaFile type="video/mp4" width="680" height="460" bitrate="522" delivery="progressive" isScalable="true" keepAspectRatio="true">
        <![CDATA[http://strm.yandex.ru/video3]]>
      </MediaFile>
      <MediaFile type="application/mpeg" width="" height="" bitrate="" delivery="streamming" isScalable="true" keepAspectRatio="true">
        <![CDATA[http://strm.yandex.ru/video4.m3u8]]>
      </MediaFile>
      </MediaFiles>
  </someTag>
<xml>

Sample template code for describing a multi-format JSON video

<xml>
  <someTag>
    <!-- The multi-format video macro is used inside the CDATA section -->
    <![CDATA[
      jsonData = [%template.media_files%];
    ]]>
  </someTag>
<xml>

When the banner is displayed, the following code is sent:

<xml>
  <someTag>
    <!-- The multi-format video macro expands into an array of converted formats -->
    <![CDATA[
      jsonData = [{
  "url" : "http://strm.yandex.ru/video5",
  "type" : "video/mp4",
  "width" : "480",
  "height" :"240",
  "bitrate" :"322",
  "delivery" :"progressive"
},
{
  "url" : "http://strm.yandex.ru/video6",
  "type" : "video/mp4",
  "width" : "480",
  "height" :"240",
  "bitrate" :"322",
  "delivery" :"progressive"
},
{
  "url" : "http://strm.yandex.ru/video7",
  "type" : "video/mp4",
  "width" : "480",
  "height" :"240",
  "bitrate" :"322",
  "delivery" :"progressive"
},
{
  "url" : "http://strm.yandex.ru/video8.m3u8",
  "type" : "application/mpeg",
  "width" : "",
  "height" :"",
  "bitrate" :"",
  "delivery" :"streamming"
}];
]]>
  </someTag>
<xml>

Sample VAST template with a macro for a multi-format XML video

Note

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.

Click Add.

Macros for templates

Your table can be converted to the following form according to your instructions:

Description of the variable	Variable name in the code
Link to a flash video.	`%banner.get_url%`
Image link	`%banner.image_url%`
Click-through URL (predefined variable).	`%request.reference_mrc%`
Click-through URL (additional variable), where N is the variable number from 1 to 25. This macro counts the number of clicks and redirects to the advertiser site.	`%banner.reference_mrc_userN%`
Click-through transfer parameter (the variable name that is specified in the flash video and takes the value of the “Click-through URL” variable).	`%banner.flash_parameter_name%`
Ad label flag for the 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 Ad label. Displayed if `%banner.ad_label%` is set to `1` and the Domain field in the banner parameters is not empty.	`%banner.domain:jsenc%`
Link to a multi-format video. Available for banners with video ads that were uploaded directly to the Adfox interface.	`%template.media_files%`
Parameter used to pass the “target” value.	`%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%`
ALT image text	`%banner.alt%`
Link's “TARGET”. The value is inserted from the banner parameters or pulled from the request's `p3` parameter.	`%banner.target%`
Background color	`%banner.background_color%`
Video duration in seconds	`%banner.video_duration%`
Link to the tracking pixel. If you don't set the value of this parameter in the banner, it defaults to "https://banners.adfox.ru/transparent.gif".	`%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. Events help you learn what actions a user took within a banner. For example, expanded the banner or hovered over a button.	`%banner.eventN%`
ID of the banner selected for an impression.	`%banner.id%`
ID of the ad campaign selected for an impression.	`%campaign.id%`
ID of the placement where the banner selected for an impression is placed in.	`%place.id%`
ID of the section where the banner selected for an impression is placed in.	`%section.id%`
ID of the site where the banner selected for an impression is placed in.	`%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 number of an additional characteristic, 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 a UTS, the format is the number of seconds since the 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%`

Encoding of variable values

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:

htmlenc converts the characters <,>, and &.

%banner.user1:htmlenc%

Original value:

hello// "world", & hello 'world'! + Good morning! < Good afternoon!

After encoding:

hello// "world", &amp; hello 'world'! + Good morning! &lt; Good afternoon!

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

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!

Automatic submission of information about ad creatives to the state register

If you use Adfox tools for ad labeling, 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 predefined templates, automatic data submission is enabled by default. You can manually enable or disable data submission to the ERIR both in predefined and custom templates.

To set up the submission of creative data to the ERIR:

Open the template parameters.
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

Don't enable data submission to the state register for the Transition URL variable.
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

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

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.

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

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

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.

Alert

After you delete the templates, the banners based on them are no longer displayed on the site.

Contact support

Send an email

Was the article helpful?

Banner types