API Programmable Search Element Control

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

Todo o JavaScript é carregado de forma assíncrona, o que permite que a página da Web continue sendo carregada enquanto o navegador busca o JavaScript do Mecanismo de Pesquisa Programável.

Introdução

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

Escopo

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

Compatibilidade com navegadores

A lista de navegadores compatíveis com o Mecanismo de Pesquisa Programável pode ser encontrada aqui.

Público

Esta documentação é destinada a desenvolvedores que querem adicionar a funcionalidade da Pesquisa Programável do Google às páginas deles.

Elementos da Pesquisa programável

Você pode usar a marcação HTML para adicionar um Programmable Search Element à sua página. Cada elemento consiste em pelo menos um componente: uma caixa de pesquisa, um bloco de resultados da pesquisa ou ambos. A caixa de pesquisa aceita entradas do usuário de qualquer uma das 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 das seguintes maneiras:

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

Os seguintes tipos de elementos de pesquisa programável estão disponíveis:

Você pode adicionar quantos elementos de pesquisa válidos quiser à sua página da Web. No modo de duas colunas, todos os componentes necessários (uma caixa de pesquisa e um bloco de resultados da pesquisa) precisam estar presentes.

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

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

As seguintes opções de layout 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 criar opções de layout usando 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.

Personalizar elementos da Pesquisa programável

Para personalizar cores, fontes ou estilo de link, acesse a página "Aparência" do seu mecanismo de pesquisa programável.

Você pode usar atributos opcionais para substituir as configurações criadas no painel de controle do Mecanismo de Pesquisa Programável. Isso permite criar uma experiência de pesquisa específica para cada 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 atributo queryParameterName, junto com a string de consulta do usuário, é usado para criar o URL de 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, use atributos para personalizar esses recursos. As personalizações especificadas usando esses atributos substituem 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 do histórico está ativado
• O número máximo de preenchimentos automáticos mostrados é definido como 5
• Os refinamentos são mostrados 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 oferecem suporte ao controle detalhado da inicialização e dos processos de pesquisa de elementos de pesquisa. Eles são registrados com o JavaScript do elemento de pesquisa pelo objeto global __gcse. Registrar retornos de chamada ilustra o registro de todos os retornos de chamada 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 os elementos de pesquisa no DOM. Se parsetags estiver definido como explicit em __gcse, o JavaScript do elemento de pesquisa deixará a renderização dos elementos de pesquisa para o callback de inicialização (conforme mostrado em Registrar callbacks). Isso pode ser usado para selecionar elementos a serem renderizados ou para adiar a renderização até que sejam necessários. Ele também pode substituir os atributos dos elementos. Por exemplo, pode transformar uma caixa de pesquisa configurada pelo painel de controle ou por atributos HTML para a pesquisa na Web padrão em uma caixa de pesquisa de imagens ou especificar que as consultas enviadas por um formulário do Mecanismo de Pesquisa Programável sejam executadas em um elemento somente de resultados da pesquisa. Confira uma demonstração.

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

• Se o valor for onload, o JavaScript do elemento de pesquisa renderizará todos os elementos de pesquisa na página automaticamente. O callback de inicialização ainda é invocado, mas não é responsável por renderizar os elementos de pesquisa.
• Se o valor for explicit, o JavaScript do elemento de pesquisa não vai renderizar elementos de pesquisa. O callback pode renderizar os elementos de forma seletiva usando a função render() ou renderizar todos os elementos de pesquisa com a função go().

O código a seguir demonstra como renderizar uma caixa de pesquisa, junto com os resultados da pesquisa, em um div, usando a tag de análise 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>

Callbacks de pesquisa

O JavaScript do elemento de pesquisa oferece suporte a seis retornos de chamada 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 imagens correspondente:

• Pesquisa em andamento
  • 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 configurados usando entradas no objeto __gcse. Isso acontece quando o JavaScript do elemento de pesquisa é iniciado. As modificações em __gcse após a inicialização são ignoradas.

Cada um desses callbacks recebe o gName do elemento de pesquisa como um argumento. O gname é útil quando uma página contém mais de uma pesquisa. Atribua a um elemento de pesquisa valores gname 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 vai gerar um valor que vai permanecer consistente até que o HTML seja modificado.

Callback de início da pesquisa de imagens/na Web

Os callbacks de início da pesquisa são invocados imediatamente antes de o JavaScript do elemento de pesquisa solicitar resultados da pesquisa do servidor. Um exemplo de caso de uso seria usar a hora local do dia para controlar mudanças na consulta.

searchStartingCallback(gname, query)

gname

String de identificação do elemento de pesquisa

query

Valor

inserido pelo usuário (possivelmente modificado pelo JavaScript do elemento de pesquisa).

