API Programmable Search Element Control

Vous pouvez intégrer des composants Programmable Search Engine (champs de recherche et pages de résultats de recherche) dans vos pages Web et d'autres applications Web à l'aide du balisage HTML. Ces éléments Programmable Search Engine sont constitués de composants affichés en fonction des paramètres stockés par le serveur Programmable Search, ainsi que des personnalisations que vous effectuez.

Tout le code JavaScript est chargé de manière asynchrone, ce qui permet à votre page Web de continuer à se charger pendant que le navigateur récupère le code JavaScript Programmable Search Engine.

Introduction

Ce document fournit un modèle de base pour ajouter des éléments Programmable Search Engine à votre page Web, ainsi que des explications sur les composants configurables de l'élément et l'API JavaScript flexible.

Champ d'application

Ce document explique comment utiliser les fonctions et les propriétés spécifiques à l'API Programmable Search Engine Control.

Compatibilité du navigateur

Pour consulter la liste des navigateurs compatibles avec le moteur de recherche programmable, cliquez ici.

Audience

Cette documentation est destinée aux développeurs qui souhaitent ajouter la fonctionnalité Programmable Search de Google à leurs pages.

Éléments de recherche programmable

Vous pouvez utiliser le balisage HTML pour ajouter un Programmable Search Element à votre page. Chaque élément se compose d'au moins un composant : un champ de recherche, un bloc de résultats de recherche ou les deux. Le champ de recherche accepte les saisies des utilisateurs de l'une des manières suivantes :

• Requête de recherche saisie dans le champ de saisie de texte
• Chaîne de requête intégrée à une URL
• Exécution programmatique

De plus, le bloc de résultats de recherche accepte les entrées des manières suivantes :

• Chaîne de requête intégrée à une URL
• Exécution programmatique

Les types d'éléments de recherche programmable suivants sont disponibles :

Vous pouvez ajouter autant d'éléments de recherche valides que vous le souhaitez à votre page Web. En mode à deux colonnes, tous les composants requis (un champ de recherche et un bloc de résultats de recherche) doivent être présents.

Voici un exemple d'élément de recherche 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>

Composer différentes options de mise en page à l'aide des éléments Programmable Search

Les options de mise en page suivantes sont disponibles sur la page "Apparence" du panneau de configuration Programmable Search Engine. Voici quelques consignes générales concernant la composition des options de mise en page à l'aide des éléments de recherche programmable. Pour voir une démonstration de l'une de ces options, cliquez sur le lien.

En savoir plus sur les options de mise en page

Personnaliser les éléments de Recherche programmable

Pour personnaliser les couleurs, la police ou le style des liens, accédez à la page "Apparence" de votre moteur de recherche programmable.

