Programmable Search Element Control API

Sie können Programmable Search Engine-Komponenten wie Suchfelder und Suchergebnisseiten mit HTML-Markup Ihre Webseiten und andere Webanwendungen nutzen. Diese Programmable Search Engine -Elemente bestehen aus Komponenten, die basierend auf den von den den Server für die Programmable Search und alle von Ihnen vorgenommenen Anpassungen.

Der gesamte JavaScript-Code wird asynchron geladen, sodass Ihre Webseite während der Browser den JavaScript-Code der Programmable Search Engine abruft.

Einführung

Dieses Dokument enthält ein Basismodell zum Hinzufügen der Programmable Search Engine. -Elementen auf Ihrer Webseite zusammen mit Erklärungen zu den konfigurierbaren Komponenten und einer flexiblen JavaScript API.

Umfang

In diesem Dokument wird die Verwendung der Funktionen und Eigenschaften, die für die Programmable Search Engine Control API.

Browserkompatibilität

Eine Liste der von der Programmable Search Engine unterstützten Browser finden Sie hier.

Zielgruppe

Diese Dokumentation richtet sich an Entwickler, die Google Programmable Suchfunktionen hinzufügen.

Programmierbare Suchelemente

Sie können HTML-Markup verwenden, um Ihrer Seite ein Programmable Search Element hinzuzufügen. Jedes -Element besteht aus mindestens einer Komponente: einem Suchfeld, einem Suchblock Ergebnisse, oder beides. In das Suchfeld können Nutzer Folgendes eingeben: Möglichkeiten:

• Eine in das Texteingabefeld eingegebene Suchanfrage
• Ein in eine URL eingebetteter Abfragestring
• Programmatische Ausführung

Außerdem akzeptiert der Block der Suchergebnisse Eingaben in den auf folgende Arten:

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

Die folgenden Typen von programmierbaren Suchelementen sind verfügbar:

Sie können Ihrer Webseite beliebig viele gültige Suchelemente hinzufügen. Für zweispaltige und alle erforderlichen Komponenten (ein Suchfeld und Ergebnisblock) vorhanden sein müssen.

Hier ist 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 auf der Seite „Design“ des Steuerfelds „Programmable Search Engine“ verfügbar. Im Folgenden finden Sie einige allgemeine Richtlinien zum Erstellen von Layoutoptionen mit programmierbaren Suchelementen. Um eine Demo dieser Optionen anzuzeigen, klicken Sie auf den Link.

Weitere Informationen zu Layoutoptionen

Elemente der programmierbaren Suche anpassen

Um Farben, Schriftart und Linkstil anzupassen, rufen Sie die Seite „Design“ Ihrer programmierbaren Suchmaschine auf.

