API Programmable Search Element Control

Puoi incorporare i componenti del Motore di ricerca programmabile (caselle di ricerca e pagine dei risultati di ricerca) nelle tue pagine web e in altre applicazioni web utilizzando il markup HTML. Questi elementi del Motore di ricerca programmabile sono costituiti da componenti visualizzati in base alle impostazioni memorizzate dal server di Ricerca programmabile, insieme alle personalizzazioni apportate.

Tutto il codice JavaScript viene caricato in modo asincrono, il che consente alla pagina web di continuare a caricarsi mentre il browser recupera il codice JavaScript del Motore di ricerca programmabile.

Introduzione

Questo documento fornisce un modello di base per l'aggiunta di elementi di Motore di ricerca programmabile alla tua pagina web, insieme alle spiegazioni dei componenti configurabili dell'elemento e dell'API JavaScript flessibile.

Ambito

Questo documento descrive come utilizzare le funzioni e le proprietà specifiche dell'API Programmable Search Engine Control.

Compatibilità del browser

L'elenco dei browser supportati dal Motore di ricerca programmabile è disponibile qui.

Pubblico

Questa documentazione è destinata agli sviluppatori che vogliono aggiungere la funzionalità di Ricerca programmabile Google alle loro pagine.

Elementi di ricerca programmabile

Puoi utilizzare il markup HTML per aggiungere un elemento Ricerca programmabile alla tua pagina. Ogni elemento è costituito da almeno un componente: una casella di ricerca, un blocco di risultati di ricerca o entrambi. La casella di ricerca accetta l'input dell'utente in uno dei seguenti modi:

• Una query di ricerca digitata nel campo di input di testo
• Una stringa di query incorporata in un URL
• Esecuzione programmatica

Inoltre, il blocco dei risultati di ricerca accetta input nei seguenti modi:

• Una stringa di query incorporata in un URL
• Esecuzione programmatica

Sono disponibili i seguenti tipi di elementi di Ricerca programmabile:

Puoi aggiungere alla tua pagina web tutti gli elementi di ricerca validi che vuoi. Per la modalità a due colonne, devono essere presenti tutti i componenti richiesti (una casella di ricerca e un blocco di risultati di ricerca).

Ecco un esempio di elemento di ricerca semplice:

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

Comporre diverse opzioni di layout utilizzando gli elementi di ricerca programmabile

Nella pagina Layout e formattazione del pannello di controllo del Motore di ricerca programmabile sono disponibili le seguenti opzioni di layout. Ecco alcune linee guida generali sulla composizione delle opzioni di layout utilizzando gli elementi di ricerca programmabile. Per visualizzare una demo di una di queste opzioni, fai clic sul link.

Scopri di più sulle opzioni di layout.

Personalizzazione degli elementi di Ricerca programmabile

Per personalizzare i colori, il carattere o lo stile dei link, vai alla pagina Aspetto del tuo motore di ricerca programmabile.

Puoi utilizzare gli attributi facoltativi per sovrascrivere le configurazioni create nel pannello di controllo del Motore di ricerca programmabile. In questo modo, puoi creare un'esperienza di ricerca specifica per la pagina. Ad esempio, il seguente codice crea una casella di ricerca che apre una pagina dei risultati (http://www.example.com?search=lady+gaga) in una nuova finestra. Il valore dell'attributo queryParameterName, insieme alla stringa di query dell'utente, viene utilizzato per creare l'URL dei risultati.

Tieni presente che l'attributo queryParameterName è preceduto dal prefisso data-. Questo prefisso è obbligatorio per tutti gli attributi.

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

Se hai utilizzato il pannello di controllo del motore di ricerca programmabile per attivare funzionalità come il completamento automatico o i perfezionamenti, puoi utilizzare gli attributi per personalizzare queste funzionalità. Qualsiasi personalizzazione specificata utilizzando questi attributi sostituirà le impostazioni effettuate nel pannello di controllo. L'esempio seguente crea un elemento di ricerca a due colonne con le seguenti funzionalità:

• La gestione della cronologia è attivata
• Il numero massimo di completamenti automatici visualizzati è impostato su 5
• I miglioramenti vengono visualizzati come link.

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

Attributi supportati

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

Callback

