Native design

Attention. By using natively designed blocks, you accept the risks laid out in paragraph 3.21 of the Offer agreement. Before you start designing your template, make sure to read the current advertising legislation, including the requirements set for mandatory advertisement elements and their size.

Native advertising is an ad format that flexibly adapts to the site design.

You can define the set of elements in the ad: title, text, image, and so on. Some elements are required by advertising law and the Yandex Advertising Network terms. Other elements are optional: use them to seamlessly place an ad on your resource.

Customize the HTML and CSS settings to blend the ad into your site.

Add a native design when editing or creating an RTB block: in the visual designer, when setting up the Advertising formats, click Add formatNative design.

Design customization

The appearance of the block is configured on the Code tab of the Advertising formats windows in the visual designer.

Note. If you don't have any experience with HTML or CSS, we strongly recommend that you use one of our design templates. On the General tab, select a template from the Design template list and change the grid size and background to adapt the template to your site.
Main block elements

Each displayed element corresponds to its own HTML tag.

Add the mandatory design elements: according to the Yandex Advertising Network terms, they must be in the ad block. Please keep in mind that ads for mobile apps and other ad types have different sets of required elements.

Here is a simple template that uses all the available elements:

<div class="wrapper">
  <div class="headline">Read also</div>
  <ya-units-grid cols="${grid_columns}" rows="${grid_rows}">
    <div class="image"><ya-unit-image /></div>
    <div class="title"><ya-unit-title /></div>
    <div class="age"><ya-unit-age /></div>
    <div class="warn"><ya-unit-warning /></div>
    <div class="desc"><ya-unit-desc /></div>
    <div class="domain"><ya-unit-domain /></div>
    <div class="meta">
      <span class="category"><ya-unit-category /></span>
    </div>
  <ya-unit-close />
  </ya-units-grid>
 </div>
  

