API Programmable Search Element Control

É possível incorporar componentes do Mecanismo de Pesquisa Programável (caixas e páginas de resultados da pesquisa) em suas páginas e outros aplicativos da Web usando marcação HTML. Esses Mecanismos de Pesquisa Programável Os elementos consistem em componentes que são renderizados com base nas configurações armazenadas pelo do servidor de Pesquisa Programável, além de todas as personalizações que você fizer.

Todo o JavaScript é carregado de forma assíncrona, o que permite que sua página da Web continua carregando enquanto o navegador busca o JavaScript do Mecanismo de Pesquisa Programável.

Introdução

Este documento mostra um modelo básico para adicionar o Mecanismo de Pesquisa Programável elementos à sua página da Web, além de explicações sobre o comportamento componentes configuráveis e uma API JavaScript flexível.

Escopo

Este documento descreve como usar as funções e propriedades específicas do a API Programmable Search Engine Control.

Compatibilidade do navegador

A lista de navegadores compatíveis com o Mecanismo de Pesquisa Programável está disponível aqui.

Público

Esta documentação é destinada aos desenvolvedores que querem adicionar recursos programáveis do Google a funcionalidade de pesquisa nas páginas.

Elementos da Pesquisa Programável

Use a marcação HTML para adicionar um Elemento de pesquisa programável à sua página. Cada consiste em pelo menos um componente: uma caixa de pesquisa, um bloco de pesquisa resultados ou ambos. A caixa de pesquisa aceita a entrada do usuário em qualquer um dos seguintes maneiras:

• Uma consulta de pesquisa digitada no campo de entrada de texto
• Uma string de consulta incorporada em um URL
• Execução programática

Além disso, o bloco de resultados da pesquisa aceita entradas no da seguinte maneira:

• Uma string de consulta incorporada em um URL
• Execução programática

Os seguintes tipos de Elementos da Pesquisa programável estão disponíveis:

É possível adicionar um número ilimitado de elementos de pesquisa válidos à página da Web. Para colunas todos os componentes necessários (uma caixa de pesquisa e bloco de resultados) precisam estar presentes.

Veja um exemplo de um Elemento de pesquisa simples:

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

Criar diferentes opções de layout usando elementos da Pesquisa programável

As opções de layout a seguir estão disponíveis na página "Aparência" do painel de controle do Mecanismo de Pesquisa Programável. Confira algumas diretrizes gerais sobre como escrever opções de layout usando os Elementos de Pesquisa Programável. Para ver uma demonstração de qualquer uma dessas opções, clique no link.

Mais informações sobre as opções de layout.

Como personalizar elementos da Pesquisa programável

Para personalizar as cores, a fonte ou o estilo dos links, acesse a página "Aparência" do mecanismo de pesquisa programável.