I callback supportano il controllo dettagliato dell'inizializzazione dell'elemento di ricerca e dei processi di ricerca. Sono registrati con l'elemento di ricerca JavaScript tramite l'oggetto globale __gcse. Register Callbacks illustra la registrazione di tutti i callback supportati.

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

Il callback di inizializzazione

Il callback di inizializzazione viene richiamato prima che il JavaScript dell'elemento di ricerca esegua il rendering degli elementi di ricerca nel DOM. Se parsetags è impostato su explicit in __gcse, il rendering degli elementi di ricerca viene lasciato al callback di inizializzazione (come mostrato in Registra callback). Potrebbe essere utilizzato per selezionare gli elementi da visualizzare o per posticipare il rendering degli elementi fino a quando non sono necessari. Può anche ignorare gli attributi degli elementi; ad esempio, può trasformare una casella di ricerca configurata tramite il pannello di controllo o gli attributi HTML in una casella di ricerca di immagini o specificare che le query inviate tramite un modulo del motore di ricerca programmabile vengono eseguite in un elemento solo risultati di ricerca. Guarda una demo.

Il ruolo del callback di inizializzazione è controllato dal valore della proprietà parsetags di __gcse.

• Se il valore è onload, il codice JavaScript dell'elemento di ricerca esegue il rendering automatico di tutti gli elementi di ricerca nella pagina. Il callback di inizializzazione viene comunque richiamato, ma non è responsabile del rendering degli elementi di ricerca.
• Se il valore è explicit, il codice JavaScript dell'elemento di ricerca non esegue il rendering degli elementi di ricerca. Il callback può eseguirli il rendering in modo selettivo utilizzando la funzione render() o eseguire il rendering di tutti gli elementi di ricerca con la funzione go().

Il seguente codice mostra come eseguire il rendering di una casella di ricerca, insieme ai risultati di ricerca, in un div, utilizzando il tag di analisi explicit e il callback di inizializzazione:

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

Cerca richiamate

Il JavaScript dell'elemento di ricerca supporta sei callback che operano nel flusso di controllo della ricerca. I callback di ricerca sono a coppie: un callback di ricerca web e un callback di ricerca immagini corrispondente:

• Ricerca iniziale
  • Per la ricerca immagini
  • Per la ricerca sul web
• Risultati pronti
  • Per la ricerca immagini
  • Per la ricerca sul web
• Risultati visualizzati
  • Per la ricerca immagini
  • Per la ricerca sul web

Come il callback di inizializzazione,i callback di ricerca vengono configurati utilizzando le voci nell'oggetto __gcse. Ciò accade quando viene avviato il codice JavaScript dell'elemento di ricerca. Le modifiche apportate a __gcse dopo l'avvio vengono ignorate.

A ognuna di queste funzioni di callback viene passato gName per l'elemento di ricerca come argomento. Il gname è utile quando una pagina contiene più di una ricerca. Assegna a un elemento di ricerca i valori gname utilizzando l'attributo data-gname:

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

Se l'HTML non identifica il nome, lo script JavaScript dell'elemento di ricerca genera un valore che rimarrà coerente finché l'HTML non verrà modificato.

Image/Web Search-Starting Callback

I callback di avvio della ricerca vengono richiamati immediatamente prima che il JavaScript dell'elemento di ricerca richieda i risultati di ricerca dal suo server. Un esempio di caso d'uso potrebbe essere l'utilizzo dell'ora locale del giorno per controllare le modifiche alla query.

searchStartingCallback(gname, query)

gname

Stringa identificativa dell'elemento di ricerca

query

Valore

inserito dall'utente (eventualmente modificato dal JavaScript dell'elemento di ricerca).

Il callback restituisce il valore da utilizzare come query per questa ricerca. Se restituisce una stringa vuota, il valore restituito viene ignorato e il chiamante utilizza la query non modificata.

In alternativa, puoi inserire la funzione di callback nell'oggetto __gcse o aggiungere dinamicamente il callback all'oggetto con JavaScript:

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

Esempio di callback di avvio della ricerca

La ricerca di esempio che avvia il callback in Example Search Starting Callback aggiunge morning o afternoon alla query a seconda dell'ora del giorno.

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

Installa questo callback in 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 per i risultati di ricerca di immagini/web

Questi callback vengono richiamati immediatamente prima che il codice JavaScript dell'elemento di ricerca esegua il rendering delle promozioni e dei risultati. Un caso d'uso di esempio è un callback che esegue il rendering delle promozioni e dei risultati in uno stile che non può essere specificato con la normale personalizzazione.

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

