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, it means that a site with the banner type 240 × 400 can display the Image or Video banner templates.

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

  • Preset: 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 preset templates

  1. Open Settings → Banner types → Custom → Nondimensional → XML.

  2. Create a new banner type or select an existing one for which you want to add a template.

  3. Add the template. To do this, click Templates.

  4. Click Use preset.

  5. Select a preset template from the list and click .

    Warning

    For a banner in a campaign with an impression count method of Impression (IMS), Viewable impression (IMS), and Viewable impression, Yandex (IMS), select IMS  templates. Only such templates support viewability counting and anti-fraud controls for impressions and clicks.

  6. At the bottom of the page that opens, click Add.

If you add the same preset 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 preset templates, creative parameters are automatically submitted to the state register (if ad register is enabled for the banner). When adding banners with such a template, you'll see this icon next to the field for your creative: . To disable submitting data for a specific banner, click on this icon. It will turn gray: . When you copy a banner with active labeling, labeling on a child banner is turned off. If you need to enable labeling, do it manually.

How to disable submitting creative data at the template level

To disable submitting creative data to the state register (Unified Register of Online Advertising), go to the template parameters, find the line containing the additional variable that is responsible for the file or code of the creative, and for the Marking parameter, select the Do not use in marking value.

How to create your own template

Add your own template

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

  1. 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/m/pic/2013/08/19/06/32/05/products_logo_1.png">Adfox. Place and manage site ads</a>
      </div>
    </div>
    
  2. In the Adfox interface, go to the banner type where you want to add a new template. Add a Code forwarding [context] template from the preset list.

  3. Open the template parameters.

  4. In the Default value box, insert the HTML code of the banner for additional variable No. 1 HTML ad tag.

  5. We recommend that you select Prohibit editing.

  6. If you plan to use this template to place ads for which data is submitted to the Russian state register (Unified Register of Online Advertising) through the Yandex advertising data operator, we recommend that you enable automatic submission of creative data to the Unified Register of Online Advertising

  7. 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, include an additional variable #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, include an additional variable #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 include a preset 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. Place and manage site ads</a>
      </div>
    </div>
    

    If the banner has the sticky format, manually add the layout for the “Ad” label to your unit code. We don't recommend including the “Ad” label in the banner parameters in Adfox.

  8. After you replace all the necessary values with macros, save the changes in the template. You can add banners.

Add a template for video ads

To add a template with multi-format video support:

  1. Open Settings → Banner types → Custom or XML. Add a new banner type or open the template list for an existing banner.

  2. Click Add.

  3. 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 main one. If you specify a %template.media_files% macro in the template, it's replaced with an empty string.

  4. 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 to 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 multiformat video macro is used in 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 to 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

  5. Click Add.

Macros for templates

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

Variable description

Variable name in the code

Flash video link

%banner.get_url%

Image link

%banner.image_url%

FLV video link

%banner.get_flv%

Click URL (a preset variable)

%request.reference_mrc%

Click URL (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 transfer parameter (the variable name that is specified in the flash video and takes the value of the “Click URL” variable)

%banner.flash_parameter_name%

Enabling the Ad 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 Ad 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 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 in %, use an additional variable)

%banner.width%

Height (in pixels. To specify the height in %, 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%

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 campaign that's selected for impression

%campaign.id%

ID of the placement 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 placement 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:

  1. htmlenc escapes the <, >, & characters

    %banner.user1:htmlenc%
    

    Original value:

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

    After encoding:

    hello// "world", & hello 'world'! + Good morning! < Good afternoon!
    
  2. urlenc produces the urlencode of the string.

    %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
    
  3. jsenc escapes (\) quotes, newlines, 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

If you use Adfox tools for ad register, we recommend that you enable submitting data to the Russian state register (Unified Register of Online Advertising) 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 Unified Register of Online Advertising both in preset and custom templates.

To set up the submission of creative data to the Unified Register of Online Advertising:

  1. Open the template parameters.

  2. In the line with the variable responsible for the creative, for the Marking parameter select a value:

    • Use as URL: If you upload a creative as a file (image or video).
    • Use as text data: If the variable contains a text (for example, title or banner text). For the HTML code variable, also select Use as text data.

    Note

    You don't need to enable data submission to the Unified Register of Online Advertising for the Click URL variable.

  3. Click Change at the bottom of the page.

After that, you'll see the   icon next to the field for your creative when adding banners with this template. This icon means that the data specified in this field will be automatically submitted to the Unified Register of Online Advertising.

You can disable the data submission for each specific banner. To do so, click the  icon next to the creative field to make it turn gray (). When you copy a banner, a child banner inherits the parent banner's settings pertaining to 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 enable at least one option when creating the template, the column is displayed in the template parameters. Otherwise, the entire column is hidden.

Variables with the “Prohibit editing” option 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 box 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” option selected:

  • In the template: You can edit the default value, and the changes apply to all banners, including the ones previously created.
  • 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 box 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 advertising, 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, open the Settings → Banner types tab and click Templates opposite the necessary 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 for 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