You can use this for:

  • Change the block's appearance from a grid (<ya-units-grid />) to a slider (<ya-units-slider />).
  • Add your own layout to the template.
  • Swap elements (don't disrupt nesting) or nest elements into other HTML tags.
  • Remove elements you don't want them displayed in the block. For example, if you wish to hide description, delete the line <ya-unit-desc />.
Important.

The template must include the element <ya-units-grid /> or <ya-units-slider />. You cannot delete these elements as they are required for the block to work properly. All elements using the format <ya-unit-...> must be located inside <ya-units-grid /> or <ya-units-slider />.

Please be sure to follow the requirements laid out for the mandatory ad elements so that your ad complies with the Yandex Advertising Network Terms of Use and advertisement law.

Required ad elements
Element HTML tag Required ad element Required mobile app ad element
The “Ad” label <ya-unit-category/> Yes Yes
Age rating. Displayed if present in ads <ya-unit-age/> Yes Yes
Disclaimer. Displayed if present in ads <ya-unit-warning /> Yes Yes
Close button <ya-unit-close/> Yes Yes
Ad title <ya-unit-title/> Yes no
Domain <ya-unit-domain/> Yes no
Price <ya-unit-price/> no Yes
App name <ya-unit-app-name/> no Yes
App icon <ya-unit-app-icon/> no Yes
App action button <ya-unit-mobile-app-button/> no Yes
CSS class styles
CSS classes have multiple formatting styles:
  • headline — Block header
  • title — Cell ad header
  • category — "Ad" label
  • wrapper — The overall appearance of the block
  • grid-row — Grid row
  • grid-item — Grid cell
  • grid — Grid
  • ya-units-slider — Overall slider appearance
  • ya-slider-item — Card inside the slider
  • unit-wrapper — Ad space
  • unit-image — Image used in the ad

You can also create your own CSS classes and customize their styles.

General design settings

These are the basic options for design customization. They don't require any advanced markup skills.

Configuring native ad block design

Native blocks may have the appearance of a grid of a specific size or of a slider (a horizontal scrollable ad feed). The grid is rendered by <ya-units-grid/> while the slider is rendered by <ya-units-slider />. You can't use both of these elements within the same template.

Setting up the grid

The <ya-units-grid> element is used to draw the grid based on parameters specified in the Grid size fields. You can only change the grid size using these fields.

Exception: if you need to display a different grids for different screen sizes, specify the corresponding values in the sizes. parameter. The ${grid_columns}x${grid_rows} valuables must be listed last. For example:
HTML
<ya-units-grid sizes="(max-width: 1024px) 2x2, (max-width: 600px) 2x1, ${grid_rows}x${grid_columns}">
Here is how grids are going to be matched to different screen sizes in this example:
  • A 2 × 1 grid will be displayed on screens less than 600 pixels wide.
  • A 2 × 2 grid will be displayed on screens between 601 and 1024 pixels wide.
  • Screens wider than 1025 pixels will display a grid based on the values set in the Grid size fields on the General tab.
Important. Keep in mind that you should set the number of displayed ad block cells in the HTML code. To specify the number of ads to load, change the values in the Grid size fields. For example, if you set the Grid size to 5 × 2 while the <ya-units-grid> element is configured to display a 2 × 2 grid for this screen size instead, then only 4 out of 10 loaded ads will be displayed. The opposite is also possible: if you have a 5 × 2 grid while the number of ads is set to 2 × 2, then the block will display six empty cells.
The grid layout is configured via CSS classes grid, grid-row, and grid-item. For example:
CSS
.grid-row {
  margin-top: 10px; /* vertical distance between cells — 10 pixels */
}
.grid-item {
  margin-left: 20px; /* horizontal distance between cells — 20 pixels */
}
.grid {
  border: 1px solid #000; /* border around the grid: thickness — 1 pixel, border type — solid, color — black */
}
Setting up the slider
To render an ad block as a slider, use the <ya-units-slider /> element.
Example of a slider template:
<div class="block">
  <div class="headline">Read also</div>
  <ya-units-slider>
    <div class="unit">
      <ya-unit-close />
      <div class="image">
        <ya-unit-image ratio="0.5" />
      </div>
      <div class="body">
        <div class="title">
          <ya-unit-title />
        </div>
        <div class="meta">
          <span class="category">
            <ya-unit-category />
          </span>
          <span class="date">
            <ya-unit-date />
          </span>
        </div>
      </div>
    </div>
  </ya-units-slider>
</div>
The slider design can be customized in CSS using the classes ya-units-slider (overall slider appearance) and ya-slider-item (a specific card within the slider):
.ya-units-slider {
  width: 95vw;
}
.ya-slider-item:not(:first-child) {
  margin-left: 1em;
}
You can add an ad scroll button to your slider. To do this, find the element <ya-units-slider> and add the element <ya-slider-button>. The scroll direction is indicated with the direction attribute:
  • The left value sets scrolling to the left. The scroll button will be placed before the ads in the slider.
  • The right value determines scrolling to the right. The scroll button will be placed after the ads in the slider.
If <ya-slider-button> includes an element with the ya-clickable class, then scrolling will be triggered once the element is clicked on. If there is no such element, scrolling is performed by clicking on the button itself.
For example:
<ya-slider-button direction="left">Back to top</ya-slider-button>
When you scroll to the leftmost or rightmost position, the element <ya-units-slider /> receives the classes ya-slider-leftmost or ya-slider-rightmost respectively.
Note. If the scroll buttons are located above the slider cell, we don't recommend hiding them using these classes: this can lead to invalid clicks.
Customizing the overall ad block design
To customize your ad block's overall appearance, such as the text background color or margins, you need to wrap all of the ad block's code in the wrapper class tag and set up parameters for that CSS class. For example:
HTML
<div class="wrapper">
  <ya-units-grid cols="${grid_columns}" rows="${grid_rows}">
  ...
  </ya-units-grid>
</div>
CSS
.wrapper {
  background: #fff; /* background color — white */
  padding: 10px; /* margins inside the border, all sides — 10 pixels */
  margin: 5px; /* margins outside the border, all sides — 5 pixels */
  border: 2px solid #000; /* border: thickness — 1 pixel, border type — solid, color — black */
  border-radius: 6px; /* round the border's corners after 6 pixels */
}
Restricting the number of rows displayed
May be useful for a header or a recommendation description. If you want to limit the number of rows displayed in the ad block, wrap the element you need in the <ya-clamp> tag. For example:
HTML
Original header style:
<div class="title"><ya-unit-title /></div>
After limiting the number of displayed rows to two:
<ya-clamp lines="2" class="title"><ya-unit-title /></ya-clamp>
Or
<div class="title"><ya-clamp lines="2"><ya-unit-title /></ya-clamp></div>
Text formatting
You can use CSS to format your text. Choose the class of the element you wish to configure and change its values. For example:
Setting up the font and spacing
CSS

.headline {
  font-family: Helvetica, sans-serif; /* font  */
  font-size: 18px; /* font size — 18 pixels */
  font-weight: bold; /* font thickness (weight) — bold */
  font-style: italic; /* font style — italics */
  line-height: 24px; /* line spacing — 24 pixels */
  letter-spacing: 1px; /* character spacing — 1 pixel*/
  text-decoration: underline; /* text decoration — underlined */
  text-transform: uppercase; /* text case — all uppercase */
  text-align: right; /*  text alignment — right */
  color: #373e44; /* text color — dark gray */
  background: #fff; /* background color — white */
}
                          
.category {
  color: #093; /* text color — green */
  font-size: 12px; /* font size — 12 pixels */
  text-transform: uppercase; /*  text case — all uppercase */
}
                        
Configuring margins
CSS

.headline {
  padding-top: 10px; /* top margin — 10 pixels */
  padding-right: 10px; /* right margin — 10 pixels */
  padding-bottom: 10px; /* bottom margin — 10 pixels */
  padding-left: 10px; /* left margin — 10 pixels */
}
Making a border around text
CSS

.headline {
  border: 1px solid #000; /* border: thickness — 1 pixel, border type — solid, color — black */
}
Configuring cell design

You can use the unit-wrapper class to configure the background color or border for each cell. For example:

CSS
.unit-wrapper {
  background: #fff; /* background color — white */
  border: 1px solid #666; /* border: thickness — 1 pixel, border type — solid, color — gray */
  padding: 5px; /* margins inside cell — 5 pixels */
  border-radius: 5px; /* round the border corners after 6 pixels */
}
Cells that contain ads without images can have their own unique layout, which you can set using the <unit-wrapper.unit-without-image> class. For example:
CSS
.unit-wrapper.unit-without-image {
  background: #fff; /* background color — white */
  border: 1px solid #666; /* border: thickness — 1 pixel, border type — solid, color — gray */
  padding: 5px; /* margins outside the border — 5 pixels */
  border-radius: 6px; /* round the border's corners after 6 pixels */
}
Setting up image layout inside a cell
To configure the image layout in the HTML template, use the <ya-unit-image> element. You can use it to:
  • Set the aspect ratio (the ratio parameter).
  • Display a video instead of an image.
  • Specify the path to a placeholder image (used in ad blocks if your ad doesn't have any images to display) with the src parameter.
For example:
HTML
<ya-unit-image ratio="0.5" enable-video src="https://example.com/image/image.png">
You can set other parameters in CSS (such as the image's maximum height or rounding corners) by changing the parameters in the unit-image class. For example:
CSS
.unit-image {
  max-height: 200px; /* maximum height — 200 pixels */
  border-radius: 4px; /* round the border corners after 4 pixels */
}
Adapting your ads' appearance to fit different website designs

You can dynamically change your ad design to fit different site sections or visual themes (such as light or dark themes). To do this, add the additionalClasses parameter to the embed code and list a class array inside it. For example:

<script>
    (yaads = window.yaads || []).push({
        id: "123456-7",
        render: "div",
        additionalClasses: ["dark", "light"]
    });
</script>

When the code is called, the following classes will be added to the root element <ya-units-grid> or <ya-units-slider>:

<ya-units-grid cols="1" rows="1"> <!-- when calling the code, classes are added to the root element -->
  <div class="image">
    <ya-unit-image ratio="1" />
  </div>
</ya-units-grid>

Now you can set the element styles so that the rules are only applied when the added classes are included in the root element. To do this, go to the Design tab in the CSS settings and set the desired properties to the elements using the added classes. For example:

.dark .image {
  background-color: black;
}
                
.light .image {
  background-color: white;
}
Close button settings

You can change the button's appearance or disable the tooltip that appears when hovering the cursor over the button.

Disabling the tooltip

When you hover your mouse over the close button, a tooltip appears. You can disable it using the disableTooltip parameter: <ya-unit-close disableTooltip/>. For example:

<div class="wrapper">
  <ya-units-grid cols="5">
    <ya-unit-close disableTooltip>
      <div class="super-tooltip">Close</div>
    </ya-unit-close>
  </ya-units-grid>
</div>
Customize the appearance of the tooltip and the close button

Use the .ya-ad-close-hovered class in CSS to make the tooltip appear as you hover the mouse over the close button.

If you want the close button to pop up when you hover the mouse over the tooltip instead, use the .ya-unit-item-hovered class. For example:

.super-tooltip {
  display: none;
}
/* a tooltip pop up when hovering the mouse over the close button */
.ya-ad-close-hovered .super-tooltip {
  display: block; /* display as a block element */
  position: absolute; /* absolute positioning */
  width: 45%; /* width — 45% */
  height: 8%; /* height — 8% */
  top: 14%; /* position relative to top border — 14% */
  left: 20%; /* position relative to left border — 20% */
  background-color: black; /* background color — black */
  color: white; /* text color — white */
}
/* close button appears when hovering over an ad*/
.ya-unit-item-hovered .ya-ad-close {
  display: block; /* display as a block element */
}
.ya-ad-close {
  display: none; 
  /* a clickable 7px-wide area around the close button */
  padding: 7px; /* margins around the border, all sides (7 px) */
  border-radius: 5px; /* rounding out the border's corners after 5 px */
  background-color: red; /* background color — red */
  width: 40px; /* width — 40 px */
  height: 40px; /* height — 40 px */
  top: 10%; /* position relative to top border — 10% */
  right: 10%; /* position relative to right border — 10% */
}

You can also change the system image for the button: to do this, specify a link to your SVG image using the svg parameter. For example:

<ya-unit-close svg="data:image/svg+xml;base64,PD94..." />
Setting up an additional field in the feedback menu

To add a customizable field to the feedback menu, you can use the customField and customFieldUrl parameters:

<ya-unit-close customField="Super PRO" customFieldUrl="https://yandex.ru" />
Adding advertiser information

You can add advertiser info to your ads:

The website's favicon

You can add a favicon using the <ya-unit-favicon /> element.

The favicon has a fixed size that can be set with the size parameter. The valid sizes are 16, 32, and 120 (16 by default). For example:

<ya-unit-favicon size="32" />
Logo

You can add the advertiser's logo to be displayed on your block's ads using the <ya-unit-logo />element.

For cases where the publication doesn't have a logo, set a placeholder image in the src parameter. The placeholder image has zero height by default.

<ya-unit-logo src="https://example.com/image/image.png" />
If the publication does not have a logo, it's replaced with other elements in the following order: favicon — image — placeholder. You can change this order in the disabledSubstitution parameter:
  • <ya-unit-logo disabledSubstitution="all" /> — Excludes both the favicon and the image. The logo is immediately replaced with a placeholder
  • <ya-unit-logo disabledSubstitution="favicon" /> — Excludes the favicon: the logo is replaced with an image, or a placeholder if no image is found.
  • <ya-unit-logo disabledSubstitution="image" /> — Excludes the images: the logo is replaced with a favicon or a placeholder if no favicon is found.
Sitelinks

Added using the <ya-unit-sitelinks /> element. The number of sitelinks can be limited by the limit: parameter.

Physical address

Added using the <ya-unit-address /> element.

Action button settings

You can add an action button to your ad that will act as the ad link for the user. To do this, add the element <ya-unit-direct-button />.

The text on the button is chosen by the advertiser in Yandex.Direct. To make this text appear during ad rendering, specify a special value {BUTTON_CAPTION} inside <ya-unit-direct-button/>, such as:

<ya-unit-direct-button><div>{BUTTON_CAPTION}</div></ya-unit-direct-button>

The user's browser will render the element as <div/>:

<div class="ya-unit-direct-button"><div>Get discount</div></div>
Mobile app ad design
Mobile app ads have their own set of elements that can be added to your template:
Required ad elements
App name
Added using the element <ya-unit-app-name />.
App icon
The app icon is handled by the element <ya-unit-app-icon/>. The icon's aspect ratio is 1:1. You can also specify a placeholder image in case your ad doesn't have an icon, such as <ya-unit-app-icon src="https://someurl"/>.
App action button
Looks like a button with text, such as “Install” or “Download”. Added via the element <ya-unit-mobile-app-button/>, which is rendered as <div/> with the specified text in the user's browser.
Price (with the currency symbol)
Added using the <ya-unit-price/> element.
Additional elements
App rating
Added using the <ya-unit-rating/> element. Must be between 0 and 5. Looks like five gray star outlines, some of which are filled in yellow. The number of filled-in stars corresponds to the app's rating. Fractions are also supported (for example, a rating of 3.5 is displayed as 3.5 yellow stars).

To display the rating using the shortened format, use the parameter isShort: <ya-unit-rating isShort= />. The rating will then be displayed as one yellow star with the rating itself as a number next to it.

Total number of ratings in the app rating
Added using the element <ya-unit-review-count/>. We recommend using this element together with the app rating.

When rendering mobile app ads, the ad elements are assigned the .ya-unit-item-rmp class, which you can use to customize the design of similar ads in CSS.

Statistics

To view a report on native design impressions for an ad block, expand its card menu and click Statistics.

The Monetization report will open with slices by RTB block ID, native design ID, and design name.