Creating and configuring a widget

Alert

The widget only features articles from sites that appear in Yandex Search results and were added to the Yandex Advertising Network as a primary site or an approved mirror. For example, content taken from a site 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 Yandex Advertising Network domain before creating your widget.

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

Creating a widget

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

Step 1. General

Select a site for your widget from the list.
Enter your widget's Name.

Step 2. Site version

Select the site version to embed the widget on:

Site desktop version.
Site mobile version.

Step 3. Content source

Specify the parameters for all the publications that should be upload to the widget.
- Metrics for optimization. Select a method for the algorithm to select 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've placed the widget on.
- Filter read. Enable this option if you want to filter out the publications that the user already saw. 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.
- Use only image creatives. 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. The display of images in ad slots depends on the site settings.
- Publication date no older than. If the content you post becomes outdated after a while (such as news), you can specify the number of days that should pass from the date of publication before it's no longer displayed in the widget.
Click Add source and specify the domain that hosts the content you want to upload into the widget. The domain must match one of your sites or be specified in its mirrors. The site doesn't have to be the same one where you created the widget.

Alert

You also don't need to specify the address protocol (HTTP, HTTPS).
Set your filter parameters:
- Allowed tags. If you've added tags to your site pages, you can filter publications by the tags. 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 crawl 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 root directory of your site preceded by the / symbol. The maximum path length is 128 characters.
- Restricted site sections. Use this parameter if you want to blacklist publications on certain sections of your site from showing up in the ad unit, entering the paths to them in this field (leave the Allowed site sections of the site field empty). The maximum path length is 128 characters.
You can add more domains if necessary (10 max).

Step 4. 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 check how your ad unit will look on the desktop or mobile version of the site, specify its width and height in pixels over the text container. For the mobile version of the site, you can evaluate how the unit 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 unit you're creating and are only used 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 set manually in pixels.
Fit to width (height): The test container is displayed so that your width (height) fits to the designer field, with the height (width) changed proportionally.

: 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 site in mind, as 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:

Automatically

Manually

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

Use the diagram to choose where you want to place ads in the grid.

Tip

Choose the number of ad places based on the effect you wish to achieve. Recommendations boost your site's conversion rate and other user-related metrics, while ads net you direct revenue.

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 5. CPM floor

Choose a method for determining your CPM floor and click Create.

Embedding the widget

To embed the widget on the desktop or mobile version of the site, go to Websites Ads → Recommendation widget and click Get code next to the desired unit. The ad code consists of two parts: the Yandex Advertising Network loader code and the recommendation widget code.

Loader code

Used for preloading ads.

Embed the loader code on all the pages of the site where you plan to display ads. Copy the code to the clipboard and paste it at the beginning of the page between the <head> and </head> tags.

The loader code is only embedded on the page once and is used to call all Yandex Advertising Network units.

Used for displaying the recommendation widget on the page.

Copy the code to the clipboard and paste it into the HTML code of your site between the <body> and </body> tags in the place where the recommendation widget is to be displayed. If you add it to another place, ads may display incorrectly.

When embedding the code, make sure that:

The code for the units or widgets that should be displayed first is inserted as early as possible.
The ad tag isn't placed in a hidden DOM node or iframe.
The ad on the page isn't blocked by other units and elements.
There are no errors related to the ad tag in the browser console.

Please keep in mind that when copying code, your text editor might truncate or wrap long strings, which might cause the JavaScript code to run incorrectly. Please be attentive and do not modify the tag when copying. The Copy button is the best way to copy the tag.

Editing

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

While in edit mode, you can also set a minimum CPM floor for a specific region in the Geography tab. After you set the floor in a specific region, the widget will only display ads from advertisers whose CPM exceeds that floor.

Choose a region and specify your CPM floor on the right (in RUB, excluding VAT). Nested regions inherit the CPM floor from the top-level region.

Note

This feature should be used carefully. If you're not careful about setting your CPM floor, you can potentially filter out all ads and lose revenue. Do not set a floor if you aren't sure what you're supposed to do.

Quick exclusion

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, do the following:

Open Websites Ads → Recommendation widget.
Find the widget you need in the list and click Edit.
Click the Content source → Quick block tab.
Click Add document.
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. When this happens, the system returns a noItemsForWidget response. 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 domain.ru in your widget settings, no content from sub.domain.ru will be displayed in the widget.

Content is unavailable

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

The site was banned from Yandex Search.
The site owner blocked the Yandex robot.

Content hosted on domain hasn't been indexed yet

If your widget received a domain that has been registered in Yandex Advertising Network 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:

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 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 domain.com/news/sport, 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.