API управления программируемым поисковым элементом

Вы можете встраивать компоненты программируемой поисковой системы (поля поиска и страницы результатов поиска) в свои веб-страницы и другие веб-приложения с помощью разметки HTML. Эти элементы программируемой поисковой системы состоят из компонентов, которые отображаются на основе настроек, хранящихся на сервере программируемого поиска, а также любых внесенных вами настроек.

Весь код JavaScript загружается асинхронно, что позволяет вашей веб-странице продолжать загрузку, пока браузер получает код JavaScript программируемой поисковой системы.

Введение

В этом документе представлена ​​базовая модель добавления элементов программируемой поисковой системы на вашу веб-страницу, а также пояснения настраиваемых компонентов элемента и гибкого API JavaScript.

Объем

В этом документе описывается, как использовать функции и свойства, специфичные для API управления программируемой поисковой системой.

Совместимость с браузером

Список браузеров, поддерживаемых Программируемой поисковой системой, можно найти здесь .

Аудитория

Эта документация предназначена для разработчиков, желающих добавить на свои страницы функции программируемого поиска Google.

Программируемые поисковые элементы

Вы можете использовать HTML-разметку, чтобы добавить на свою страницу элемент программируемого поиска. Каждый элемент состоит как минимум из одного компонента: поля поиска, блока результатов поиска или того и другого. Поле поиска принимает вводимые пользователем данные любым из следующих способов:

• Поисковый запрос, введенный в поле ввода текста
• Строка запроса, встроенная в URL-адрес.
• Программное исполнение

Кроме того, блок результатов поиска принимает ввод следующими способами:

• Строка запроса, встроенная в URL-адрес.
• Программное исполнение

Доступны следующие типы программируемых поисковых элементов:

Вы можете добавить на свою веб-страницу любое количество действительных элементов поиска. Для двухколоночного режима должны присутствовать все необходимые компоненты (поле поиска и блок результатов поиска).

Вот пример простого элемента поиска:

<!-- 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>

Создавайте различные варианты макета, используя программируемые элементы поиска.

Следующие параметры макета доступны на странице «Внешний вид» панели управления Программируемой поисковой системы. Ниже приведены некоторые общие рекомендации по составлению вариантов макета с использованием программируемых элементов поиска. Чтобы просмотреть демо-версию любого из этих вариантов, щелкните ссылку.

Подробнее о вариантах планировки.

Настройка программируемых поисковых элементов

Чтобы настроить цвета, шрифт или стиль ссылки, перейдите на страницу «Внешний вид» вашей программируемой поисковой системы.

