Implementation Guide

Note: Only ever make one ad request per page no matter how many blocks may be present.

Important: Read the Terms and Conditions before using this code

To use this code you must have an AdSense account with active permission to use AdSense Custom Search Ads.

Overview

Implementing AdSense Custom Search Ads on your site is a 3 step process:

Step 1: Create your custom search style in AdSense

After signing in, expand Ads for search then click Search styles. From here you can create a new style or update an existing one.

Step 2: Configure the code

Click Get Code Embed. Configure your ad containers to match the ad containers on your search page.

Step 3: Implement the code

Copy the code from the code generator and paste it on your page, remembering to update the query parameter. The code generated in the head tag should be placed in the head tag on your site for the ads to load properly. The code for ad unit 1 will contain the settings for all ad units on the page. Additional ad units will only require placing the corresponding ad unit <div> on the page where ads should appear.

The most commonly used features are supplied in the code generator, but some additional parameters are available in the reference section. The reference section contains all page level options, which apply to all ad units on the page, as well as all unit level options, which apply to individual ad units.

Sample code

Asynchronous ad loading

The generated code is asynchronous. A full working example of asynchronous ad loading is shown below. You may open this example in new tab. Remember to put your own client-Id.

<html>
<head>

<script async="async" src="https://www.google.com/adsense/search/ads.js"></script>

<script type="text/javascript" charset="utf-8">
  (function(g,o){g[o]=g[o]||function(){(g[o]['q']=g[o]['q']||[]).push(
  arguments)},g[o]['t']=1*new Date})(window,'_googCsa');
</script>

</head>

<body>

<div id="afscontainer1"></div>
<script type="text/javascript" charset="utf-8">

var pageOptions = {
  'pubId' : 'test client ID', // Enter your own client-ID here
  'query' : 'flowers', // User query for this page
  'styleId': '7824176615' // Enter your own style ID here
};

var adblock1 = {
  'container' : 'afscontainer1',
  'width' : 700
};

var adblock2 = {
  'container' : 'afscontainer2',
  'width' : 700
};

_googCsa('ads', pageOptions, adblock1, adblock2);
</script>

<p>Search result 1</p>
<p>Search result 2</p>
<p>Search result 3</p>

<div id="afscontainer2"></div>
</body>
</html>

Related Search on Search is an organic unit with search terms related to the current search term. Links on this unit go to a new search result page.

<html>
<head>

<script async="async" src="https://www.google.com/adsense/search/ads.js"></script>

<script type="text/javascript" charset="utf-8">
  (function(g,o){g[o]=g[o]||function(){(g[o]['q']=g[o]['q']||[]).push(
  arguments)},g[o]['t']=1*new Date})(window,'_googCsa');
</script>

</head>

<body>

<div id="afscontainer1"></div>
<script type="text/javascript" charset="utf-8">

var pageOptions = {
  'pubId': 'test client ID', // Enter your own client-ID here
  'relatedSearchTargeting': 'query', // Must use 'query' for Related Search on Search pages
  'query': 'flowers', // User query for this page
  'styleId': '1234567890', // Enter your own style ID here
  'resultsPageBaseUrl': '//www.example.com/search', // Enter your own base URL here
  'resultsPageQueryParam': 'query' // Enter your own query parameter here
};

var adblock = {
  'container': 'afscontainer1',
  'number': 3,
  'width': 700
};

var rsblock = {
  'container': 'afscontainer2',
  'relatedSearches': 6,
  'width': 500
};

_googCsa('ads', pageOptions, adblock, rsblock);
</script>

<p>Search result 1</p>
<p>Search result 2</p>
<p>Search result 3</p>

<div id="afscontainer2"></div>
</body>
</html>

Related Search on Content provides search terms for the user related to the content of the page. This enables users to explore relevant topics, engaging with search ads or site navigation. Don't use the 'query' parameter for Related Search on Content Pages as it will cause unexpected results.

Note: Before related search terms can appear on your site, Google needs to crawl your pages to ensure the terms are contextually relevant. When a page has not yet been crawled or is blocked from crawling (eg. by a robots.txt) by the AdSense crawler, we will not show suggested Related Search terms you provide to Google.

The Related Search on Content product relies on Google's content crawling system to index pages and generate relevant search terms. Content page URLs containing query parameters such as tracking variables, user IDs, session IDs, or other dynamic identifiers can interfere with the crawler's ability to assess the page's core content and may lead to inaccurate or irrelevant related search terms. Please use the 'ignoredPageParams' parameter to identify these nonessential parameters, ensuring proper content indexing and reducing unnecessary crawl load. This allows Google to better recognize a page as having already been crawled and start showing suggested terms (both Google and the partner's, if eligible).

<html>
<head>

<script async="async" src="https://www.google.com/adsense/search/ads.js"></script>

<script type="text/javascript" charset="utf-8">
  (function(g,o){g[o]=g[o]||function(){(g[o]['q']=g[o]['q']||[]).push(
  arguments)},g[o]['t']=1*new Date})(window,'_googCsa');
</script>

</head>

<body>

<p>Page content</p>

<div id="afscontainer1"></div>

<script type="text/javascript" charset="utf-8">

var pageOptions = {
  'pubId': 'test client ID', // Enter your own client-ID here
  'relatedSearchTargeting': 'content', // Must use 'content' for Related Search on Content pages
  'hl': 'en', // The preferred language for related terms (default to 'en' if not specified)
  'styleId': '1234567890', // Enter your style ID
  'resultsPageBaseUrl': '//www.example.com/search', // Enter the base URL of your results page
  'resultsPageQueryParam': 'query', // Specify the query parameter on your results page
  'terms': 'term a,term b', // Optionally provide your own related terms in a comma-delimited list
  'referrerAdCreative': 'example ad title' // Only used when a user clicked an ad to arrive here;
                                           // required when 'terms' is present.
};

var rsblock1 = {
  'container': 'afscontainer1',
  'relatedSearches': 6
};

_googCsa('relatedsearch', pageOptions, rsblock1);
</script>

<p>More page content</p>

</body>
</html>

Things to Avoid

We advise that all publishers adhere to our guidelines for implementing AdSense Custom Search Ads, and avoid certain implementation methods that might interfere with ads rendering and cause unexpected results or suboptimal performance.

  • Don't make multiple ad calls from a page unless for an infinite scroll implementation
  • Don’t hide ad blocks either before or after ads are rendered
  • Don’t move ad blocks around the page
  • Don’t request more ad blocks than you want to show on the page
  • Don’t manipulate the DOM of the ad blocks
  • Don’t implement your own lazy-loading (rely on Google’s lazy-loading instead)
  • Don’t cache Google’s JS resources on your site
  • Don't use the 'query' parameter for Related Search on Content Pages as it will cause unexpected results.