Sie können optionale Attribute verwenden, um Konfigurationen zu überschreiben, die in der Programmierbare Suchmaschine Steuerfeld So können Sie eine seitenspezifische Suche erstellen. Mit dem folgenden Code wird beispielsweise ein Suchfeld erstellt, das eine Suchergebnisseite öffnet. (http://www.example.com?search=lady+gaga) in einem neuen Fenster öffnen. Der Wert der Eigenschaft queryParameterName zusammen mit dem Nutzerabfragestring mit denen die Ergebnis-URL erstellt wurde.

Beachten Sie, dass dem Attribut queryParameterName das Präfix data- vorangestellt ist. 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 über das Steuerfeld der Programmable Search Engine Funktionen wie automatische Vervollständigung oder Optimierungen nutzen, können Sie um diese Funktionen anzupassen. Alle Anpassungen, die Sie mithilfe dieser Attribute festlegen überschreibt die im Steuerungsfeld vorgenommenen Einstellungen. Im folgenden Beispiel wird erstellt, ein zweispaltiges Suchelement mit den folgenden Funktionen:

• Verlaufsverwaltung ist aktiviert
• Die maximale Anzahl der angezeigten automatischen Vervollständigungen ist auf 5 festgelegt
• Suchfilter 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

</ph> <ph type="x-smartling-placeholder"></ph>

Callbacks unterstützen die detaillierte Steuerung der Initialisierung der Suchelemente und der Suchprozesse. Sie werden im JavaScript des Search Element über das globale __gcse registriert. -Objekt enthält. Register Callbacks (Callbacks registrieren) veranschaulicht die Registrierung aller unterstützte Callbacks unterstützt.

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

Initialisierungs-Callback

Der Initialisierungs-Callback wird aufgerufen, bevor das Suchelement-JavaScript die Suche rendert Elemente im DOM. Wenn parsetags auf explicit gesetzt ist, __gcse aktiviert, rendert das JavaScript für das Suchelement die Suchelemente auf dem Initialisierungs-Callback (wie unter Register Callbacks dargestellt). Dies kann verwendet werden, um Elemente zum Rendern auszuwählen oder das Rendern von Elementen zu verschieben, bis sie wieder gerendert werden erforderlich. Außerdem können die Attribute der Elemente überschrieben werden. kann es zum Beispiel Suchfeld, das über das Steuerfeld oder die HTML-Attribute so konfiguriert ist, dass es standardmäßig in ein Bildsuchfeld suchen oder angeben, dass über ein Programmable Search Engine-Formular gesendete Anfragen ausgeführt werden. <ph type="x-smartling-placeholder"></ph> Demo ansehen

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

• Wenn der Wert onload ist, gibt das Suchelement JavaScript rendert alle Suchelemente auf der Seite automatisch. Der Initialisierungs-Callback ist weiterhin aufgerufen, ist jedoch nicht für das Rendern der Suchelemente verantwortlich.
• Wenn der Wert explicit ist, wird das Suchelement-JavaScript nicht gerendert. Elemente suchen. Der Callback kann sie mithilfe der Methode render()-Funktion verwenden, oder alle Suchelemente mit der Funktion go() rendern

Der folgende Code zeigt, wie ein Suchfeld zusammen mit Suchergebnissen in einem div unter Verwendung des Parse-Tags explicit und des Initialisierungs-Callbacks:

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

Rückrufe suchen

Das Suchelement-JavaScript unterstützt sechs Callbacks, die im die Suche steuern. Die Such-Callbacks kommen paarweise, ein Websuch-Callback und ein übereinstimmender Bildsuche-Callback:

• Suche beginnt <ph type="x-smartling-placeholder">
  </ph>
  • Für die Bildersuche
  • Für die Websuche
• Ergebnisse verfügbar <ph type="x-smartling-placeholder">
  </ph>
  • Für die Bildersuche
  • Für die Websuche
• Gerenderte Ergebnisse <ph type="x-smartling-placeholder">
  </ph>
  • Für die Bildersuche
  • Für die Websuche

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

Jedem dieser Callbacks wird das gName für das Search Element als Argument. gname ist nützlich, wenn eine Seite mehr als eine Suche enthält. Suche starten mit dem Attribut data-gname einen gname-Wert festlegen:

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

Wenn der gname im HTML-Code nicht identifiziert wird, generiert das Suchelement-JavaScript einen Wert, der bleiben einheitlich, bis der HTML-Code geändert wird.

Callback beim Starten der Bild-/Websuche

Die Callbacks, die die Suche starten, werden unmittelbar vor den JavaScript-Anfragen für das Suchelement aufgerufen. die Suchergebnisse von seinem Server. Ein Anwendungsbeispiel wäre die Verwendung der lokalen Tageszeit, um Änderungen an der Abfrage zu steuern.

searchStartingCallback(gname, query)

gname

Identifizierender String des Suchelements

query

Vom Nutzer eingegebener Wert (möglicherweise durch die Suche geändert) -Elements im JavaScript-Code.)

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

Alternativ kannst du die Callback-Funktion in das __gcse-Objekt einfügen oder Sie fügen den Callback dynamisch mit JavaScript zum Objekt hinzu:

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

Beispiel für einen Callback beim Starten der Suche

Die Beispielsuche, die einen Callback startet, Beispiel-Callback beim Starten der Suche fügt entweder morning hinzu oder afternoon hinzu (je nach Tageszeit).

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

Diesen Callback in window.__gcse: installieren

  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>

Rückruf für Bilder-/Websuchergebnisse

