Creating and configuring the widget

Attention. The widget only parses content from websites that are displayed in Yandex search and connected to YAN as a content site or its mirror. For example, content taken from a website blocked by Yandex search cannot be displayed in the widget.

The widget is updated with new content within two hours after it's been created. However, this might take longer if you register a brand new YAN domain before creating your widget.

  1. Creating a widget
  2. Embedding the widget
  3. Editing
  4. Quick block
  5. Issues with widget display

Recommendation widgets are placed on content sites. You can create a new content site or use an existing one.

Creating a widget

To create a recommendation widget, go to Products → Recommendation widget and click Add widget. This will open a step-by-step widget builder.

Step 1. General
  1. Select a content site for your widget from the list.
  2. Enter your widget's Name.
Step 2. Content source
  1. Specify the parameters for all the publications that should be upload to the widget.
    • Optimization metrics. Choose your preferred method for processing and choosing recommendations.
      • CTR (Click-Through Rate). This method maximizes the number of clicks on your content that come through the widget.
      • Long clicks. This algorithm maximizes the number of clicks while trying to make user sessions last longer after users click your recommendation.
      Note. In both cases, the recommendations are tailored to the users' interests. The recommendation algorithm also factors in the subject of the page you placed the widget on.
    • Filter viewed content. Enable this option if you want to filter out content that's been viewed by the user. Our algorithm uses machine learning by default, which helps it determine if a user should see content they've already seen or not. Multiple factors are considered before a choice is made. We do not recommend enabling this option. Our experiments show that machine learning handles filtering more effectively.
    • Only display content with images. Disable this option if you want to upload both image-based and text-based content into the widget. If you plan to upload publications without images to the widget, configure the placeholder image.
      Note. This option doesn't apply to ads. Instead, images in ads are displayed based on your ad platform settings.
    • Publication date no older than. If the content you post becomes outdated after a certain period of time (such as news stories), you can specify the number of days after the publication date when it should no longer be displayed in the widget.
  2. Click Add source and specify the domain that hosts the content you want to upload to the widget. The domain must be hosting one of your content sites or its mirrors. The platform doesn't have to be the same one that the widget was created on.
    Attention. You also don't need to specify the address protocol (HTTP, HTTPS).
  3. Set your filter parameters:
    • Allowed tags. If the site pages include tags on them, you can use those tags to filter publications. List tags for the content that should be displayed in the widget and press Enter.
    • Restricted tags. List tags for the content you don't want to display in the widget.
      Tip. After the tags are added to your site's pages, you should wait a few days before using them to filter content. This gives the robot some time to parse these pages and receive the necessary information about the tags. Otherwise, the widget may not have enough recommendations to display.
    • Allowed site sections. Enter the path to the site sections you want to upload into the widget. Specify the path from the site's root directory, starting at /. The maximum path length is 128 characters.
    • Restricted site sections. Only use this parameter if you want to upload publications from all sections except the ones specified (leave the Allowed site sections field empty). The maximum path length is 128 characters.
  4. You can add more domains if necessary (10 max).
Step 3. Design

Customize the appearance of your ad widget using the preview area to check the result.

Preview area

The preview area is a test container. To see how your block will look on the desktop or mobile version of the site, specify its width and height in pixels on top of the text container. For the mobile version of the site, you can evaluate how the block will look on different devices, with the horizontal or vertical screen orientation.

You can scale your preview area, but you will only see changes if the test container fails to fit into the designer field. The scale settings don't affect the block you're creating and are only for convenience. Select the appropriate option from the drop down menu:

  • Autoscaling — The size of the test container is automatically selected to fully fit into the code designer field.
  • Actual size — The length and width of the test container are they same as you manually set in pixels.
  • Fit to width (height) — The test container is displayed so that your width (height) fits the designer field, with the height (width) changes proportionally.
Widget parameters

The recommendation widget is designed as a grid, with each cell hosting some sort of a recommendation or an ad. Select the number of cells along the width and height in the Grid size list. The minimum size is 1 × 2 or 2 × 1, the maximum size is 10 × 10. Make sure to keep the size of the container on the website in mind, since you don't want the cells to appear too small.

Ad parameters
A widget must have at least one cell with an ad space. Choose your layout organization method:

Set the number of ad spaces. Their layout will be updated after each page refresh.

Tip. Choose the number of ad places based on your goal. Recommendations boost your website's conversion rate and other user-related metrics, while ads net you direct remuneration.
Design customization

Select the appropriate Design template from the list.

