Programmable Search Element Control API

Sie können Komponenten der programmierbaren Suchmaschine (Suchfelder und Suchergebnisseiten) mithilfe von HTML-Markup in Ihre Webseiten und andere Webanwendungen einbetten. Diese Elemente der Programmable Search Engine bestehen aus Komponenten, die auf Grundlage der auf dem Programmable Search-Server gespeicherten Einstellungen sowie aller von Ihnen vorgenommenen Anpassungen gerendert werden.

Das gesamte JavaScript wird asynchron geladen. So kann Ihre Webseite weiter geladen werden, während der Browser das JavaScript der Programmable Search Engine abruft.

Einführung

In diesem Dokument wird ein grundlegendes Modell zum Hinzufügen von Programmable Search Engine-Elementen auf Ihrer Webseite beschrieben. Außerdem werden die konfigurierbaren Komponenten des Elements und die flexible JavaScript API erläutert.

Umfang

In diesem Dokument wird beschrieben, wie Sie die Funktionen und Eigenschaften verwenden, die für die Programmable Search Engine Control API spezifisch sind.

Browserkompatibilität

Eine Liste der von der programmierbaren Suchmaschine unterstützten Browser finden Sie hier.

Zielgruppe

Diese Dokumentation richtet sich an Entwickler, die ihren Seiten Funktionen der programmierbaren Google-Suche hinzufügen möchten.

Programmierbare Suchelemente

Sie können HTML-Markup verwenden, um ein Programmable Search Element auf Ihrer Seite einzufügen. Jedes Element besteht aus mindestens einer Komponente: einem Suchfeld, einem Block mit Suchergebnissen oder beidem. Im Suchfeld können Nutzereingaben auf folgende Weise erfolgen:

• Eine Suchanfrage, die in das Texteingabefeld eingegeben wurde
• Ein in eine URL eingebetteter Abfragestring
• Programmatische Ausführung

Außerdem kann der Block mit Suchergebnissen auf folgende Weise Eingaben entgegennehmen:

• Ein in eine URL eingebetteter Abfragestring
• Programmatische Ausführung

Die folgenden Arten von programmierbaren Suchelementen sind verfügbar:

Sie können Ihrer Webseite beliebig viele gültige Suchelemente hinzufügen. Im zweispaltigen Modus müssen alle erforderlichen Komponenten (ein Suchfeld und ein Suchergebnisblock) vorhanden sein.

Hier ein Beispiel für ein einfaches Suchelement:

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

Verschiedene Layoutoptionen mit Programmable Search Elements erstellen

Die folgenden Layoutoptionen sind im Steuerfeld der Programmable Search Engine auf der Seite „Design“ verfügbar. Im Folgenden finden Sie einige allgemeine Richtlinien zum Erstellen von Layoutoptionen mit programmierbaren Suchelementen. Klicken Sie auf den Link, um eine Demo für eine der Optionen aufzurufen.

Weitere Informationen zu Layoutoptionen

Elemente der programmierbaren Suche anpassen

Wenn Sie Farben, Schriftarten oder Linkstile anpassen möchten, rufen Sie die Seite „Erscheinungsbild“ Ihrer Programmable Search Engine auf.