gname

Stringa identificativa dell'elemento di ricerca

query

query che ha prodotto questi risultati

promos

Un array di oggetti promozione, che corrispondono alle promozioni corrispondenti alla query dell'utente. Consulta la definizione dell'oggetto promozione.

results

un array di oggetti risultato. Consulta la definizione dell'oggetto risultato.

div

un div HTML posizionato nel DOM in cui l'elemento di ricerca inserirebbe normalmente promozioni e risultati di ricerca. Normalmente, il codice JavaScript dell'elemento di ricerca gestisce il riempimento di questo div, ma questo callback può scegliere di interrompere il rendering automatico dei risultati e utilizzare questo div per eseguire il rendering dei risultati.

Se questo callback restituisce un valore true, il codice JavaScript dell'elemento di ricerca passa al lavoro del piè di pagina.

Esempio di callback Risultati pronti

Il callback resultsReady di esempio in Example Results Ready Callback sostituisce la presentazione predefinita di promozioni e risultati con una sostituzione molto semplice.

    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>

Image/Web Search Results-Rendered Callback

Questi callback vengono richiamati immediatamente prima che il JavaScript dell'elemento di ricerca esegua il rendering del piè di pagina della pagina. Esempi di casi d'uso includono un callback che aggiunge contenuti dei risultati che l'elemento di ricerca non visualizza, ad esempio una casella di controllo Salva o informazioni che non vengono visualizzate automaticamente, oppure un callback che aggiunge pulsanti Per saperne di più.

Se un callback di rendering dei risultati ha bisogno di informazioni che si trovavano nei parametri promos e results del callback di disponibilità dei risultati, può passarle tra loro, in questo modo:

callback(gname, query, promoElts, resultElts);

gname

Stringa identificativa dell'elemento di ricerca

query

stringa di ricerca.

promoElts

Un array degli elementi DOM contenenti promozioni.

resultElts

un array degli elementi DOM contenenti i risultati.

Non è presente alcun valore restituito.

Esempio di callback di rendering dei risultati

Il callback resultsRendered di esempio in Example Results Rendered Callback aggiunge una casella di controllo Keep fittizia a ogni promozione e risultato.

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 il callback dei risultati di rendering ha bisogno di informazioni passate al callback dei risultati pronti, può passare questi dati tra i callback. L'esempio seguente mostra uno dei tanti modi per passare un valore di valutazione da richSnippet dal callback dei risultati pronti al callback dei risultati visualizzati.

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>

Esempio di callback di rendering dei risultati: apertura di tipi di file specifici in una nuova scheda/finestra

Il seguente esempio di callback può modificare i link dei risultati di ricerca dopo il rendering per aprire un file specifico in una nuova scheda/pagina anziché nella finestra corrente (ad esempio PDF, Excel o Word). In questo modo, l'esperienza di navigazione migliora quando gli utenti non vogliono aprire un file nella stessa finestra e allontanarsi dalla pagina dei risultati.

Questo esempio di callback identifica i link PDF nei risultati di ricerca e imposta l'attributo target="_blank" sui link PDF in modo che si aprano in una nuova scheda. Un MutationObserver viene utilizzato per gestire dinamicamente i nuovi risultati se la pagina viene aggiornata. Nota:puoi sostituire .pdf in handleSearchResults con qualsiasi altro tipo di file in base alle tue esigenze.

Questo esempio di callback non funziona nei layout Google Hosted e 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>

Altri esempi di callback

Altri esempi di callback sono disponibili nel documento Altri esempi di callback.

Proprietà di promozione e risultati

Utilizzando la notazione JSDoc, queste sono le proprietà degli oggetti promotion e result. Qui sono elencate tutte le proprietà che potrebbero essere presenti. La presenza di molte proprietà dipende dai dettagli della promozione o del risultato di ricerca.

{
  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 in results ha il tipo libero di un array di oggetti. I valori delle voci di questo array sono controllati dai dati strutturati trovati nella pagina web per ogni risultato di ricerca. Ad esempio, un sito web di recensioni potrebbe includere dati strutturati che aggiungono questa voce dell'array a richSnippet:

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

API Programmable Search Element Control (V2)

L'oggetto google.search.cse.element pubblica le seguenti funzioni statiche:

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