The new Safari 8. as well as Google Chrome. can automatically install your site as a search provider when users visit. Safari Mobile 8 can automatically install your site after the visitor has performed one search on the site. Safari calls this feature Quick Website Search and here’s how you enable the feature for your website.
OpenSearch
Safari 8 for Mac uses the OpenSearch standard to power its automated search provider installations. This standard is also used by Google Chrome to provide a similar feature. The drop-down box that lets you choose a search provider in Firefox will include an entry for installing the current site when it’s detected as an OpenSearch provider.
Auto-discovery
For a site to be recognized as a search provider it must announce itself as an OpenSearch provider. This is done using a small XML file which is referenced from a link element in the head section of an HTML page.
<head> …
<link rel="search"
type="application/opensearchdescription+xml"
href="https://example.com/osd.xml"
title="Example website" />
</head>The important bits in the above example are the rel and type properties. These identify the referenced resource as an OpenSearch description document. The title attribute is used by Firefox before the search provider is installed.
OpenSearch description document
<?xml version="1.0"?>
<!-- SPDX-License-Identifier: CC0-1.0 -->
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
<ShortName>Example website</ShortName>
<Description>Search Example website’s extensive archive of articles on Example topics.</Description>
<Image width="16"
height="16"
type="image/x-icon">https://example.com/favicon.ico</Image>
<Url method="get"
rel="results"
type="text/html"
template="https://example.com/search?query={searchTerms}&client=osd" />
<Url rel="self"
type="application/opensearchdescription+xml"
template="https://example.com/osd.xml" />
<Language>en</Language>
<InputEncoding>UTF-8</InputEncoding>
</OpenSearchDescription>The format is pretty self-explanatory. The search path is discovered from the Url element where {searchTerms} will be replaced by a URL encoded search string provided by the user. Both GET and POST methods will work. However, there’s wider support for the GET method in clients. Consider offering both GET and POST if you prefer POST.
Safari and Google Chrome use the domain’s associated favicon instead of the Image data in the OpenSearch description document. Firefox uses the domain’s favicon for the installation prompt but switches to the OpenSearch description document’s Image data after installing. I would recommend providing a 16×16 and 32×32 favicon in the conventional /favicon.ico location and as the OpenSearch description document’s Image to make it more maintainable and keep the resources reusable/cachable.
It can be a good idea to include a parameter to the search path to help track that searches originated from an OpenSearch client. In the example code, I added “&client=osd” as a query parameter to illustrate this.
The rel=self Link is used by Firefox to periodically auto-update the search provider.
Drive-by installation protection
There are some measures to ensure that malicious parties and advertisers can’t inject a search provider when the user visits a random page. These measures include:
- User must be on a path-less request, e.g.
https://www.example.com/ - Must be in the main frame (no framesets, iframes, objects, or fragments)
The keywords are derived automatically by the domain name. There’s still the risk of unexpected results after users visit the map service here.com once followed by a search for “here be dragons”. (Uncharted territories? Get it? Get it?)
The OSD file is retrieved by a special User-Agent:
com.apple.Safari.SearchHelper/11601.1.37 CFNetwork/750.2 Darwin/15.0.0 (x86_64)
Fallback for OpenSearch
Only 4 % of the web’s most popular websites offers OpenSearch as of July 2014, according to BuiltWith. While you want to ensure that your website offers it, Safari needed a fallback when sites don’t offer it.
Unlike the Mac version, Safari Mobile doesn’t auto-install the search provider when visiting a site’s front-page. Nor does it use the OpenSearch description document method outlined above for Safari. Users are required to perform a search on the site by submitting a recognizable search form. A small but detrimental oversight in this policy.
<form method="get" action="https://www.example.com/search">
<input type="search" name="query">
<input type="button" value="Search">
</form>The form must have only one visible input controller, and it should be of type “search”. There’s more too it than that, however any standard and one-controller search form will just work.
This method is also used by Safari for Mac when the site doesn’t offer an OpenSearch description document, or when the user performs a search on the site without ever visiting the front page. (Note that Safari for Mac will try to use a site’s OpenSearch description document to enhance the installed search provider even when initially installed using the fallback method.)
Going the extra mile
Browsers and other OpenSearch clients can enforce a same-origin security policy for OpenSearch providers. All resources such as the search path and OpenSearch description document path should be on the same domain as your main site. When possible, its good practice to provide the search path over HTTPS to protect the visitor’s privacy.
Google Chrome can also use search-suggestions when included in the OpenSearch description document. Refer to Chromium’s documentation for details.
The Safari specific information in this post is updated as of Safari 8 on Mac OS X 10.10 Public Beta and iOS 8 Developer Beta 4.