Vous pouvez utiliser des attributs facultatifs pour remplacer les configurations créées dans le panneau de configuration Programmable Search Engine. Cela vous permet de créer une expérience de recherche spécifique à une page. Par exemple, le code suivant crée un champ de recherche qui ouvre une page de résultats (http://www.example.com?search=lady+gaga) dans une nouvelle fenêtre. La valeur de l'attribut queryParameterName, ainsi que la chaîne de requête utilisateur, sont utilisées pour créer l'URL des résultats.

Notez que l'attribut queryParameterName est précédé de data-. Ce préfixe est obligatoire pour tous les attributs.

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

Si vous avez utilisé le panneau de configuration du Programmable Search Engine pour activer des fonctionnalités telles que la saisie semi-automatique ou les affinement, vous pouvez utiliser des attributs pour les personnaliser. Toutes les personnalisations que vous spécifiez à l'aide de ces attributs remplaceront les paramètres définis dans le panneau de configuration. L'exemple suivant crée un élément de recherche à deux colonnes avec les caractéristiques suivantes :

• La gestion de l'historique est activée
• Le nombre maximal de saisies semi-automatiques affichées est défini sur 5.
• Les affinements s'affichent sous forme de liens.

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

Attributs acceptés

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

Rappels

Les rappels permettent de contrôler précisément l'initialisation des éléments de recherche et les processus de recherche. Ils sont enregistrés auprès de l'élément de recherche JavaScript via l'objet global __gcse. Register Callbacks illustre l'enregistrement de tous les rappels acceptés.

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

Rappel d'initialisation

Le rappel d'initialisation est appelé avant que le JavaScript de l'élément de recherche ne rende les éléments de recherche dans le DOM. Si parsetags est défini sur explicit dans __gcse, le code JavaScript de l'élément de recherche laisse le rendu des éléments de recherche au rappel d'initialisation (comme indiqué dans Enregistrer les rappels). Cela peut être utilisé pour sélectionner les éléments à afficher ou pour différer l'affichage des éléments jusqu'à ce qu'ils soient nécessaires. Il peut également remplacer les attributs des éléments. Par exemple, il peut transformer un champ de recherche configuré via le panneau de configuration ou les attributs HTML pour qu'il soit défini par défaut sur la recherche sur le Web en un champ de recherche d'images, ou spécifier que les requêtes envoyées via un formulaire Programmable Search Engine sont exécutées dans un élément de résultats de recherche uniquement. Regardez une démonstration.

Le rôle du rappel d'initialisation est contrôlé par la valeur de la propriété parsetags de __gcse.

• Si sa valeur est onload, le JavaScript de l'élément de recherche affiche automatiquement tous les éléments de recherche sur la page. Le rappel d'initialisation est toujours appelé, mais il n'est pas responsable du rendu des éléments de recherche.
• Si sa valeur est explicit, le JavaScript de l'élément de recherche n'affiche pas les éléments de recherche. La fonction de rappel peut les afficher de manière sélective à l'aide de la fonction render() ou afficher tous les éléments de recherche avec la fonction go().

Le code suivant montre comment afficher un champ de recherche et les résultats de recherche dans un div, à l'aide du tag d'analyse explicit et du rappel d'initialisation :

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

Rappels de recherche

Le JavaScript de l'élément de recherche est compatible avec six rappels qui fonctionnent dans le flux de contrôle de la recherche. Les rappels de recherche sont fournis par paires : un rappel de recherche sur le Web et un rappel de recherche d'images correspondant :

• Recherche en cours
  • Pour la recherche d'images
  • Pour la recherche sur le Web
• Résultats disponibles
  • Pour la recherche d'images
  • Pour la recherche sur le Web
• Résultats affichés
  • Pour la recherche d'images
  • Pour la recherche sur le Web

Comme le rappel d'initialisation,les rappels de recherche sont configurés à l'aide d'entrées dans l'objet __gcse. Cela se produit au démarrage du code JavaScript de l'élément de recherche. Les modifications apportées à __gcse après le démarrage sont ignorées.

Chacun de ces rappels reçoit le gName de l'élément de recherche en tant qu'argument. Le gname est utile lorsqu'une page contient plusieurs recherches. Attribuez des valeurs gname à un élément de recherche à l'aide de l'attribut data-gname :

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

Si le nom n'est pas identifié dans le code HTML, le JavaScript de l'élément de recherche génère une valeur qui restera cohérente jusqu'à ce que le code HTML soit modifié.

Rappel de début de recherche d'images/sur le Web

Les rappels de début de recherche sont appelés immédiatement avant que l'élément de recherche JavaScript ne demande des résultats de recherche à son serveur. Par exemple, vous pouvez utiliser l'heure locale pour contrôler les modifications apportées à la requête.

searchStartingCallback(gname, query)

gname

Chaîne d'identification de l'élément de recherche

query

Valeur

saisie par l'utilisateur (éventuellement modifiée par le code JavaScript de l'élément de recherche).

Le rappel renvoie la valeur à utiliser comme requête pour cette recherche. S'il renvoie une chaîne vide, la valeur de retour est ignorée et l'appelant utilise la requête non modifiée.

Vous pouvez également placer la fonction de rappel dans l'objet __gcse ou ajouter dynamiquement le rappel à l'objet avec JavaScript :

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

Exemple de rappel de début de recherche

L'exemple de rappel de début de recherche dans Exemple de rappel de début de recherche ajoute morning ou afternoon à la requête en fonction de l'heure de la journée.

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

Installez ce rappel dans 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 "Résultats de recherche d'images/Web prêts"

Ces rappels sont appelés immédiatement avant que le JavaScript de l'élément de recherche n'affiche les promotions et les résultats. Un cas d'utilisation typique serait un rappel qui affiche des promotions et des résultats dans un style qui ne peut pas être spécifié avec une personnalisation normale.

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

gname

