Browse the documentation

Search Ads

Applies to: Publishers · needs the matching permission on your account

A Search Ads zone shows native ads for what visitors type into your own search box. As someone types "running shoes", the zone asks for ads that match that search and shows them as results, under your box or inside your existing suggestions list. It can also list the ads in the page itself, as search results under the box or in a spot you choose. Each result is labelled as an ad.

What this is#

Search Ads is an ad zone type built on native ads. It serves only Search Ads campaigns, which advertisers buy as their own ad type, and never regular native campaigns. It doesn't replace your search. Your search box, its form and its results page keep working as before. The zone listens to what is typed and, once enough characters are in, requests native ads for that search.

  • Search Ads campaigns that target a keyword in the search are picked for it, so the results are relevant to what the visitor is looking for. Search Ads campaigns without keywords fill any remaining places.
  • Some searches never get an ad. A built-in list blocks searches about minors, non-consent, violence and similar topics in many languages, including disguised spellings. That list is always on. You can add your own words and phrases on top.
  • Each search is recorded in your stats as the zone's sid1, so you can see which searches earn.

If Search Ads is not in the Type list when you create a zone, it has not been switched on for your network yet. Ask your account manager.

When you'll use this#

  • Your site has a search box that gets real use, and you want to earn from that moment of intent.
  • You already show search suggestions and want a sponsored result between them.
  • Your site has no search box yet. The zone can draw one for you.
  • You want the ads listed in the page like search results, not in a box that floats over it.

Set it up#

  1. Create a zone of type Search Ads under Ad Zones.
  2. On the zone's Settings tab, fill in:
    • Where the ads show:
      • Own dropdown under the search box: the zone opens its own box under your input with the ads and the visitor's recent searches. Use this when your site has no suggestions of its own.
      • Inside the site's existing suggestions panel: the ads go into a placement you put inside your current suggestions list. Fill in the Suggestions panel selector so ads are only requested while that panel is open.
      • We draw the search box, with the ads under it: the zone puts a search box on your page itself and opens the same dropdown under it. Fill in Text in the empty box and, if searches should go to your own results page, Your search page, for example https://yoursite.com/search?q={q}. {q} is replaced by what the visitor typed. Leave it empty and the box only shows ads and recent searches.
      • A results list in the page, under the search box or in your own div: the ads are listed in the page itself, like search results, instead of in a dropdown that floats over it. They appear right under the search box, or in a div you put where you want them, for example in your content column. The list updates as the visitor types and when they press Enter, and stays when they click elsewhere. Leave Search box selector empty and the zone draws the box; fill it in to use your own. If the page address carries a search, for example /search?q=shoes, it is filled in and the ads are listed on load; Search parameter in the page address is its name (q, or s for /?s=shoes).
    • Search box selector (not for the drawn box; optional for the results list): a CSS selector that matches exactly one search input on your page, such as #header-search.
    • How each ad looks: an ad card with image, title, description and link, or a search suggestion, one line with a small image and the title, so the ad reads like one of the suggestions, or a search result: the label and link on top, the title, the full description and a small image, so the ad reads like one of your own results. Use the search result look with the results list.
    • Ads per search, Characters before ads show, and the Ad label text.
    • Extra blocked terms: words or phrases that should never get an ad on your site.
  3. Open the zone's Code tab and copy the code. The search box selector and the other settings are already filled in.
  4. Put the code on your page after the ad controller tag:
    • Own dropdown: paste the script anywhere, for example just before </body>. There is no div to place.
    • Existing suggestions: put the div inside your suggestions panel, after your own suggestions. For a ul or ol list, change the div into an li. Paste the script once.
    • Results list: put the box div (or keep your own search box) where the search box should appear. The ads are listed right under it. To list them somewhere else, add the div from the comment in the code there. Paste the script once.
    • Drawn search box: put the div where the box should appear, for example in your header. The box fills the width of the div up to 480px. Paste the script anywhere after the controller tag.

Keep your search form and its input name exactly as they are. With the own dropdown, also set autocomplete="off" on the input so the browser's saved suggestions don't cover the ads. The zone code does this for you once it loads.

Changing the layout#

The results use the same templates as a native zone: tpl_body, tpl_row and tpl_item. Inside tpl_item, {image}, {title}, {description} and {displayurl} are replaced for each ad. The element with the class {href_itemid} is what the visitor clicks. The default layout comes with gcs- class names (gcs-item, gcs-title, gcs-label, …) that you can restyle from your own CSS. Keep the ad label visible.

The drawn search box uses gcs-box, gcs-box-input and gcs-box-btn. Its width and corner radius follow the CSS variables --gcs-box-width and --gcs-box-radius, and the colours follow the Dropdown colours setting.

Tips#

  • One zone per search box. A header box and a separate mobile box need two zones. One box that is only restyled for mobile needs one.
  • If your search box is added to the page later, for example by a single-page app, the zone waits for it. If you replace the box with a new one, call goCtrl.search.refresh(<zone id>) afterwards, using the controller name from your code.
  • With the own dropdown, a search that runs without a form submit (an instant-results page, say) can still be added to the visitor's recent searches with goCtrl.search.remember(<zone id>, "the search").
  • goCtrl.search.query(<zone id>, "a search") puts a search into the box from your own code and shows the ads for it, for example when your page runs a search without a reload.
  • To control when your suggestions panel counts as open, call goCtrl.search.setOpen(<zone id>, true) and false yourself.

Troubleshooting#

  • Nothing shows up. Check that the Search box selector matches exactly one input. Then check the search is at least as long as Characters before ads show. Also check that the controller tag is on the page before the zone code.
  • Ads show for some searches and not others. Either the search is on the blocked list, or no campaign had an ad for it at that moment. Blocked searches never get an ad and never appear in your stats.
  • The dropdown sits in the wrong place. It is positioned under the input when it opens, and again on scroll and resize. If your header is fixed or animates, use the existing-suggestions mode instead and place the div yourself.