Вы можете использовать дополнительные атрибуты для перезаписи конфигураций, созданных на панели управления Программируемой поисковой системы . Это позволяет вам создать опыт поиска для конкретной страницы. Например, следующий код создает окно поиска, которое открывает страницу результатов (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">

Если вы использовали панель управления Программируемой поисковой системы для включения таких функций, как автозаполнение или уточнения , вы можете использовать атрибуты для настройки этих функций. Любые настройки, которые вы указываете с помощью этих атрибутов, переопределяют настройки, выполненные на панели управления. В следующем примере создается элемент поиска с двумя столбцами и следующими функциями:

• Управление историей включено
• Максимальное количество отображаемых автозаполнений установлено на 5.
• Уточнения отображаются в виде ссылок.

<div class="gcse-searchbox" data-enableHistory="true" data-autoCompleteMaxCompletions="5">
<div class="gcse-searchresults" data-refinementStyle="link">

Поддерживаемые атрибуты

<div class="gcse-searchbox" data-gname="storesearch"></div>
<div class="gcse-searchresults" data-gname="storesearch"></div>

Обратные вызовы

Обратные вызовы поддерживают детальный контроль над инициализацией поисковых элементов и процессами поиска. Они регистрируются в JavaScript элемента поиска через глобальный объект __gcse . Регистрация обратных вызовов иллюстрирует регистрацию всех поддерживаемых обратных вызовов.

  window.__gcse = {
    parsetags: 'explicit', // Defaults to 'onload'
    initializationCallback: myInitializationCallback,
    searchCallbacks: {
      image: {
        starting: myImageSearchStartingCallback,
        ready: myImageResultsReadyCallback,
        rendered: myImageResultsRenderedCallback,
      },
      web: {
        starting: myWebSearchStartingCallback,
        ready: myWebResultsReadyCallback,
        rendered: myWebResultsRenderedCallback,
      },
    },
  };
  

Обратный вызов инициализации

Обратный вызов инициализации вызывается до того, как JavaScript элемента поиска отобразит элементы поиска в DOM. Если в __gcse для parsetags установлено explicit , JavaScript элемента поиска оставляет рендеринг элементов поиска обратному вызову инициализации (как показано в разделе «Регистрация обратных вызовов »). Это можно использовать для выбора элементов для рендеринга или для отсрочки рендеринга элементов до тех пор, пока они не потребуются. Он также может переопределять атрибуты элементов; например, он может превратить окно поиска, настроенное с помощью панели управления или атрибутов HTML по умолчанию для веб-поиска, в окно поиска изображений или указать, что запросы, отправленные через форму программируемой поисковой системы, выполняются в элементе только для результатов поиска. Посмотрите демо.

Роль обратного вызова инициализации контролируется значением свойства parsetags __gcse .

• Если его значение — onload , JavaScript элемента поиска автоматически отображает все элементы поиска на странице. Обратный вызов инициализации по-прежнему вызывается, но он не отвечает за отображение элементов поиска.
• Если его значение explicit , JavaScript элемента поиска не отображает элементы поиска. Обратный вызов может отображать их выборочно с помощью функции render() или отображать все элементы поиска с помощью функции go()

Следующий код демонстрирует, как визуализировать поле поиска вместе с результатами поиска в div с использованием explicit тега синтаксического анализа и обратного вызова инициализации:

    <div id="test"></div>

const myInitCallback = function() {
  if (document.readyState == 'complete') {
    // Document is ready when Search Element is initialized.
    // Render an element with both search box and search results in div with id 'test'.
    google.search.cse.element.render(
        {
          div: "test",
          tag: 'search'
         });
  } else {
    // Document is not ready yet, when Search Element is initialized.
    google.setOnLoadCallback(function() {
       // Render an element with both search box and search results in div with id 'test'.
        google.search.cse.element.render(
            {
              div: "test",
              tag: 'search'
            });
    }, true);
  }
};

// Insert it before the Search Element code snippet so the global properties like parsetags and callback
// are available when cse.js runs.
window.__gcse = {
  parsetags: 'explicit',
  initializationCallback: myInitCallback
};

<script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>

Поиск обратных вызовов

JavaScript элемента поиска поддерживает шесть обратных вызовов, которые работают в потоке управления поиском. Обратные вызовы поиска выполняются парами: обратный вызов веб-поиска и соответствующий обратный вызов поиска изображений:

• Поиск начинается
  • Для поиска изображений
  • Для веб-поиска
• Результаты готовы
  • Для поиска изображений
  • Для веб-поиска
• Полученные результаты
  • Для поиска изображений
  • Для веб-поиска

Как и обратный вызов инициализации, обратные вызовы поиска настраиваются с использованием записей в объекте __gcse . Это происходит при запуске JavaScript элемента поиска. Изменения в __gcse после запуска игнорируются.

Каждому из этих обратных вызовов в качестве аргумента передается gName для элемента поиска. gname полезно, когда страница содержит более одного поиска. Присвойте элементу поиска значения gname используя атрибут data-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 в зависимости от времени суток.

    const myWebSearchStartingCallback = (gname, query) => {
      const hour = new Date().getHours();
      return query + (hour < 12 ? ' morning' : ' afternoon');
    };
    window.myImageSearchStartingCallbackName = myWebSearchStartingCallback;

Установите этот обратный вызов в 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

HTML-элемент div, расположенный в DOM, где элемент поиска обычно размещает рекламные акции и результаты поиска. Обычно JavaScript элемента поиска обрабатывает заполнение этого div, но этот обратный вызов может остановить автоматическую визуализацию результатов и использовать этот div для самой визуализации результатов.

Если этот обратный вызов возвращает true значение, JavaScript элемента поиска переходит к работе с нижним колонтитулом страницы.

Пример обратного вызова готовых результатов

Пример обратного вызова resultsReady в примере обратного вызова Results Ready переопределяет представление рекламных акций и результатов по умолчанию с помощью очень простой замены.

    const myResultsReadyCallback = function(name, q, promos, results, resultsDiv) {
      const makePromoElt = (promo) => {
        const anchor = document.createElement('a');
        anchor.href = promo['url'];
        anchor.target = '_blank';
        anchor.classList.add('gs-title');
        const span = document.createElement('span');
        span.innerHTML = 'Promo: ' + promo['title'];
        anchor.appendChild(span);
        return anchor;
      };
      const makeResultParts = (result) => {
        const anchor = document.createElement('a');
        anchor.href = result['url'];
        anchor.target = '_blank';
        anchor.classList.add('gs_title');
        anchor.appendChild(document.createTextNode(result['visibleUrl']));
        const span = document.createElement('span');
        span.innerHTML = ' ' + result['title'];
        return [anchor, span];
      };

      const table = document.createElement('table');
      if (promos) {
        for (const promo of promos) {
          const row = table.insertRow(-1);
          const cell = row.insertCell(-1);
          cell.appendChild(makePromoElt(promo));
        }
        resultsDiv.appendChild(table);
        resultsDiv.appendChild(document.createElement('br'));
      }
      if (results) {
        const table = document.createElement('table');
        for (const result of results) {
          const row = table.insertRow(-1);
          const cell = row.insertCell(-1);
          const [anchor, span] = makeResultParts(result);
          cell.appendChild(anchor);
          const cell2 = row.insertCell(-1);
          cell2.appendChild(span);
        }
        resultsDiv.appendChild(table);
      }
      return true;
    };

  window.__gcse || (window.__gcse = {});
    window.__gcse.searchCallbacks = {
      web: {
        ready: myResultsReadyCallback,
      },
    };

  <script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

Обратный вызов, отображаемый в результатах изображения/веб-поиска

Эти обратные вызовы вызываются непосредственно перед тем, как JavaScript элемента поиска отображает нижний колонтитул страницы. Примеры вариантов использования могут включать обратный вызов, который добавляет содержимое результата, которое элемент поиска не отображает, например, флажок «Сохранить этот флажок» или информацию, которая не отображается автоматически, или обратный вызов, который добавляет кнопки для получения дополнительной информации .

Если обратному вызову, отображаемому с результатами, требуется информация, которая была в параметрах promos и results обратного вызова с готовыми результатами results он может передать ее между ними, например:

callback(gname, query, promoElts, resultElts);

gname

Идентифицирующая строка элемента поиска

query

строка поиска.

promoElts

массив элементов DOM, содержащих рекламные акции.

resultElts

массив элементов DOM, содержащих результаты.

Возвращаемого значения нет.

Пример результатов, отображаемых обратного вызова

В примере обратного вызова resultsRendered в разделе «Пример результатов Rendered Callback» добавляется фиктивный флажок « Сохранить » для каждого продвижения и результата.

myWebResultsRenderedCallback = function(name, q, promos, results) {
    for (const div of promos.concat(results)) {
      const innerDiv = document.createElement('div');
      innerDiv.appendChild(document.createTextNode('Keep: '));
      const checkBox = document.createElement('input');
      checkBox.type = 'checkbox';
      checkBox.name = 'save';
      innerDiv.appendChild(checkBox);
      div.insertAdjacentElement('afterbegin', innerDiv);
    }
  };

window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
    rendered: 'myWebResultsRenderedCallback',
  },
};

  <script async
    src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