Diese Callbacks werden aufgerufen, bevor das Suchelement-JavaScript die bevorzugten Suchergebnisse und Ergebnisse. Ein Beispiel für einen Anwendungsfall wäre ein Callback, der bevorzugte Suchergebnisse darstellt und zu einem Stil führt, kann nicht mit der normalen Anpassung angegeben werden.

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

gname

Identifizierender String des Suchelements

query

Abfrage, die diese Ergebnisse geliefert hat

promos

Ein Array mit Werbeobjekten, die übereinstimmenden Werbeaktionen für die auf die Suchanfrage des Nutzers. Weitere Informationen finden Sie in der Definition des Angebotsobjekts.

results

Array von Ergebnisobjekten Weitere Informationen finden Sie in der Ergebnisobjektdefinition.

div

Ein HTML-div-Element im DOM, an dem das Suchelement normalerweise und in den Suchergebnissen. Normalerweise würde das Suchelement-JavaScript dieses div-Element auszufüllen, aber dieser Callback kann die automatische Darstellung der Ergebnisse stoppen. und verwenden Sie div, um die Ergebnisse selbst zu rendern.

Wenn dieser Callback einen true-Wert zurückgibt, springt das Suchelement-JavaScript zu seinem in der Fußzeile zu arbeiten.

Beispiel-Callback für Ergebnisausgabe

Das Beispiel resultsReady-Callback in Der Beispielaufruf-Callback für Ergebnisse überschreibt die Standardpräsentation. von Werbeaktionen und Ergebnissen durch einen 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>

Callback für gerenderte Bilder/Websuchergebnisse

Diese Callbacks werden aufgerufen, bevor das Suchelement-JavaScript die Seite rendert. in der Fußzeile. Beispielanwendungsfälle wären z. B. ein Callback, der Ergebnisinhalte hinzufügt, die von der Suche nicht angezeigt, wie das Kästchen Speichern oder Informationen, die nicht automatisch gerendert wird oder ein Callback ist, mit dem Schaltflächen für weitere Informationen hinzugefügt werden.

Wenn für einen gerenderten Callback mit Ergebnis Informationen benötigt werden, die in den promos- und results des Callbacks für Ergebnisse, kann diese wie folgt zwischen ihnen übergeben werden:

callback(gname, query, promoElts, resultElts);

gname

Identifizierender String des Suchelements

query

Suchstring.

promoElts

Ein Array der DOM-Elemente, die Angebote enthalten.

resultElts

Ein Array der DOM-Elemente, die Ergebnisse enthalten.

Es gibt keinen Rückgabewert.

Beispiel-Callback für gerenderte Ergebnisse

Das Beispiel resultsRendered-Callback in Der Beispiel-Callback für gerenderte Ergebnisse fügt ein Dummy-Keep-Element hinzu. für jedes bevorzugte Suchergebnis und jedes Ergebnis an.

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 für den gerenderten Callback für Ergebnisse Folgendes erforderlich ist: Informationen, die an den results ready-Callback übergeben wurden, können diese Daten zwischen die Callbacks. Das folgende Beispiel zeigt eine von vielen Möglichkeiten, einen Bewertungswert von richSnippet vom Callback bereit für die Ergebnisse an die gerenderten Ergebnisse zurück.

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>

Weitere Callback-Beispiele

Weitere Callback-Beispiele finden Sie in der Weitere Callback-Beispiele.

Angebots- und Ergebniseigenschaften

In der JSDoc-Notation sind dies die Eigenschaften von promotion- und result-Objekte. Hier sind alle Eigenschaften aufgelistet, die vorhanden sein können. Viele der Properties sind vorhanden. von den Details der Werbeaktion oder des 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 lockeren Typ eines Arrays: Objekte. Die Werte der Einträge in diesem Array werden vom strukturierte Daten die auf der Webseite für die einzelnen Suchergebnisse gefunden werden. Eine Website mit Rezensionen kann beispielsweise strukturierte Daten, mit denen dieser Array-Eintrag richSnippet hinzugefügt wird:

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

Programmable Search Element Control API (Version 2)

Das Objekt google.search.cse.element veröffentlicht Folgendes: statische Funktionen:

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