O callback retorna o valor que deve ser usado como consulta para essa pesquisa. Se ela retornar uma string vazia, o valor de retorno será ignorado e o autor da chamada usará a consulta sem modificações.

Outra opção é colocar a função de callback no objeto __gcse ou adicionar dinamicamente o callback ao objeto com JavaScript:

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

Exemplo de callback de início de pesquisa

O exemplo de callback de início de pesquisa em Exemplo de callback de início 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 esse 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 de imagens/na Web

Esses callbacks são invocados imediatamente antes de o JavaScript do elemento de pesquisa renderizar promoções e resultados. Um exemplo de caso de uso seria um callback que renderiza promoções e resultados 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 gerou esses resultados

promos

uma matriz de objetos de promoção, que correspondem às promoções correspondentes à consulta do usuário. Consulte a definição do objeto de promoção.

results

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

div

uma div HTML posicionada no DOM em que o elemento de pesquisa normalmente coloca promoções e resultados da pesquisa. Normalmente, o JavaScript do elemento de pesquisa processa o preenchimento dessa div, mas o callback pode interromper a renderização automática de resultados e usar esse div para renderizar os resultados por conta própria.

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

Exemplo de callback de resultados prontos

O exemplo de callback resultsReady em Exemplo de callback de resultados prontos substitui a apresentação padrão de promoções e resultados por 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 de resultados da pesquisa de imagens/na Web

Esses callbacks são invocados imediatamente antes de o JavaScript do elemento de pesquisa renderizar o rodapé da página. Exemplos de casos de uso incluem um callback que adiciona conteúdo de resultado que o elemento de pesquisa não mostra, como uma caixa de seleção Salvar ou informações que não são renderizadas automaticamente, ou um callback que adiciona botões Mais informações.

Se um callback de resultados renderizados precisar de informações que estavam nos parâmetros promos e results do callback de resultados prontos, ele poderá transmitir essas informações entre eles, assim:

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 dos elementos DOM que contêm resultados.

Não há valor de retorno.

Exemplo de callback de renderização de resultados

O callback de exemplo resultsRendered em Exemplo de callback de renderização de resultados adiciona uma caixa de seleção Manter fictícia 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 de resultados renderizados precisar de informações transmitidas ao callback de resultados prontos, ele poderá transmitir esses dados entre os callbacks. O exemplo a seguir mostra uma das várias maneiras de transmitir um valor de classificação de richSnippet do callback de resultados prontos para o callback de 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>

Exemplo de callback de renderização de resultados: abrir tipos de arquivos específicos em uma nova guia/janela

O exemplo de callback a seguir pode modificar os links de resultados da pesquisa depois que eles são renderizados para abrir um arquivo específico em uma nova guia/página em vez da janela atual (por exemplo: PDF, Excel ou Word). Isso melhora a experiência de navegação quando os usuários não querem abrir um arquivo na mesma janela e sair da página de resultados.

Este exemplo de callback identifica links de PDF nos resultados da pesquisa e define o atributo target="_blank" nesses links para que eles sejam abertos em uma nova guia. Um MutationObserver é usado para processar dinamicamente novos resultados se a página for atualizada. Observação:você pode substituir .pdf em handleSearchResults por qualquer outro tipo de arquivo, de acordo com sua necessidade.

Este exemplo de callback não funciona em layouts hospedados e de sobreposição do Google.

function handleSearchResults() {
  const links = document.querySelectorAll('.gsc-results .gs-title');
  links.forEach(link => {
    const url = link.href;
    if (url?.toLowerCase().endsWith('.pdf')) {
      link.setAttribute('target', '_blank');
    }
  });
}

const myWebResultsRenderedCallback = () => {
  // Call handleSearchResults when results are rendered
  handleSearchResults();
  // Set up a MutationObserver to handle subsequent updates to the results
  const observer = new MutationObserver(handleSearchResults);
  const searchResultsContainer = document.querySelector('.gsc-results');
  if (searchResultsContainer) {
    observer.observe(searchResultsContainer, {
      childList: true,
      subtree: true
    });
  } else {
    console.log('No Results.');
  }
};

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>

Mais exemplos de callback

Outros exemplos de callback podem ser encontrados no documento Mais exemplos de callback.

Propriedades de promoção e resultado

Usando a notação JSDoc, estas são as propriedades dos objetos promotion e result. Aqui, listamos todas as propriedades que podem estar presentes. A presença de muitas das propriedades depende 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 solto de uma matriz de objetos. Os valores das entradas nessa matriz são controlados pelos dados estruturados encontrados na página da Web de cada resultado da pesquisa. Por exemplo, um site de avaliações pode incluir dados estruturados que adicionam esta entrada de matriz a richSnippet:

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

API Programmable Search Element Control (V2)

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

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