Aller au contenu principal
Version : Stable (v4.x)

Bien démarrer avec la v4

Traduction Bêta Non Officielle

Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →

Introduction​

DocSearch v4 représente une amélioration significative par rapport aux versions précédentes, offrant une accessibilité accrue, une meilleure réactivité et une expérience de recherche optimisée pour votre documentation. Basé sur Algolia Autocomplete, DocSearch v4 garantit une intégration transparente utilisée par les principaux sites de documentation mondiaux.

Installation​

Vous recherchez la documentation de l'API Composable ? Elle est disponible ici.

Les paquets DocSearch sont disponibles sur le registre npm.

Utilisateurs de Docusaurus​

Si votre site de documentation utilise Docusaurus, utilisez @docsearch/docusaurus-adapter pour bénéficier des dernières fonctionnalités de DocSearch (y compris les nouvelles capacités d'Ask AI comme le support de panneau latéral), tout en conservant @docusaurus/preset-classic.

yarn add @docsearch/js@4
# or with npm
npm install @docsearch/js@4

Without package manager​

Include CSS in your website's <head>

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@4" />

And the JavaScript at the end of your <body>:

<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@4"></script>

Optimiser les performances de la première requête​

Améliorez l'expérience de recherche initiale de vos utilisateurs avec preconnect, voir la section Optimisation des performances ci-dessous

Mise en œuvre​

DocSearch requires a dedicated container in your HTML

<div id="docsearch"></div>

Initialize DocSearch by passing your container:

import docsearch from '@docsearch/js';

import '@docsearch/css';

docsearch({
  container: '#docsearch',
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
});

DocSearch generates an accessible, fully-functional search input for you automatically.

Test rapide (sans identifiants)​

Pour tester DocSearch immédiatement sans vos propres identifiants, utilisez notre configuration de démonstration :

docsearch({
  appId: 'PMZUYBQDAK',
  apiKey: '24b09689d5b4223813d9b8e48563c8f6',
  indexName: 'docsearch',
  askAi: 'askAIDemo',
});

Ou utilisez notre nouveau DocSearch Playground dédié

Utiliser DocSearch avec Ask AI​

DocSearch v4 introduit la prise en charge d'Ask AI, la fonctionnalité de recherche avancée d'Algolia propulsée par l'IA. Ask AI améliore l'expérience utilisateur en fournissant des réponses intelligentes et contextuellement pertinentes directement à partir de votre documentation. Vous pouvez également utiliser le même objet de configuration askAi pour router les conversations via Agent Studio.

Pour activer Ask AI, vous pouvez ajouter votre ID Algolia Assistant sous forme de chaîne, ou utiliser un objet pour une configuration plus avancée (comme spécifier un index différent, des identifiants, des paramètres de recherche ou activer Agent Studio) :

docsearch({
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
  askAi: 'YOUR_ALGOLIA_ASSISTANT_ID',
});

  • Utilisez la forme chaîne pour une configuration simple.

  • Utilisez la forme objet pour personnaliser l'index, les identifiants ou les filtres utilisés par Ask AI.

  • La fonctionnalité de questions suggérées se configure dans le Dashboard au niveau de la section Ask AI.

Utilisation d'Agent Studio avec DocSearch​

Pour utiliser Algolia Agent Studio comme backend de conversation, définissez agentStudio: true à l'intérieur de l'objet askAi.

docsearch({
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
  askAi: {
    assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
    agentStudio: true,
    searchParameters: {
      YOUR_INDEX_NAME: {
        filters: 'type:content AND language:en',
        attributesToRetrieve: ['title', 'content', 'url'],
        restrictSearchableAttributes: ['title', 'content'],
        distinct: 'url',
      },
    },
  },
});

  • agentStudio se configure à l'intérieur de askAi, et non comme une propriété de premier niveau de DocSearch.

  • Lorsque agentStudio: true, searchParameters doit être indexé par nom d'index.

  • Les paramètres de recherche d'Agent Studio prennent en charge filters, attributesToRetrieve, restrictSearchableAttributes et distinct.

Filtrage des résultats de recherche​

Recherche par mot-clé​

Si votre site utilise les balises méta DocSearch ou si vous avez ajouté des variables personnalisées à votre configuration, vous pourrez utiliser l'option facetFilters pour limiter vos résultats de recherche à une facet

Cela permet de limiter la portée de la recherche à une langue ou une version spécifique.

docsearch({
  searchParameters: {
    facetFilters: ['language:en', 'version:1.0.0'],
  },
});

Ask AI​

Le filtrage s'applique également lors de l'utilisation d'Ask AI. Cela permet de limiter la portée de la recherche du LLM aux résultats pertinents uniquement.

info

Nous recommandons d'utiliser l'option facetFilters lors de l'utilisation d'Ask AI avec plusieurs langues ou tout index multi-facettes.

docsearch({
  askAi: {
    assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
    searchParameters: {
      facetFilters: ['language:en', 'version:1.0.0'],
    },
  },
});
astuce

Vous pouvez utiliser facetFilters: ['type:content'] pour vous assurer qu'Ask AI n'utilise que les enregistrements où l'attribut type est content (c'est-à-dire uniquement les enregistrements qui contiennent effectivement du contenu). Cela est utile si votre index contient des enregistrements pour la navigation, des métadonnées ou d'autres types sans contenu.

Envoi d'événements​

Vous pouvez envoyer des événements de recherche à votre index DocSearch en passant le paramètre insights lors de la création de votre instance DocSearch.

docsearch({
   // other options
+  insights: true,
});

Optimisation des performances​

Préconnexion (Preconnect)​

Améliorez la vitesse de chargement de votre première requête de recherche en ajoutant cet extrait dans la section <head> de votre site :

<link rel="preconnect" href="https://YOUR_APP_ID-dsn.algolia.net" crossorigin />

Cela aide le navigateur à établir rapidement une connexion avec Algolia, améliorant l'expérience utilisateur, en particulier sur les appareils mobiles.