Если обратному вызову, отображающему результаты, нужна информация, которая была передана обратному вызову готовности результатов, он может передавать эти данные между обратными вызовами. В следующем примере показан один из многих способов передачи значения рейтинга из richSnippet из обратного вызова готовности результатов в обратный обратный вызов для отображения результатов.

const makeTwoPartCallback = () => {
  let saveForRenderCallback;
  const readyCallback = (name, q, promos, results, resultsDiv) =>
  {
    saveForRenderCallback = [];
    for (const result of results) {
      const {
        richSnippet: {
          answer = []
        } = {},
      } = result;
      const firstAnswer = answer[0];
      if (firstAnswer) {
        const upVotes = firstAnswer['upvotecount'];
        if (upVotes) {
          saveForRenderCallback.push(
            {upvotes: parseInt(upVotes, 10)}
          );
          continue;
        }
      }
      saveForRenderCallback.push({});
    }
  };
  const renderedCallback = (name, q, promos, results) => {
    for (let i = 0; i < results.length; ++i) {
      const div = results[i];
      const votes = saveForRenderCallback[i]['upvotes'];
      if (votes) {
        const innerDiv = document.createElement('div');
        innerDiv.innerHTML = '<b>Upvotes: ' + votes + '</b>';
         div.insertAdjacentElement('afterbegin', innerDiv);
      }
    }
  };
  return {readyCallback, renderedCallback};
};

const {
  readyCallback: webResultsReadyCallback,
  renderedCallback: webResultsRenderedCallback,
} = makeTwoPartCallback();
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
    ready: webResultsReadyCallback,
    rendered: webResultsRenderedCallback,
  },
};

  <script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:kdroeu4mwju"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

Дополнительные примеры обратного вызова

Дополнительные примеры обратного вызова можно найти в документе «Дополнительные примеры обратного вызова» .

Свойства продвижения и результатов

Используя нотацию JSDoc , это свойства объектов продвижения и результатов . Здесь мы перечисляем все свойства, которые могут присутствовать. Наличие многих свойств зависит от деталей акции или результатов поиска.

{
  content: string,
  image: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  url: string,
  visibleUrl: string,
}

{
  content: string,
  contentNoFormatting: string,
  contextUrl: string, // For image search results only
  fileFormat: string,
  image: { // For image search reseults only
    height: number,
    url: string,
    width: number,
  },
  perResultLabels: !Array<{
    anchor: string,
    label: string,
    labelWithOp: string,
  }>,
  richSnippet: !Array<!Object>, // For web search results only
  thumbnailImage: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  titleNoFormatting: string,
  url: string,
  visibleUrl: string,
}

richSnippet в результатах имеет свободный тип массива объектов. Значения записей в этом массиве контролируются структурированными данными , найденными на веб-странице для каждого результата поиска. Например, веб-сайт с обзорами может включать структурированные данные, которые добавляют эту запись массива в richSnippet :

'review': {
  'ratingstars': '3.0',
  'ratingcount': '1024',
},

API управления программируемым поисковым элементом (V2)

Объект google.search.cse.element публикует следующие статические функции:

var element = google.search.cse.element.getElement('element1');
            element.execute('news');