HTML マークアップを使用して、プログラム可能検索エンジンのコンポーネント(検索ボックスと検索結果ページ)をウェブページやその他のウェブ アプリケーションに埋め込むことができます。これらのプログラム可能検索エンジンの要素は、プログラム可能検索サーバーによって保存された設定とユーザーによるカスタマイズに基づいてレンダリングされるコンポーネントで構成されます。
すべての JavaScript は非同期で読み込まれるため、ブラウザがプログラム可能検索エンジンの JavaScript を取得する間もウェブページの表示を続行できます。
はじめに
このドキュメントでは、プログラム可能検索エンジンの要素をウェブページに追加するための基本モデルについて説明し、要素の構成可能なコンポーネントと柔軟な JavaScript API について説明します。
範囲
このドキュメントでは、Programmable Search Engine Control API に固有の関数とプロパティの使用方法について説明します。
ブラウザの互換性
プログラム可能検索エンジンでサポートされているブラウザの一覧については、こちらをご覧ください。
視聴者
このドキュメントは、Google のプログラム可能な検索機能をページに追加するデベロッパーを対象としています。
プログラム可能な検索要素
HTML マークアップを使用して、プログラム可能検索要素をページに追加できます。各要素は少なくとも 1 つのコンポーネント(検索ボックス、検索結果のブロック、またはその両方)で構成されています。検索ボックスでは、次のいずれかの方法でユーザー入力を受け付けます。
- テキスト入力フィールドに入力された検索クエリ
- URL に埋め込まれたクエリ文字列
- プログラムによる実行
また、検索結果のブロックでは、次の方法で入力を受け入れます。
- URL に埋め込まれたクエリ文字列
- プログラムによる実行
以下の種類の Programmable Search 要素を使用できます。
要素の種類 | コンポーネント | 説明 |
---|---|---|
standard | <div class="gcse-search"> |
検索ボックスと検索結果が同じ <div> に表示されます。 |
2 列 | <div class="gcse-searchbox"> と <div class="gcse-searchresults"> |
片側に検索結果、もう片側に検索ボックスがある 2 列レイアウト。ウェブページに 2 列モードで複数の要素を挿入する場合は、gname 属性を使用して検索ボックスと検索結果ブロックをペア設定できます。 |
検索ボックスのみ | <div class="gcse-searchbox-only"> |
スタンドアロンの検索ボックス。 |
検索結果のみ | <div class="gcse-searchresults-only"> |
検索結果のスタンドアロン ブロック。 |
ウェブページには有効な検索要素をいくつでも追加できます。2 列モードの場合は、必要なコンポーネント(検索ボックスと検索結果ブロック)がすべて存在している必要があります。
単純な検索要素の例を次に示します。
<!-- Put the following javascript before the closing </head> tag and replace 123456 with your own Programmable Search Engine ID. --> <script async src="https://cse.google.com/cse.js?cx=123456"></script> <!-- Place this tag where you want both of the search box and the search results to render --> <div class="gcse-search"></div>
プログラム可能な検索要素を使用してさまざまなレイアウト オプションを作成する
プログラム可能検索エンジンのコントロール パネルの [デザイン] ページでは、次のレイアウト オプションを使用できます。プログラム可能な検索要素を使用してレイアウト オプションを作成する際の一般的なガイドラインは次のとおりです。これらのオプションのデモを見るには、リンクをクリックしてください。
オプション | コンポーネント |
---|---|
全幅 | <div class="gcse-search"> |
コンパクト | <div class="gcse-search"> |
2 列 | <div class="gcse-searchbox"> 、<div class="gcse-searchresults"> |
2 ページ | 1 ページ目は <div class="gcse-searchbox-only"> 、2 ページ目は <div class="gcse-searchresults-only"> (または他のコンポーネント)です。 |
結果のみ | <div class="gcse-searchresults-only"> |
Google がホストする | <div class="gcse-searchbox-only"> |
プログラム可能な検索要素のカスタマイズ
色、フォント、リンク スタイルをカスタマイズするには、プログラム可能検索エンジンの [デザイン] ページに移動します。
オプションの属性を使用すると、プログラム可能検索エンジンのコントロール パネルで作成した構成を上書きできます。これにより、ページ固有の検索エクスペリエンスを実現できます。たとえば、次のコードは、検索結果ページ(http://www.example.com?search=lady+gaga)を新しいウィンドウで開く検索ボックスを作成します。queryParameterName
属性の値とユーザーのクエリ文字列は、結果 URL を作成するために使用されます。
queryParameterName
属性には data-
という接頭辞が付くことに注意してください。この接頭辞はすべての属性で必須です。
<div class="gcse-searchbox-only" data-resultsUrl="http://www.example.com" data-newWindow="true" data-queryParameterName="search">
プログラム可能検索エンジンのコントロール パネルを使用してオートコンプリートや絞り込みなどの機能を有効にした場合は、属性を使用してこれらの機能をカスタマイズできます。これらの属性を使用して指定したカスタマイズは、コントロール パネルで行った設定をオーバーライドします。次の例では、次の特徴を持つ 2 列の検索要素を作成します。
- 履歴管理が有効
- 表示されるオートコンプリートの最大数は 5 に設定されています
- 絞り込みはリンクとして表示されます。
<div class="gcse-searchbox" data-enableHistory="true" data-autoCompleteMaxCompletions="5"> <div class="gcse-searchresults" data-refinementStyle="link">
サポートされている属性
属性 | タイプ | 説明 | コンポーネント |
---|---|---|---|
全般 | |||
gname |
文字列 | (省略可)検索要素オブジェクトの名前。名前は、関連するコンポーネントを名前で取得したり、searchbox コンポーネントと searchresults コンポーネントをペアにする場合に使用されます。指定しなかった場合、プログラム可能検索エンジンは、ウェブページ上のコンポーネントの順序に基づいて、gname を自動的に生成します。たとえば、1 つ目の名前のない searchbox-only には gname 「searchbox-only0」があり、2 つ目は gname 「seachbox-only1」です。2 列レイアウトのコンポーネントに対して自動生成される gname は two-column です。次の例では、gname storesearch を使用して searchbox コンポーネントを searchresults コンポーネントにリンクしています。
<div class="gcse-searchbox" data-gname="storesearch"></div> <div class="gcse-searchresults" data-gname="storesearch"></div> オブジェクトを取得する際に、複数のコンポーネントが同じ |
すべて |
autoSearchOnLoad |
ブール値 | 読み込み中のページの URL に埋め込まれたクエリで検索を実行するかどうかを指定します。自動検索を実行するには、URL にクエリ文字列が存在している必要があります。デフォルト | すべて |
enableHistory |
ブール値 | true の場合、ブラウザの戻るボタンと進むボタンの履歴管理を有効にします。デモを見る |
searchbox 検索ボックスのみ |
queryParameterName |
文字列 | クエリ パラメータ名(例: q (デフォルト)、query )。URL に埋め込まれます(例: http://www.example.com?q=lady+gaga)。クエリ パラメータ名のみを指定しても、読み込み時の自動検索はトリガーされません。自動検索を実行するには、URL にクエリ文字列が含まれている必要があります。 |
すべて |
resultsUrl |
URL | 検索結果ページの URL です。(デフォルトは Google がホストするページです)。 | 検索ボックスのみ |
newWindow |
ブール値 | 検索結果ページを新しいウィンドウで開くかどうかを指定します。 デフォルト | 検索ボックスのみ |
ivt |
ブール値 |
このパラメータを使用すると、同意済みのトラフィックと同意のないトラフィックの両方で、無効なトラフィックのみの Cookie とローカル ストレージを使用する広告を許可することを Google に通知するブール値を指定できます。
デフォルト: 使用例: |
検索結果 検索結果のみ |
mobileLayout |
文字列 |
モバイル デバイスでモバイル レイアウト スタイルを使用するかどうかを指定します。
デフォルト: 使用例: |
すべて |
オートコンプリート | |||
enableAutoComplete |
ブール値 | プログラム可能検索エンジンのコントロール パネルでオートコンプリートが有効になっている場合にのみ使用できます。
true は、オートコンプリートを有効にします。 |
すべて |
autoCompleteMaxCompletions |
Integer | 表示するオートコンプリートの最大数。 | searchbox 検索ボックスのみ |
autoCompleteMaxPromotions |
Integer | オートコンプリートに表示されるプロモーションの最大数。 | searchbox 検索ボックスのみ |
autoCompleteValidLanguages |
文字列 | オートコンプリートを有効にする言語のカンマ区切りリスト。 サポートされている言語。 | searchbox 検索ボックスのみ |
絞り込み | |||
defaultToRefinement |
文字列 | プログラム可能検索エンジンのコントロール パネルで絞り込みを作成している場合にのみ使用できます。表示するデフォルトの絞り込みラベルを指定します。注: この属性は Google がホストするレイアウトではサポートされていません。 | すべて |
refinementStyle |
文字列 | 有効な値は tab (デフォルト)と link です。link がサポートされるのは、画像検索が無効になっている場合、または画像検索を有効にしてもウェブ検索が無効になっている場合のみです。 |
検索結果 検索結果のみ |
画像検索 | |||
enableImageSearch |
ブール値 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。
|
検索結果 検索結果のみ |
defaultToImageSearch |
ブール値 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。
|
すべて |
imageSearchLayout |
文字列 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 画像検索結果ページのレイアウトを指定します。有効な値は |
検索結果 検索結果のみ |
imageSearchResultSetSize |
整数、文字列 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 画像検索の結果セットの最大サイズを指定します。例: |
すべて |
image_as_filetype |
文字列 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 結果を指定した拡張子のファイルに制限します。 サポートされている拡張機能は | すべて |
image_as_oq |
文字列 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 論理 OR を使用して検索結果をフィルタリングします。 「term1」または「term2」のいずれかを含む検索結果を取得する場合の使用例: | すべて |
image_as_rights |
文字列 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 ライセンスに基づくフィルタ。 サポートされている値は 一般的な組み合わせをご覧ください。 | すべて |
image_as_sitesearch |
文字列 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 検索結果を特定サイトのページに限定します。 使用例: | すべて |
image_colortype |
文字列 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 検索結果をモノクロ(モノラル)、グレースケール、またはカラーの画像に限定します。サポートされている値は | すべて |
image_cr |
文字列 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 検索結果を、特定の国で作成されたドキュメントに限定します。 | すべて |
image_dominantcolor |
文字列 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 検索を特定のドミナント カラーの画像に制限します。
サポートされている値は | すべて |
image_filter |
文字列 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 検索結果の自動フィルタリング。 サポートされている値: 0/1 使用例: | すべて |
image_gl |
文字列 | プログラム可能検索エンジンのコントロール パネルで 画像検索が有効になっている場合にのみ使用できます。元の国がパラメータ値と一致する検索結果をブーストします。 | すべて |
image_size |
文字列 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 指定されたサイズの画像を返します。サイズは | すべて |
image_sort_by |
文字列 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 日付または他の構造化コンテンツを使用して結果を並べ替えます。 関連性で並べ替えるには、空の文字列(image_sort_by=")を使用します。 使用例: | すべて |
image_type |
文字列 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 検索を特定のタイプの画像に制限します。
サポートされている値は、 | すべて |
ウェブ検索 | |||
disableWebSearch |
ブール値 | true の場合、ウェブ検索を無効にします。通常は、プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用されます。 |
検索結果 検索結果のみ |
webSearchQueryAddition |
文字列 | 論理 OR を使用して検索クエリに余分な語句を追加します。
使用例: |
すべて |
webSearchResultSetSize |
整数、文字列 | 結果セットの最大サイズ。画像検索とウェブ検索の両方に適用されます。デフォルトは、レイアウトと、プログラム可能検索エンジンの設定(ウェブ全体または指定したサイトのみ)によって異なります。有効な値は次のとおりです。
|
すべて |
webSearchSafesearch |
文字列 |
ウェブ検索の検索結果に対してSafeSearchを有効にするかどうかを指定します。指定できる値は off と active です。 |
すべて |
as_filetype |
文字列 | 結果を指定した拡張子のファイルに制限します。Google でインデックス登録可能なファイル形式の一覧については、Search Console ヘルプセンターをご覧ください。 | すべて |
as_oq |
文字列 | 論理 OR を使用して検索結果をフィルタリングします。
「term1」または「term2」を含む検索結果が必要な場合の使用例: |
すべて |
as_rights |
文字列 | ライセンスに基づくフィルタ。
サポートされている値は 一般的な組み合わせについては、https://wiki.creativecommons.org/wiki/CC_Search_integration をご覧ください。 | すべて |
as_sitesearch |
文字列 | 検索結果を特定のサイトのページに限定します。
使用例: |
すべて |
cr |
文字列 | 検索結果を、特定の国で作成されたドキュメントに限定します。
使用例: |
すべて |
filter |
文字列 | 検索結果の自動フィルタリング。
サポートされている値: 0/1 使用例: |
すべて |
gl |
文字列 | 元の国がパラメータ値と一致する検索結果をブーストします。 これは、言語の値の設定と組み合わせた場合にのみ機能します。 使用例: |
すべて |
lr |
文字列 | 検索結果を特定の言語のドキュメントのみに限定します。 使用例: |
すべて |
sort_by |
文字列 | 日付または他の構造化コンテンツを使用して結果を並べ替えます。属性値には、プログラム可能検索 egnine の [結果の並べ替え] 設定で指定されているオプションのいずれかを指定する必要があります。 関連性で並べ替えるには、空の文字列(sort_by=")を使用します。 使用例: |
すべて |
検索結果 | |||
enableOrderBy |
ブール値 | 検索結果を関連度、日付、ラベルで並べ替えることができます。 | すべて |
linkTarget |
文字列 | リンク ターゲットを設定します。デフォルト | 検索結果 検索結果のみ |
noResultsString |
文字列 | クエリに一致する結果がない場合に表示するデフォルトのテキストを指定します。デフォルトの結果文字列を使用すると、サポートされているすべての言語でローカライズされた文字列を表示できますが、カスタマイズされた文字列は表示されません。 | 検索結果 検索結果のみ |
resultSetSize |
整数、文字列 | 結果セットの最大サイズ。例: large 、small 、filtered_cse 、10 デフォルトは、レイアウトと、エンジンの設定(ウェブ全体を検索するか、指定したサイトのみを検索するか)によって異なります。 |
すべて |
safeSearch |
文字列 | ウェブ検索と画像検索の両方で
セーフサーチを有効にするかどうかを指定します。指定できる値は off と active です。 |
すべて |
コールバック
コールバックは、検索要素の初期化プロセスと検索プロセスの詳細な制御をサポートします。これらは、グローバル __gcse
オブジェクトを通じて検索要素 JavaScript に登録されます。コールバックの登録では、サポートされているすべてのコールバックの登録を示しています。
初期化コールバック
初期化コールバックは、検索要素 JavaScript が DOM の検索要素をレンダリングする前に呼び出されます。__gcse
で parsetags
が explicit
に設定されている場合、検索要素の JavaScript は、検索要素のレンダリングを初期化コールバックに残します(コールバックを登録するを参照)。これを使用して、レンダリングする要素を選択したり、必要になるまでレンダリング要素を延期したりできます。また、要素の属性をオーバーライドすることもできます。たとえば、コントロール パネルまたは HTML 属性で構成された検索ボックスをデフォルトでウェブ検索に変えたり、プログラム可能検索エンジンのフォームを介して送信されたクエリが検索結果のみの要素で実行されるように指定したりできます。
デモをご覧ください。
初期化コールバックのロールは、__gcse
の parsetags
プロパティの値によって制御されます。
- 値が
onload
の場合、検索要素 JavaScript はページ上のすべての検索要素を自動的にレンダリングします。初期化コールバックは引き続き呼び出されますが、検索要素のレンダリングは行われません。 - 値が
explicit
の場合、検索要素の JavaScript は検索要素をレンダリングしません。コールバックでは、render()
関数を使用して要素を選択的にレンダリングするか、go()
関数を使用してすべての検索要素をレンダリングできます。
次のコードは、explicit
パースタグと初期化コールバックを使用して、div
で検索ボックスを検索結果とともにレンダリングする方法を示しています。
検索コールバック
検索要素 JavaScript は、検索制御フローで動作する 6 つのコールバックをサポートしています。検索コールバックには、ウェブ検索コールバックとそれに対応する画像検索コールバックのペアがあります。
- 検索開始中
- 画像検索用
- ウェブ検索用
- 結果あり
- 画像検索用
- ウェブ検索用
- レンダリングされた結果
- 画像検索用
- ウェブ検索用
初期化コールバックと同様に、検索コールバックは __gcse
オブジェクト内のエントリを使用して構成されます。この処理は、検索要素の JavaScript が開始すると行われます。起動後に __gcse
を変更しても無視されます。
これらの各コールバックには、検索要素の gName
が引数として渡されます。gname
は、1 つのページに複数の検索が含まれている場合に役立ちます。data-gname
属性を使用して、検索要素に gname
値を指定します。
<div class="gcse-searchbox" data-gname="storesearch"></div>
HTML で gname が識別されない場合、検索要素の JavaScript は、HTML が変更されるまで一貫した値を生成します。
画像/ウェブ検索 - 開始コールバック
検索開始コールバックは、検索要素 JavaScript がサーバーに検索結果をリクエストする直前に呼び出されます。ユースケースの一例として、現地時刻を使用してクエリの変更を制御することが挙げられます。
searchStartingCallback(gname, query)
gname
- 検索要素の識別文字列
query
- ユーザーが入力した値(検索要素の JavaScript によって変更される場合があります)。
このコールバックは、この検索のクエリとして使用される値を返します。空の文字列を返した場合、その戻り値は無視され、呼び出し元は変更されていないクエリを使用します。
あるいは、コールバック関数を __gcse
オブジェクトに配置するか、JavaScript を使用してオブジェクトにコールバックを動的に追加することもできます。
window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};
検索開始コールバックの例
検索開始コールバックの例の検索開始コールバックの例では、時間帯に応じて morning
または afternoon
をクエリに追加します。
このコールバックを window.__gcse:
にインストールする
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
image: {
starting: 'myImageSearchStartingCallbackName',
},
web: {
starting: myWebSearchStartingCallback,
},
};
<script
async src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>
画像/ウェブ検索結果の準備完了コールバック
これらのコールバックは、検索要素の JavaScript がプロモーションと結果をレンダリングする直前に呼び出されます。ユースケースの一例として、プロモーションをレンダリングして通常のカスタマイズでは指定できないスタイルにするコールバックがあります。
resultsReadyCallback(gname, query, promos, results, div)
gname
- 検索要素の識別文字列
query
- これらの結果を生成したクエリ
promos
- プロモーション オブジェクトの配列。ユーザーのクエリで一致したプロモーションに対応します。プロモーション オブジェクトの定義をご覧ください。
results
- 結果オブジェクトの配列。結果オブジェクトの定義をご覧ください。
div
- 通常、検索要素がプロモーションや検索結果を配置する DOM 内に配置される HTML div。通常、検索要素の JavaScript はこの div の入力を処理しますが、このコールバックは結果の自動レンダリングを停止し、この
div
を使用して結果自体をレンダリングすることもできます。
このコールバックが true
値を返す場合、検索要素の JavaScript はページフッターの処理までスキップします。
結果準備完了コールバックの例
結果準備コールバックの例にある resultsReady
コールバックの例は、プロモーションと結果のデフォルト表示を非常にシンプルな置き換えでオーバーライドしています。
画像/ウェブ検索結果 - レンダリング済みコールバック
これらのコールバックは、検索要素の JavaScript がページフッターをレンダリングする直前に呼び出されます。ユースケースの例としては、[Save this] チェックボックスや自動的にレンダリングされない情報など、検索要素で表示されない結果コンテンツを追加するコールバックや、[for more information] ボタンを追加するコールバックがあります。
結果レンダリングのコールバックに、結果準備完了コールバックの promos
パラメータと results
パラメータに含まれていた情報が必要な場合は、次のようにそれらの間で渡すことができます。
callback(gname, query, promoElts, resultElts);
gname
- 検索要素の識別文字列
query
- 検索文字列。
promoElts
- プロモーションを含む DOM 要素の配列。
resultElts
- 結果を格納する DOM 要素の配列。
戻り値はありません。
レンダリングされたコールバックの結果の例
レンダリングされた結果コールバックの例にある resultsRendered
コールバックの例では、各プロモーションと結果にダミーの Keep チェックボックスを追加します。
結果レンダリング完了コールバックに渡された情報を必要とする場合、コールバック間でそのデータを渡すことができます。次の例は、richSnippet
から結果準備完了コールバックから結果レンダリング コールバックに評価値を渡す多くの方法の 1 つです。
コールバックのその他の例
その他のコールバックの例は、その他のコールバックの例に記載されています。
プロモーションと検索結果のプロパティ
JSDoc 表記法を使用すると、これらは promotion オブジェクトと result オブジェクトのプロパティになります。ここでは、含まれる可能性のあるすべてのプロパティを列挙しています。宿泊施設の多くが表示されるかどうかは、プロモーションや検索結果の詳細によって異なります。
結果の richSnippet
は、オブジェクトの配列のルーズ型です。この配列のエントリの値は、各検索結果のウェブページにある構造化データによって制御されています。たとえば、レビューのウェブサイトには、この配列エントリを richSnippet
に追加する構造化データが含まれている場合があります。
'review': { 'ratingstars': '3.0', 'ratingcount': '1024', },
Programmable Search Element Control API(V2)
google.search.cse.element
オブジェクトは、次の静的関数を公開します。
機能 | 説明 | ||||||
---|---|---|---|---|---|---|---|
.render(componentConfig, opt_componentConfig) |
検索要素をレンダリングします。
パラメータ
|
||||||
.go(opt_container) |
指定されたコンテナ内のすべての検索要素タグまたはクラスをレンダリングします。
パラメータ
|
||||||
.getElement(gname) |
gname で要素オブジェクトを取得します。見つからなかった場合は、null を返します。
返される
次のコードは、検索要素「element1」でクエリ「news」を実行します。 var element = google.search.cse.element.getElement('element1'); element.execute('news'); |
||||||
.getAllElements() |
gname をキーとして、正常に作成されたすべての要素オブジェクトのマップを返します。 |