Creating and configuring a widget

Alert

Widgets only parse content from websites that are displayed in Yandex search and connected to Yandex Advertising Network as a 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 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 Ads on websites → Recommendation widget and click Add widget. This will open a step-by-step widget builder.

Step 1. General
  1. Select a site for your widget from the list.
  2. Enter your widget's Name.
Step 2. Site version

Select the website version to embed the widget on:

  • Desktop website version.
  • Mobile website version.
Step 3. 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 site doesn't have to be the same one that the widget was created on.

    Alert

    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 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 see how your unit 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 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 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 ad unit 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. 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 placement. Choose your layout organization method:

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 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 set the style.

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 Ads on websites → 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 ad units.

Recommendation widget code

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 embed code 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 embed code 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. Make sure the code does not get modified during copying. The Copy button is the best way to copy the code.

Editing

You can change your widget's settings at any time after the initial setup. Simply find your widget in the list in Ads on websites → 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). The CPM floor 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 floor, you can potentially filter out all ads and lose remuneration. Do not set a floor if you aren't sure what you're supposed to do.

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 Ads on websites → 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. In this case, you'll get a response saying noItemsForWidget. 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 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 Yandex Advertising Network 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 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.

Contact support

Write to WhatsApp Go to WhatsApp

Write to chat

Send an email



You can also go to



Useful links



Previous
Getting your website ready
Next
Design customization
In this article: