API de Programmable Search Element Control

Puedes incorporar componentes del Motor de Búsqueda Programable (cuadros de búsqueda y páginas de resultados de búsqueda) en tus páginas web y otras aplicaciones web con lenguaje de marcado HTML. Estos elementos del Motor de Búsqueda Programable constan de componentes que se renderizan según la configuración almacenada por el servidor de Programmable Search, junto con las personalizaciones que realices.

Todo el código JavaScript se carga de forma asíncrona, lo que permite que tu página web siga cargándose mientras el navegador recupera el código JavaScript del Motor de Búsqueda Programable.

Introducción

En este documento, se proporciona un modelo básico para agregar elementos del Motor de Búsqueda Programable a tu página web, junto con explicaciones de los componentes configurables del elemento y la flexible API de JavaScript.

Alcance

En este documento, se describe cómo usar las funciones y propiedades específicas de la API de Programmable Search Engine Control.

Compatibilidad del navegador

Puedes encontrar la lista de navegadores compatibles con el Motor de Búsqueda Programable aquí.

Público

Esta documentación está dirigida a los desarrolladores que deseen agregar la funcionalidad de la Búsqueda Programable de Google a sus páginas.

Elementos de Búsqueda Programable

Puedes usar el lenguaje de marcado HTML para agregar un elemento de Búsqueda Programable a tu página. Cada elemento consta de, al menos, un componente: un cuadro de búsqueda, un bloque de resultados de la búsqueda o ambos. El cuadro de búsqueda acepta la entrada del usuario de cualquiera de las siguientes maneras:

• Una búsqueda escrita en el campo de entrada de texto
• Es una cadena de consulta integrada en una URL.
• Ejecución programática

Además, el bloque de resultados de la búsqueda acepta entradas de las siguientes maneras:

• Es una cadena de consulta integrada en una URL.
• Ejecución programática

Están disponibles los siguientes tipos de elementos de Búsqueda Programable:

Puedes agregar la cantidad que desees de elementos de búsqueda válidos a tu página web. En el modo de dos columnas, deben estar presentes todos los componentes requeridos (un cuadro de búsqueda y un bloque de resultados de búsqueda).

A continuación, se muestra un ejemplo de un elemento de búsqueda simple:

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

Cómo componer diferentes opciones de diseño con elementos de Búsqueda Programable

Las siguientes opciones de diseño están disponibles en la página Aspecto del panel de control del Motor de Búsqueda Programable. A continuación, se incluyen algunos lineamientos generales para componer opciones de diseño con elementos de Búsqueda programable. Para ver una demostración de cualquiera de estas opciones, haz clic en el vínculo.

Más información sobre las opciones de diseño.

Cómo personalizar elementos de la Búsqueda Programable

Para personalizar los colores, la fuente o el estilo de los vínculos, ve a la página Aspecto de tu motor de búsqueda programable.

Puedes usar atributos opcionales para anular las configuraciones creadas en el panel de control del Motor de Búsqueda Programable. Esto te permite crear una experiencia de búsqueda específica para la página. Por ejemplo, el siguiente código crea un cuadro de búsqueda que abre una página de resultados (http://www.example.com?search=lady+gaga) en una ventana nueva. El valor del atributo queryParameterName, junto con la cadena de consulta del usuario, se usa para crear la URL de los resultados.

Ten en cuenta que el atributo queryParameterName tiene el prefijo data-. Este prefijo es obligatorio para todos los atributos.

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

Si usaste el panel de control del Motor de Búsqueda Programable para habilitar funciones como autocompletar o refinamientos, puedes usar atributos para personalizar esas funciones. Cualquier personalización que especifiques con estos atributos anulará la configuración realizada en el panel de control. En el siguiente ejemplo, se crea un elemento de búsqueda de dos columnas con las siguientes características:

• La administración del historial está habilitada
• La cantidad máxima de autocompletados que se muestran está establecida en 5.
• Los refinamientos se muestran como vínculos.

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

Atributos admitidos

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

Devoluciones de llamada

Las devoluciones de llamada admiten el control detallado de los procesos de inicialización y búsqueda de elementos de búsqueda. Se registran con el JavaScript del Elemento de búsqueda a través del objeto global __gcse. Register Callbacks ilustra el registro de todas las devoluciones de llamada admitidas.

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

La devolución de llamada de inicialización

La devolución de llamada de inicialización se invoca antes de que el JavaScript del Elemento de búsqueda renderice elementos de búsqueda en el DOM. Si parsetags se establece en explicit en __gcse, el JavaScript del elemento de búsqueda deja la renderización de los elementos de búsqueda en la devolución de llamada de inicialización (como se muestra en Cómo registrar devoluciones de llamada). Esto se puede usar para seleccionar elementos que se renderizarán o para aplazar la renderización de elementos hasta que sean necesarios. También puede anular los atributos de los elementos. Por ejemplo, puede convertir un cuadro de búsqueda configurado a través del panel de control o los atributos HTML para que se establezca de forma predeterminada en la búsqueda web en un cuadro de búsqueda de imágenes, o bien especificar que las búsquedas enviadas a través de un formulario de motor de búsqueda programable se ejecuten en un elemento solo de resultados de búsqueda. Mira una demostración.

El rol de la devolución de llamada de inicialización se controla con el valor de la propiedad parsetags del objeto __gcse.

• Si su valor es onload, el JavaScript del Elemento de búsqueda renderiza automáticamente todos los Elementos de búsqueda en la página. Aún se invoca la devolución de llamada de inicialización, pero no es responsable de renderizar los Elementos de la Búsqueda.
• Si su valor es explicit, el JavaScript del Elemento de búsqueda no renderiza Elementos de búsqueda. La devolución de llamada puede renderizarlos de forma selectiva con la función render() o renderizar todos los elementos de búsqueda con la función go().

En el siguiente código, se muestra cómo renderizar un cuadro de búsqueda, junto con los resultados de la búsqueda, en un div, con la etiqueta de análisis explicit y la devolución de llamada de inicialización:

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

Devoluciones de llamada de búsqueda

El JavaScript del elemento de búsqueda admite seis devoluciones de llamada que operan en el flujo de control de búsqueda. Las devoluciones de llamada de búsqueda vienen en pares: una devolución de llamada de búsqueda web y una devolución de llamada de búsqueda de imágenes coincidente:

• Búsqueda en curso
  • Para la búsqueda de imágenes
  • Para la búsqueda web
• Los resultados están listos.
  • Para la búsqueda de imágenes
  • Para la búsqueda web
• Resultados renderizados
  • Para la búsqueda de imágenes
  • Para la búsqueda web

Al igual que la devolución de llamada de inicialización, las devoluciones de llamada de búsqueda se configuran con entradas en el objeto __gcse. Esto sucede cuando se inicia el código JavaScript del elemento de búsqueda. Se ignoran las modificaciones en __gcse después del inicio.

A cada una de estas devoluciones de llamada se le pasa el gName del Elemento de búsqueda como argumento. El gname es útil cuando una página contiene más de una búsqueda. Asigna valores de gname a un elemento de búsqueda con el atributo data-gname:

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

Si el código HTML no identifica el gname, el JavaScript del Elemento de búsqueda genera un valor que permanecerá coherente hasta que se modifique el código HTML.

Devolución de llamada de inicio de búsqueda de imágenes o en la Web

Las devoluciones de llamada de inicio de la búsqueda se invocan inmediatamente antes de que el elemento de búsqueda de JavaScript solicite resultados de la búsqueda a su servidor. Un ejemplo de caso de uso sería usar la hora local del día para controlar los cambios en la búsqueda.

searchStartingCallback(gname, query)

gname

Cadena de identificación del elemento de búsqueda

query

Valor de

ingresado por el usuario (es posible que se haya modificado con el elemento de búsqueda de JavaScript).

La devolución de llamada muestra el valor que se debe usar como la búsqueda para esta búsqueda. Si devuelve una cadena vacía, se ignora el valor devuelto y el llamador usa la búsqueda sin modificar.

También puedes colocar la función de devolución de llamada en el objeto __gcse o agregar la devolución de llamada al objeto de forma dinámica con JavaScript:

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

Ejemplo de devolución de llamada de inicio de la búsqueda

El ejemplo de devolución de llamada de inicio de búsqueda en Ejemplo de devolución de llamada de inicio de búsqueda agrega morning o afternoon a la búsqueda según la hora del día.

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

Instala esta devolución de llamada en 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>

Devolución de llamada que indica que los resultados de la búsqueda de imágenes o web están listos

Estas devoluciones de llamada se invocan inmediatamente antes de que el JavaScript del Elemento de búsqueda renderice las promociones y los resultados. Un ejemplo de caso de uso sería una devolución de llamada que renderiza promociones y resultados con un estilo que no se puede especificar con la personalización normal.

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

gname

Cadena de identificación del elemento de búsqueda

query

consulta que produjo estos resultados

promos

un array de objetos de promoción, que corresponden a las promociones que coinciden con la búsqueda del usuario. Consulta la definición del objeto promotion.

results

, un array de objetos de resultado. Consulta la definición del objeto result.

div

un elemento div de HTML ubicado en el DOM donde el Elemento de búsqueda normalmente colocaría promociones y resultados de la búsqueda Normalmente, el código JavaScript del Elemento de búsqueda se encargaría de completar este div, pero esta devolución de llamada puede optar por detener la renderización automática de los resultados y usar este div para renderizar los resultados por sí misma.

Si esta devolución de llamada muestra un valor de true, el JavaScript del Elemento de búsqueda se salta el trabajo del pie de página.

Ejemplo de devolución de llamada de resultados listos

La devolución de llamada resultsReady de ejemplo en Ejemplo de devolución de llamada de resultados listos anula la presentación predeterminada de las promociones y los resultados con un reemplazo muy simple.

    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>

Devolución de llamada renderizada de los resultados de la búsqueda de imágenes o web

Estas devoluciones de llamada se invocan inmediatamente antes de que el JavaScript del Elemento de búsqueda renderice el pie de página. Entre los casos de uso de ejemplo, se incluiría una devolución de llamada que agrega contenido de resultados que el elemento de búsqueda no muestra, como una casilla de verificación Guardar o información que no se renderiza automáticamente, o una devolución de llamada que agrega botones Para obtener más información.

Si una devolución de llamada de resultados renderizados necesita información que estaba en los parámetros promos y results de la devolución de llamada de resultados listos, puede pasarla entre ellos, de la siguiente manera:

callback(gname, query, promoElts, resultElts);

gname

Cadena de identificación del elemento de búsqueda

query

Cadena de búsqueda de

.

promoElts

un array de los elementos del DOM que contienen promociones.

resultElts

: Un array de los elementos del DOM que contienen resultados.

No hay valor de retorno.

Ejemplo de devolución de llamada de resultados renderizados

La devolución de llamada de resultsRendered de ejemplo en Devolución de llamada de ejemplo de resultados renderizados agrega una casilla de verificación Keep ficticia a cada promoción y 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>

Si la devolución de llamada de resultados renderizados necesita información que se pasó a la devolución de llamada de resultados listos, puede pasar esos datos entre las devoluciones de llamada. En el siguiente ejemplo, se muestra una de las muchas formas de pasar un valor de calificación de richSnippet desde la devolución de llamada de resultados listos a la devolución de llamada 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>

Ejemplo de devolución de llamada de renderización de resultados: Apertura de tipos de archivos específicos en una pestaña o ventana nueva

En el siguiente ejemplo de devolución de llamada, se pueden modificar los vínculos de los resultados de la búsqueda después de que se renderizan para abrir un archivo específico en una pestaña o página nueva en lugar de la ventana actual (por ejemplo, PDF, Excel o Word). Esto mejora la experiencia de navegación cuando los usuarios no quieren abrir un archivo en la misma ventana y se alejan de la página de resultados.

En este ejemplo de devolución de llamada, se identifican los vínculos a archivos PDF en los resultados de la búsqueda y se establece el atributo target="_blank" en los vínculos a archivos PDF para que se abran en una pestaña nueva. Se usa un MutationObserver para controlar de forma dinámica los resultados nuevos si se actualiza la página. Nota: Puedes reemplazar .pdf en handleSearchResults por cualquier otro tipo de archivo según tus necesidades.

Este ejemplo de devolución de llamada no funciona en los diseños de Google Hosted ni de Overlay.

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>

Más ejemplos de devoluciones de llamada

Puedes encontrar ejemplos adicionales de devoluciones de llamada en el documento More Callback Examples.

Propiedades de promoción y resultado

Con la notación de JSDoc, estas son las propiedades de los objetos promotion y result. Aquí, enumeramos todas las propiedades que podrían estar presentes. La presencia de muchas de las propiedades depende de los detalles de la promoción o del resultado de la búsqueda.

{
  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 en results tiene el tipo flexible de un array de objetos. Los valores de las entradas de este array se controlan con los datos estructurados que se encuentran en la página web para cada resultado de la búsqueda. Por ejemplo, un sitio web de opiniones podría incluir datos estructurados que agreguen esta entrada de array a richSnippet:

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

API de Programmable Search Element Control (V2)

El objeto google.search.cse.element publica las siguientes funciones estáticas:

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