Creating and configuring the widget


The widget only parses content from websites that are displayed in Yandex search and connected to YAN as a content site or its mirror. This means that websites banned in Yandex search will not be displayed in the recommendation 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 your widget
  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 new recommendation widget, open Products → Recommendation widget and click Add widget. This will open a step-by-step widget builder.

Step 1. Common
  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 types of content you're going to upload into 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 interests of users. The recommendation algorithm also factors in the content of the page you've 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 don't recommend using this option as our experiments showed that machine learning is a better way to filter out content.
    • 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 want to upload content without images, you can set up a 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 you host content that can become irrelevant as time goes on (such as news), you can set a limit on your content's publication date and content from earlier will not be displayed in the widget.
  2. Click Add source.
  3. Specify the domain that hosts the content you want to upload into the widget. The domain must be hosting one of your content sites or its mirrors. However, your content site and the site hosting the widget don't have to share the same domain.
    Attention. You also don't need to specify the address protocol (HTTP, HTTPS).
  4. Set your filter parameters:
    • Allowed tags. If your site page has tags, you can use them to filter content in the widget. List tags for the content you want to be displayed in the widget and press Enter.
    • Restricted tags. List tags for the content you don't want to be displayed 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 your widget may miss a lot of recommendations.
    • Allowed site sections. Enter the path to the site sections you want to upload into the widget. The path must start with your website's root section, and the URL must begin with the / symbol. The maximum path length is 128 characters.
    • Restricted site sections. If you want to skip some site sections to filter out their content, you can still specify their paths in case you want to load content from all other sections except those ones (this leaves the Allowed site sections field empty). The maximum path length is 128 characters.
  5. You can add more domains if necessary. You can add up to 10 domains for your ad platforms.
Step 3. Design

Before configuring your widget, setup your preview area. Specify the size of the container before you place an ad block there. Try various widget parameters until the ad block fits into the container.

Use the Preview scale field and choose the scale for the container in the preview area.

Note. The Preview area and Preview scale settings don't actually change the widget. They are just used for preview in the designer.
Widget parameters

The recommendation widget is designed as a grid, with each cell hosting some sort of a recommendation or an ad. The grid size is determined by the number of cells along its width and height, with the minimum size of 1 × 2 or 2 × 1 and maximum size of 10 × 10. Set the Grid size so it fits the container of your website.

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 and their layout will be updated after each page refresh.

Tip. You must have your end goal in mind when choosing the number of ads you want to place. Recommendations boost your website's conversion rate and other user-related metrics, while ads net you direct remuneration.
Design customization

You can use HTML and CSS to customize your widget's appearance. If you don't have any HTML/CSS coding experience, you can select a preset Design template from the list instead.

If you're familiar with HTML and CSS, you can open the Code tab and edit any of the templates however you like. You can use the HTML window to see how your widget is structured. The CSS window lets you see various possible styles you can apply.

Step 4. CPM threshold
Step 5. Geography

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.

To do that, choose a region and specify your CPM threshold on the right (in RUB, ex 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 unsure whether you need this option, it's better to leave it disabled. If you're not careful about setting your CPM threshold, you can potentially filter out all ads and lose remuneration.

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 in your page's code.

It's better not to paste the code into a text editor as some text editors may automatically insert line breaks, which would corrupt the code's syntax.

Editing your widget

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.

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

  1. Open Products → Recommendation widget.
  2. Find the widget you need in the list and click Edit.
  3. Go to the Content sources tab.
  4. Click the Quick block tab.
  5. Click Add document.
  6. 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. Pages that have been removed from their site are also excluded from the widget. 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.

Incorrect domain specified

When looking for content, the robot only parses the domain you explicitly specified in 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 restricted access to the website for the Yandex robot.
Content hosted on domain hasn't been indexed yet

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

  • Images included in your content have been marked up with the tags og:image or meta property="yandex_recommendations_image". In this case, the content will become available right after your apply your settings.
  • Within 72 hours if the images have not been marked up.
Tags are present in settings but don't actually appear in content

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

Tags should only be used for filtering content if you're sure the robot will still find enough material. Otherwise it's best not to filter anything out. You can also add the kill metatag to sections you want to exclude from the widget along with all their content.

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 into the widget, as the publication date will expire before the image is even processed.

Allowed site section is specified incorrectly

If this happens, your allowed 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. Learn more about determining publication dates.

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.