Mit optionalen Attributen können Sie Konfigurationen überschreiben, die im Steuerfeld der Programmable Search Engine erstellt wurden. So können Sie eine seitenbezogene Suchfunktion erstellen. Mit dem folgenden Code wird beispielsweise ein Suchfeld erstellt, in dem eine Ergebnisseite (http://www.example.com?search=lady+gaga) in einem neuen Fenster geöffnet wird. Der Wert des queryParameterName-Attributs wird zusammen mit dem Suchanfrage-String des Nutzers verwendet, um die Ergebnis-URL zu erstellen.

Das Attribut queryParameterName hat das Präfix data-. Dieses Präfix ist für alle Attribute erforderlich.

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

Wenn Sie das Steuerfeld der Programmierbaren Suche verwendet haben, um Funktionen wie automatische Vervollständigung oder Suchfilter zu aktivieren, können Sie diese Funktionen mit Attributen anpassen. Alle Anpassungen, die Sie mit diesen Attributen vornehmen, überschreiben die Einstellungen in der Steuerkonsole. Im folgenden Beispiel wird ein Suchfeld mit zwei Spalten und den folgenden Funktionen erstellt:

• Verwaltung des Verlaufs ist aktiviert
• Die maximale Anzahl der angezeigten Vorschläge für die automatische Vervollständigung ist auf 5 festgelegt.
• Verfeinerungen werden als Links angezeigt.

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

Unterstützte Attribute

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

Callbacks

Callbacks unterstützen die detaillierte Steuerung der Initialisierung des Suchelements und der Suchvorgänge. Sie werden über das globale __gcse-Objekt im JavaScript des Suchelements registriert. Unter Callbacks registrieren wird die Registrierung aller unterstützten Callbacks veranschaulicht.

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

Der Initialisierungs-Callback

Der Initialisierungs-Callback wird aufgerufen, bevor das JavaScript des Suchelements Suchelemente im DOM rendert. Wenn parsetags in __gcse auf explicit gesetzt ist, überlässt das Search Element-JavaScript das Rendern von Search Elements dem Initialisierungs-Callback (siehe Callbacks registrieren). Dies kann verwendet werden, um Elemente auszuwählen, die gerendert werden sollen, oder um das Rendern von Elementen zu verzögern, bis sie benötigt werden. Außerdem können die Attribute der Elemente überschrieben werden. So kann beispielsweise ein Suchfeld, das über das Steuerfeld oder HTML-Attribute für die Websuche konfiguriert ist, in ein Bildsuchfeld umgewandelt werden. Oder es kann festgelegt werden, dass Anfragen, die über ein Formular der Programmierbaren Suche gesendet werden, in einem Element ausgeführt werden, das nur Suchergebnisse enthält. Demo ansehen

Die Rolle des Initialisierungs-Callbacks wird durch den Wert des Attributs parsetags von __gcse gesteuert.

• Wenn der Wert onload ist, werden alle Suchelemente auf der Seite automatisch vom JavaScript des Suchelements gerendert. Der Initialisierungs-Callback wird weiterhin aufgerufen, ist aber nicht für das Rendern der Suchelemente verantwortlich.
• Wenn der Wert explicit ist, werden keine Suchelemente gerendert. Der Callback kann sie mit der Funktion render() selektiv rendern oder alle Suchelemente mit der Funktion go() rendern.

Im folgenden Code wird gezeigt, wie Sie ein Suchfeld zusammen mit Suchergebnissen in einem div mit dem explicit-Parsetag und dem Initialisierungs-Callback rendern:

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

Nach Callbacks suchen

Das JavaScript für das Suchelement unterstützt sechs Callbacks, die im Suchablauf ausgeführt werden. Die Such-Callbacks werden paarweise gesendet, ein Web-Such-Callback und ein passender Bild-Such-Callback:

• Suche starten
  • Für die Bildersuche
  • Für die Websuche
• Ergebnisse bereit
  • Für die Bildersuche
  • Für die Websuche
• Gerenderte Ergebnisse
  • Für die Bildersuche
  • Für die Websuche

Wie beim Initialisierungs-Callback werden die Such-Callbacks mit Einträgen im __gcse-Objekt konfiguriert. Dies geschieht, wenn das JavaScript für das Suchelement gestartet wird. Änderungen an __gcse nach dem Start werden ignoriert.

Jeder dieser Callbacks erhält das gName für das Suchelement als Argument. gname ist nützlich, wenn eine Seite mehr als eine Suche enthält. Weisen Sie einem search-Element mit dem Attribut data-gname gname-Werte zu:

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

Wenn der gname nicht im HTML-Code angegeben ist, wird durch das JavaScript für das Suchelement ein Wert generiert, der bis zur Änderung des HTML-Codes beibehalten wird.

Callback zum Starten der Bild-/Websuche

Die Callbacks für den Suchstart werden unmittelbar aufgerufen, bevor das Search Element-JavaScript Suchergebnisse von seinem Server anfordert. Ein Beispiel wäre die Verwendung der lokalen Tageszeit, um Änderungen an der Anfrage zu steuern.

searchStartingCallback(gname, query)

gname

Identifizierungsstring des Suchelements

query

Vom Nutzer eingegebener Wert (möglicherweise durch JavaScript des Suchelements geändert).

Der Callback gibt den Wert zurück, der als Abfrage für diese Suche verwendet werden soll. Wenn ein leerer String zurückgegeben wird, wird der Rückgabewert ignoriert und der Aufrufer verwendet die unveränderte Abfrage.

Alternativ können Sie die Callback-Funktion in das __gcse-Objekt einfügen oder den Callback dynamisch mit JavaScript zum Objekt hinzufügen:

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

Beispiel für einen Callback zum Starten der Suche

Im Beispiel für den Callback zum Starten der Suche in Beispiel für Callback zum Starten der Suche wird der Anfrage je nach Tageszeit entweder morning oder afternoon hinzugefügt.

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

Installieren Sie diesen 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 für Bild-/Websuchergebnisse

Diese Rückrufe werden unmittelbar vor dem Rendern von Angeboten und Ergebnissen durch das JavaScript des Suchelements aufgerufen. Ein Beispiel für einen Anwendungsfall wäre ein Callback, mit dem Werbeaktionen und Ergebnisse in einem Stil gerendert werden, der mit der normalen Anpassung nicht angegeben werden kann.

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

gname

Identifizierungsstring des Suchelements

query

Abfrage, mit der diese Ergebnisse generiert wurden

promos

ein Array von Angebots-Objekten, die den übereinstimmenden Angeboten für die Nutzeranfrage entsprechen. Definition des Angebotsobjekts

results

ein Array von Ergebnisobjekten. Definition des Ergebnisobjekts

div

ein HTML-Div, das im DOM positioniert ist und in dem das Suchelement normalerweise Werbeanzeigen und Suchergebnisse platziert. Normalerweise wird dieses Div-Element durch das JavaScript des Suchelements gefüllt. Mit diesem Callback kann das automatische Rendern von Ergebnissen jedoch beendet und dieses div-Element zum Rendern von Ergebnissen verwendet werden.

Wenn dieser Callback einen true-Wert zurückgibt, wird im JavaScript des Suchelements die Arbeit im Seitenfooter übersprungen.

Beispiel für einen Callback für „Ergebnisse bereit“

Der Beispiel-resultsReady-Callback in Beispiel für Callback „Ergebnisse bereit“ überschreibt die Standarddarstellung von Angeboten und Ergebnissen mit einem sehr einfachen Ersatz.

    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>

Gerenderter Callback für Bild-/Websuchergebnisse

Diese Callbacks werden unmittelbar vor dem Rendern der Seitenfußzeile durch das JavaScript des Suchelements aufgerufen. Beispiele für Anwendungsfälle sind ein Callback, der Ergebnisinhalt hinzufügt, der vom Suchelement nicht angezeigt wird, z. B. ein Kästchen Speichern oder Informationen, die nicht automatisch gerendert werden, oder ein Callback, der Schaltflächen Weitere Informationen hinzufügt.

Wenn ein Callback für gerenderte Ergebnisse Informationen benötigt, die in den Parametern promos und results des Callback für fertige Ergebnisse enthalten waren, kann es diese so übergeben:

callback(gname, query, promoElts, resultElts);

gname

Identifizierungsstring des Suchelements

query

-Suchstring.

promoElts

: Ein Array der DOM-Elemente, die Werbeaktionen enthalten.

resultElts

ein Array der DOM-Elemente, die Ergebnisse enthalten.

Es gibt keinen Rückgabewert.

Beispiel für den Callback „Results Rendered“

Im Beispiel-Callback resultsRendered in Beispiel für gerenderten Callback für Ergebnisse wird jeder Werbeaktion und jedem Ergebnis ein Platzhalter für das Kästchen Behalten hinzugefügt.

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>

Wenn der Callback für gerenderte Ergebnisse Informationen benötigt, die an den Callback für bereite Ergebnisse übergeben wurden, können diese Daten zwischen den Callbacks übergeben werden. Das folgende Beispiel zeigt eine von vielen Möglichkeiten, einen Wert für die Bewertung von richSnippet aus dem Callback für fertige Ergebnisse an den Callback für gerenderte Ergebnisse zu übergeben.

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>

Beispiel für den Callback „Results Rendered“: Bestimmte Dateitypen in einem neuen Tab/Fenster öffnen

Mit dem folgenden Callback-Beispiel können Suchergebnislinks nach dem Rendern so geändert werden, dass eine bestimmte Datei (z. B. PDF, Excel oder Word) in einem neuen Tab/einer neuen Seite anstelle des aktuellen Fensters geöffnet wird. So wird das Surfen verbessert, wenn Nutzer eine Datei nicht im selben Fenster öffnen und die Ergebnisseite verlassen möchten.

In diesem Callback-Beispiel werden PDF-Links in den Suchergebnissen identifiziert und das Attribut target="_blank" für PDF-Links wird so festgelegt, dass sie in einem neuen Tab geöffnet werden. Mit einem MutationObserver werden neue Ergebnisse dynamisch verarbeitet, wenn die Seite aktualisiert wird. Hinweis:Sie können .pdf in handleSearchResults nach Bedarf durch einen beliebigen anderen Dateityp ersetzen.

Dieses Callback-Beispiel funktioniert nicht bei Google Hosted- und Overlay-Layouts.

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>

Weitere Beispiele für Rückrufe

Weitere Callback-Beispiele finden Sie im Dokument Weitere Callback-Beispiele.

Eigenschaften für Angebote und Ergebnisse

Dies sind die Eigenschaften der Objekte promotion und result in JSDoc-Notation. Hier finden Sie eine Liste aller Attribute, die vorhanden sein können. Das Vorhandensein vieler Eigenschaften hängt von den Details des Angebots oder Suchergebnisses ab.

{
  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 hat den losen Typ eines Arrays von Objekten. Die Werte der Einträge in diesem Array werden durch die strukturierten Daten auf der Webseite für jedes Suchergebnis bestimmt. Auf einer Rezensionswebsite könnten beispielsweise strukturierte Daten enthalten sein, mit denen dieser Array-Eintrag zu richSnippet hinzugefügt wird:

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

Programmable Search Element Control API (V2)

Das google.search.cse.element-Objekt stellt die folgenden statischen Funktionen bereit:

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