Implementation Guide

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

Important: Review the individual terms of your contract before using this code on your site.

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

Step 1: Customize page and ad unit options using the CSA Code Generator

The code generator makes it easy to customize the look, feel, and behavior of your ads. First configure page-level options. These options apply to all of the ad units on your page. Next, configure options for individual ad units. These settings configure the look and feel (colors, font size, etc) for individual ad units on the page.

Key Parameters:

Name Parameter Description
Client-ID pubId This should be a valid client-ID. Your pubId is the part of your client-ID that comes after 'partner-'. For example, if your client-ID is 'partner-test-property', your pubId is 'test-property'. This is standard protocol for CSA.
Query query This should be dynamic based on your page. This variable targets the ads and therefore should always match what the user on your site has just performed a search for.

Note: We recommend that you enable all extensions in order to take advantage of the optimizations AFS has to offer.

Step 2: Configure additonal page and unit level options

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.

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.

Asynchronous Ad Loading Example (Recommended)

The CSA code generator outputs asynchronous code. A full working example of asynchronous ad loading is shown below. You may open this example in new tab here. 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'
};

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>

Partial-Asynchronous Ad Loading Example

This feature provides partial-asynchronous ad loading in CSA. This version of CSA will block during document.write in the ads.js script but all other calls are made asynchronously. The ads.js call should be placed in the page header for best results. The div for the first ad block must be opened and closed immediately before the script tag that requires that div.

Note: Full asynchronous ad loading is the recommended method of loading ads. Please contact your Technical Account Manager before launching partial-asynchronous ad loading to ensure that this implementation will work as intended. Code generated via the CSA code generator will not work with this implementation.

<html>
<head>

<script src="https://www.google.com/adsense/search/ads.js"></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'
};
var adblock1 = {
'container': 'afscontainer1',
'maxTop': 4,
'width': '400px'
};
var adblock2 = {
'container': 'afscontainer2',
'number': 4,
'width': '300px'
};

new google.ads.search.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>