Chaîne d'identification de l'élément de recherche

query

requête ayant généré ces résultats

promos

un tableau d'objets de promotion correspondant aux promotions associées à la requête de l'utilisateur. Consultez la définition de l'objet promotion.

results

, tableau d'objets de résultat. Consultez la définition de l'objet de résultat.

div

une balise div HTML positionnée dans le DOM où l'élément de recherche placerait normalement les promotions et les résultats de recherche. Normalement, le JavaScript de l'élément de recherche gère le remplissage de cette div, mais ce rappel peut choisir d'arrêter le rendu automatique des résultats et d'utiliser ce div pour afficher lui-même les résultats.

Si ce rappel renvoie une valeur true, le code JavaScript de l'élément de recherche passe à son travail de pied de page.

Exemple de rappel "Résultats disponibles"

L'exemple de rappel resultsReady dans Exemple de rappel "Résultats prêts" remplace la présentation par défaut des promotions et des résultats par un remplacement très 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>

Rappel de rendu des résultats de recherche d'images/Web

Ces rappels sont invoqués juste avant que le JavaScript de l'élément de recherche n'affiche le pied de page. Par exemple, un rappel qui ajoute du contenu de résultat que l'élément de recherche n'affiche pas, comme une case à cocher Enregistrer ou des informations qui ne sont pas rendues automatiquement, ou un rappel qui ajoute des boutons Pour en savoir plus.

Si un rappel de résultats affichés a besoin d'informations qui se trouvaient dans les paramètres promos et results du rappel de résultats prêts, il peut les transmettre entre eux, comme ceci :

callback(gname, query, promoElts, resultElts);

gname

Chaîne d'identification de l'élément de recherche

query

Chaîne de recherche

.

promoElts

, tableau des éléments DOM contenant les promotions.

resultElts

 : tableau des éléments DOM contenant les résultats.

Aucune valeur n'est renvoyée.

Exemple de rappel de rendu des résultats

L'exemple de rappel resultsRendered dans Exemple de rappel de rendu des résultats ajoute une case à cocher Keep (Conserver) factice à chaque promotion et résultat.

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 le rappel des résultats affichés a besoin d'informations qui ont été transmises au rappel des résultats prêts, il peut transmettre ces données entre les rappels. L'exemple suivant montre l'une des nombreuses façons de transmettre une valeur de note de richSnippet du rappel "résultats prêts" au rappel "résultats affichés".

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>

Exemple de rappel de rendu des résultats : ouverture de types de fichiers spécifiques dans un nouvel onglet/une nouvelle fenêtre

L'exemple de rappel suivant peut modifier les liens des résultats de recherche après leur affichage pour ouvrir un fichier spécifique dans un nouvel onglet ou une nouvelle page au lieu de la fenêtre actuelle (par exemple, un fichier PDF, Excel ou Word). Cela améliore l'expérience de navigation lorsque les utilisateurs ne souhaitent pas ouvrir un fichier dans la même fenêtre et quitter la page de résultats.

Cet exemple de rappel identifie les liens PDF dans les résultats de recherche et définit l'attribut target="_blank" sur les liens PDF afin qu'ils s'ouvrent dans un nouvel onglet. Un MutationObserver est utilisé pour gérer dynamiquement les nouveaux résultats si la page est actualisée. Remarque : Vous pouvez remplacer .pdf dans handleSearchResults par n'importe quel autre type de fichier selon vos besoins.

Cet exemple de rappel ne fonctionne pas avec les mises en page Google Hosted et 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>

Autres exemples de rappel

Vous trouverez d'autres exemples de rappel dans le document Autres exemples de rappel.

Propriétés de la promotion et du résultat

En utilisant la notation JSDoc, voici les propriétés des objets promotion et result. Nous listons ici toutes les propriétés qui peuvent être présentes. La présence de nombreuses propriétés dépend des détails de la promotion ou du résultat de recherche.

{
  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 dans results a le type lâche d'un tableau d'objets. Les valeurs des entrées de ce tableau sont contrôlées par les données structurées trouvées sur la page Web pour chaque résultat de recherche. Par exemple, un site Web d'avis peut inclure des données structurées qui ajoutent cette entrée de tableau à richSnippet :

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

API Programmable Search Element Control (V2)

L'objet google.search.cse.element publie les fonctions statiques suivantes :

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