If you're familiar with HTML and CSS, you can open the Code tab and edit the template. Set up the structure of the widget in the HTML window. The CSS window lets you see various possible styles you can apply.

Step 4. CPM threshold
Step 5. Geo settings

You can set the minimum CPM threshold by region. After you set the threshold in a specific region, the widget will only display ads from advertisers whose CPM exceeds that threshold.

Choose a region and specify your CPM threshold on the right (in RUB, excluding VAT). The CPM threshold of a higher-level region is automatically applied to all its nested regions.
Note. This feature should be used carefully. If you're not careful about setting your CPM threshold, you can potentially filter out all ads and lose remuneration. Do not set a threshold if you aren't sure what you're supposed to do.

Embedding the widget

To embed your widget on a website, do the following:
  1. Go to Products → Recommendation widget.
  2. Find the widget you create and click Get embed code underneath.
  3. You can also change the code loading method in the code window if necessary.
  4. Click Copy to clipboard.
  5. Paste the copied embed code into the container on your page.

We don't recommend pasting the code into a text editor. Some text editors may automatically insert line breaks, which would corrupt the code's syntax.


You can change your widget's settings at any time after the initial setup. Simply find your widget in the list in Products → Recommendation widget and click Edit underneath.

Quick block

Widgets are updated after each robot crawl. New site pages are added quickly, while older pages may take a bit longer to be added to or removed from the widget by a robot.

If you don't want to wait for the next crawl and just want to quickly remove a page manually:

  1. Open Products → Recommendation widget.
  2. Find the widget you need in the list and click Edit.
  3. Open the Content source → Quick block tab.
  4. Click Add document.
  5. Enter the page address.

The page will then be removed from the list in 30 days. If you want to automatically remove this page after each crawl, add the kill metatag to its HTTP header. The widget also does not display pages removed from the site. It may take a while for the robot to update and remove pages in the widget, so we recommend reindexing your page in Yandex.Webmaster.

Issues with widget display

Widget missing from the page

If your widget is missing from the page, the most likely reason is the lack of content. If even a single cell is missing content, the widget will not be displayed. This may happen if your filter conditions are too strict or you made a mistake during configuration. For example:

Incorrect domain specified

The robot selects publications from the domain specified in the settings. Subdomains are not included. For example, if you write in your widget settings, no content from will be displayed in the widget.

Content is unavailable

Content may be excluded from recommendations in your widget for the following reasons:

  • The website has been banned in Yandex search.
  • The site owner blocked the site for the Yandex robot.
Content hosted on the domain hasn't been indexed yet

If you add a domain that was registered in YAN less than 72 hours ago to the widget, its content may not have had enough time to be indexed yet. It will become available in one of the following scenarios:

  • Within 72 hours, if the images are not tagged with og:image or meta property="yandex_recommendations_image".
  • Immediately after you refresh the pages after tagging the images.
Tags are present in settings but don't actually appear in content or too few of them appear

Mark up your content first before specifying allowed tags in the settings. Otherwise the robot won't be able to find any content to display in the widget.

Tags should only be used for filtering content if you're sure there's enough material. Otherwise it's best not to filter anything out.

The robot didn't parse all images in time

If you want the robot to find images quicker, mark up the images with yandex_recommendation_image (top priority level) and og:image (second priority level). Images marked up with other tags will take longer to process, sometimes up to a few days. Because of this, some content may take a while to appear in the widget. If you set your filters to only display new content (such as content created yesterday), then some of it may not make it on the widget. After the image is processed, the publication may be too outdated for the widget.

Issues with an accessible site section

If this happens, your accessible section is either a folder with too little content, or you specified the folder path incorrectly. For example, if you want to upload content from the folder located at, your path in settings should be /news/sport. If you simply write /sport, the robot will not find any content.

Documents have recent publication dates

The document publication timeframe you specified is too recent, so not much content was posted on the site.

The widget displays old content

If you see content that's older than the publication date you specified, then the robot didn't identify the date correctly.

The widget displays wrong images

The robot parses content with images based on its priority level. First the robot uploads elements that have the yandex_recommendations_image metatag. If no such metatag has been found, the robot uploads elements with the og:image metatag. If og:image is also missing, then the robot uploads elements with the third metatag in the priority queue, such as <image>.

Check the tags used for your images, and add the yandex_recommendations_image metatag to the one you want to upload.

I don't see any changes in my widget settings after applying them

Usually the widget is updated within two hours after editing. This is true for content source updates and design changes. If the widget still takes too long to update, contact our support team.