Advanced Search Reporting Service /click Protocol

Advanced search reporting enables administrators to see what types of links a user chooses on a search results page, and more generally to track all actions that a user performs such as clicking navigational links. This information enables administrators to improve access and latency of search results, and to understand user click behavior. This document contains reference information about request parameters and the information logged by the search appliance about user click behavior.

An administrator enables advanced search reporting in the Admin Console’s Search > Search Features > Front Ends > Output Format page. The search appliance then modifies search result pages by inserting JavaScript on the page for tracking all links that a user clicks. When a user clicks a link in the search results, the JavaScript executes in the browser, requesting a URL from the search appliance. The URL starts with /click and contains information about the link. The arguments given in the URL are logged on the search appliance, and the search appliance returns a response to the browser. The browser then retrieves the URL on which the user clicked.

The /click URL is not visible to users. This URL has little effect on user-perceived latency because the processing is performed on the client side, and both the request and response are as minimal as possible.

This document enables advanced administrators to understand the /click URL information that is sent to the search appliance. Administrators who monitor network data may see this information. Programmers can also use this information in custom applications.

For information about configuring advanced search reporting in the Admin Console, see Gathering Information about the Search Experience in Creating the Search Experience. For information on search requests, Request Format.

The following describes how an advanced search reporting request is handled by the search appliance.

Back to top

Request Parameters

Advanced search reporting requires the site parameter. Ensure that you include &site=collection in request URLs, where collection is the collection being queried.

The end user does not see a /click URL. If an administrator uses a program such as tcpdump to view data on the Internet connection, the /click information is visible. Administrators or programmers can use this information for debugging or in an application. The parameters in the /click URL are as follows.

 

URL Parameter	Description	Example
cd	Click data. This is additional, user-provided information to give more information or context about the click. This is not interpreted by the search appliance and is just logged. This would typically only be used by people who perform advanced customization and need to log additional information.	cd=malta
ct	Required parameter. Click type. A value that identifies the type of link that a user clicks. For the value, use underscores or a dot without spaces and use alpha-numeric characters. For a complete list of click types, see Click Types in Advanced Search Reports in Creating the Search Experience. This is an extensible field. You can add your own values to this parameter. We recommend that you do not use any values that Google has already defined. We recommend that you use a sequence containing alpha-numeric characters, underscores, hyphens, and periods.	ct=c
q	Query text	q=island+countries
r	Rank of the result on which the user clicks.	r=7
s	Specifies the index number of the first entry in the result set.	s=24
url	URL that the user clicked.	url=http%3A//www.foo.com/
site	Required parameter. If this parameter does not have a valid value, other parameters in the query string do not work as expected. Limits search results to the contents of the specified collection. You can search multiple collections by separating collection names with the OR character, which is notated as the pipe symbol, or the AND character, which is notated as a period. For more information about the site parameter, see site.	&site=collection

The following is an example request for advanced search reporting parameters:

/click?ct=desk.news&r=7&url=http%3A//www.foo.com/bar.html&q=olympics&site=default_collection

The request URL contains the following parameters:

 

Value	Description
/click	Start of the advanced search reporting URL.
ct=desk.news	User clicked the News link at the top of the search page.
r=7	The rank priority of the click is 7.
url=http%3A//www.foo.com/bar.html	The URL on which the user clicked.
q=olympics	The search query the user entered that created the search page.
site=default_collection	The collection that is searched.

When a user clicks a cluster label the following example appears:

ct=cluster&cd=spanish+cuisine&q=spain&site=default_collection

This URL contains the following information:

 

Value	Description
ct=cluster	User clicked a cluster label on the search page.
cd=spain+cuisine	The click data identifies the click for “spain cuisine.”
url=http%3A//www.foo.com/bar.html	The URL on which the user clicked.
q=spain	The search query the user entered that created the search page.
site=default_collection	The collection that is searched.

Back to top

Responses

In response to the /click URL, the search appliance always sends the same HTTP response back to the browser to acknowledge receipt. The response has a status code of 204 (no content) and a MIME type of image/gif.

The Google implementation running on the client generates a URL with JavaScript as a dummy image object. The result is ignored, because the response does not affect the client behavior. Its purpose is to log the user interactions on the server side.