É possível usar atributos opcionais para substituir configurações criadas no Mecanismo de Pesquisa Programável painel de controle. Isso permite que você crie uma experiência de pesquisa específica para a página. Por exemplo, o código a seguir cria uma caixa de pesquisa que abre uma página de resultados (http://www.example.com?search=lady+gaga) em uma nova janela. O valor do parâmetro O atributo queryParameterName, junto com a string de consulta do usuário, estão usada para criar o URL dos resultados.

O atributo queryParameterName tem o prefixo data-. Esse prefixo é obrigatório para todos os atributos.

<div class="gcse-searchbox-only" data-resultsUrl="http://www.example.com" data-newWindow="true" data-queryParameterName="search">

Se você usou o painel de controle do Mecanismo de Pesquisa Programável para ativar recursos como preenchimento automático ou refinamentos, é possível usar atributos para e personalizar esses recursos. Qualquer personalização especificada usando esses atributos substitui as configurações feitas no painel de controle. O exemplo a seguir cria um Elemento de pesquisa de duas colunas com os seguintes recursos:

• O gerenciamento de histórico está ativado
• O número máximo de opções de preenchimento automático exibidas está definido como 5
• Os refinamentos são exibidos como links.

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

Atributos compatíveis

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

Callbacks

Os callbacks permitem um controle detalhado da inicialização do elemento de pesquisa e dos processos de pesquisa. Eles são registrados com o elemento de pesquisa JavaScript por meio do __gcse global objeto. Register Callbacks ilustra o registro de todos os os callbacks compatíveis.

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

O callback de inicialização

O callback de inicialização é invocado antes que o JavaScript do elemento de pesquisa renderize a pesquisa. elementos no DOM. Se parsetags estiver definido como explicit em __gcse, o JavaScript do Elemento de pesquisa deixa a renderização dos elementos de pesquisa para o retorno de chamada de inicialização (como mostrado em Registrar callbacks). Isso pode ser usado para selecionar elementos a serem renderizados ou para adiar elementos de renderização até que eles sejam necessários. Ele também pode substituir os atributos dos elementos. por exemplo, ela pode transformar caixa de pesquisa configurada por meio do Painel de controle ou de atributos HTML para padronizar para a web pesquisar em uma caixa de pesquisa de imagens ou especificar que as consultas enviadas por um formulário do Mecanismo de Pesquisa Programável são executada em um elemento somente searchresults. Veja uma demonstração.

A função do callback de inicialização é controlada pelo valor de parsetags propriedade de __gcse.

• Se o valor for onload, o elemento de pesquisa O JavaScript renderiza todos os elementos de pesquisa da página automaticamente. O callback de inicialização é ainda invocado, mas não é responsável pela renderização dos elementos de pesquisa.
• Se o valor for explicit, o JavaScript do elemento de pesquisa não será renderizado. Elementos de pesquisa. O callback pode renderizá-los seletivamente usando o função render(), ou renderizar todos os elementos da pesquisa com a função go()

O código a seguir demonstra como exibir uma caixa de pesquisa, junto com os resultados da pesquisa, em um div, usando a parsetag explicit e o callback de inicialização:

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

Pesquisar retornos de chamada

O JavaScript do Elemento de pesquisa suporta seis callbacks que operam no fluxo de controle de pesquisa. Os callbacks de pesquisa vêm em pares, um callback de pesquisa na Web e um callback de pesquisa de imagem correspondente:

• Início da pesquisa
  • Para pesquisa de imagens
  • Para pesquisa na Web
• Resultados prontos
  • Para pesquisa de imagens
  • Para pesquisa na Web
• Resultados renderizados
  • Para pesquisa de imagens
  • Para pesquisa na Web

Assim como o callback de inicialização,os callbacks de pesquisa são configurado usando entradas no objeto __gcse. Isso acontece, porque o Elemento de pesquisa O JavaScript é iniciado. Modificações em __gcse após a inicialização são ignoradas.

Cada um desses callbacks recebe o gName para o elemento de pesquisa como um argumento. O gname é útil quando uma página contém mais de uma pesquisa. Faça uma pesquisa um elemento gname com valores usando o atributo data-gname:

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

Se o HTML não identificar o gname, o JavaScript do Elemento de pesquisa gerará um valor que será permanecem consistentes até que o HTML seja modificado.

Callback de inicialização da pesquisa de imagem/na Web

Os callbacks iniciais da pesquisa são invocados imediatamente antes das solicitações JavaScript do elemento de pesquisa. resultados de pesquisa do seu servidor. Um exemplo de caso de uso seria usar a hora local do dia para controlar as mudanças feitas na consulta.

searchStartingCallback(gname, query)

gname

String de identificação do elemento de pesquisa

query

valor inserido pelo usuário (possivelmente modificado pela pesquisa JavaScript.

O callback retorna o valor que deve ser usado como a consulta para essa pesquisa. Se ele retornar um string vazia, o valor de retorno é ignorado e o autor da chamada usa a consulta não modificada.

Como alternativa, coloque a função de callback no objeto __gcse ou adicione dinamicamente o callback ao objeto com JavaScript:

window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};

Exemplo de callback inicial da pesquisa

O exemplo de pesquisa que inicia o callback em Exemplo de retorno de chamada de inicialização de pesquisa adiciona morning. ou afternoon à consulta, dependendo da hora do dia.

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

Instale este callback em 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>

Callback pronto para resultados da pesquisa na Web/de imagem

Esses callbacks são invocados imediatamente antes que o JavaScript do elemento de pesquisa processe promoções e resultados. Um exemplo de caso de uso seria um callback que renderiza promoções e resulta em um estilo que não pode ser especificado com a personalização normal.

resultsReadyCallback(gname, query, promos, results, div)

gname

String de identificação do elemento de pesquisa

query

consulta que produziu esses resultados

promos

uma matriz de objetos de promoção, que correspondem aos promotions para o a consulta do usuário. Veja a definição do objeto de promoção.

results

uma matriz de objetos de resultado. Consulte a definição do objeto resultante.

div

um div HTML posicionado no DOM onde o elemento de pesquisa normalmente promoções de lugares e resultados de pesquisa. Normalmente, o JavaScript do elemento de pesquisa lida preenchendo o div. No entanto, esse callback poderá interromper a renderização automática dos resultados. e usar esse div para renderizar os resultados.

.

Se esse callback retornar um valor true, o JavaScript do elemento de pesquisa vai pular para o e o rodapé da página funcionam.

Exemplo de callback de resultados prontos

O exemplo de callback resultsReady em O Exemplo de chamada de retorno de resultados prontos substitui a apresentação padrão de promoções e resultados com uma substituição muito simples.

    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>

Callback renderizado nos resultados da pesquisa da Web/de imagem

Esses callbacks são invocados imediatamente antes que o JavaScript do elemento de pesquisa renderize a página. rodapé. Exemplos de casos de uso incluem um callback que adiciona o conteúdo do resultado que a pesquisa não exibe, como uma caixa de seleção salvar isto ou informações que não estão renderizados automaticamente ou um callback que adicione botões para mais informações.

Se um callback renderizado de resultados precisar de informações que estavam no promos e results do callback Ready de resultados, ele pode transmiti-los entre eles, desta forma:

callback(gname, query, promoElts, resultElts);

gname

String de identificação do elemento de pesquisa

query

string de pesquisa.

promoElts

uma matriz dos elementos DOM que contém promoções.

resultElts

: uma matriz de elementos DOM contendo resultados.

Não há valor de retorno.

Exemplo de callback renderizado de resultados

O exemplo de callback resultsRendered em Example Results Rendered Callback adiciona um Keep (link em inglês) fictício caixa de seleção a cada promoção e resultado.

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>

Se o callback renderizado dos resultados precisar informações que foram transmitidas para o callback pronto para resultados, ele pode transmitir esses dados entre os callbacks. O exemplo a seguir mostra uma das várias maneiras de transmitir um valor de avaliação de richSnippet do callback pronto para resultados até os resultados renderizados .

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>

Mais exemplos de callback

Outros exemplos de callback podem ser encontrados na Documento Mais exemplos de callback.

Propriedades da promoção e do resultado

Usando a notação JSDoc, essas são as propriedades do objetos promotion e result. Aqui, listamos todas as propriedades que podem estar presentes. A presença de muitas das propriedades dependem dos detalhes da promoção ou do resultado da pesquisa.

{
  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 em results tem o tipo livre de uma matriz de objetos. Os valores das entradas nessa matriz são controlados pelo dados estruturados encontrados na página da Web para cada resultado de pesquisa. Por exemplo, um site de resenhas pode incluir dados estruturados que adicionam essa entrada de matriz a richSnippet:

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

API Programmable Search Element Control (V2)

O objeto google.search.cse.element publica o seguinte funções estáticas:

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