Créer une documentation utilisateur pour votre extension

Chaque extension doit être accompagnée d'une documentation expliquant aux utilisateurs ce qu'elle fait et comment l'utiliser.

La documentation minimale requise est cet ensemble de trois fichiers Markdown :

• PREINSTALL.md
• POSTINSTALL.md
• CHANGELOG.md

De plus, vous devriez également envisager de produire les éléments suivants :

• Un fichier README pour le dépôt public de l'extension.
• Des tutoriels, des guides et des références plus longs publiés sur votre propre site Web et liés dans votre PREINSTALL.md.

Pour découvrir certaines bonnes pratiques, ainsi que des expressions et une structure courantes, nous vous recommandons de consulter les fichiers disponibles avec les extensions Firebaseofficielles.

Créer un fichier README

Votre répertoire d'extension peut éventuellement contenir un fichier README. Notez que la firebase ext:dev:init commande n'en génère pas automatiquement.

Toutefois, la Firebase CLI est compatible avec la commande pratique suivante pour générer automatiquement un fichier README contenant du contenu extrait de votre extension.yaml fichier et de votre PREINSTALL.md fichier :

firebase ext:info ./path/to/extension --markdown > README.md

Tous les fichiers README des extensions Firebaseofficielles sont générés à l'aide de cette commande.

Ajouter des informations sur l'installation

Une fois que vous avez écrit ou généré un fichier README, ajoutez-y des informations sur l'installation. Vous pouvez utiliser l'extrait de code suivant comme modèle :

---

## 🧩 Install this extension

### Console

[![Install this extension in your Firebase project](https://www.gstatic.com/mobilesdk/210513_mobilesdk/install-extension.png "Install this extension in your Firebase project")][install-link]

[install-link]: https://console.firebase.google.com/project/_/extensions/install?ref=publisher_id/extension_name

### Firebase CLI

```bash
firebase ext:install publisher_id/extension_name --project=[your-project-id]
```

> Learn more about installing extensions in the Firebase Extensions documentation:
> [console](https://firebase.google.com/docs/extensions/install-extensions?platform=console),
> [CLI](https://firebase.google.com/docs/extensions/install-extensions?platform=cli)

---

Écrire un fichier PREINSTALL

Le fichier PREINSTALL est la présentation de votre extension, une sorte de page "marketing".

Quel contenu contient ce fichier ?

• Description complète des fonctionnalités de votre extension
• Liste des prérequis, tels que la configuration de la base de données ou l'accès à un service non Google service (exemple)
• Brève description des tâches de préinstallation et de leurs instructions
• Brève description des tâches post-installation (exemple) (les instructions détaillées sont disponibles dans POSTINSTALL)
• Brève description des implications en termes de facturation (commencez par un texte standard)

Où ce contenu s'affiche-t-il pour l'utilisateur ?

Console Firebase">

Contenu de préinstallation dans la Firebase console

Console Firebase">

• Sur la page de l'extension sur extensions.dev.
• Dans le dépôt de code source de votre extension (dans le répertoire de l'extension)
• Dans le fichier README de l'extension (si vous utilisez le Firebase CLI --markdown > README.md flag)

Les fichiers PREINSTALL ne peuvent pas accéder aux valeurs des paramètres de l'extension. Vous ne devez donc pas vous attendre à ce que les références de paramètres soient affichées avec des valeurs réelles.

Quelles bonnes pratiques suivre ?

• Si possible, limitez le contenu complet du fichier PREINSTALL à une seule page,
• Fournissez le niveau de détail dont un utilisateur final a absolument besoin avant d'installer l'extension.
• Placez les instructions détaillées dans le fichier POSTINSTALL ou dans d'autres fichiers supplémentaires.
• Indiquez brièvement si vous fournissez d'autres outils ou scripts pour prendre en charge l' extension.

Texte standard utile PREINSTALL

Nous vous recommandons d'utiliser autant que possible le texte standard suivant, le cas échéant pour votre extension. Nous avons fourni quelques exemples, mais le plus important est de vous assurer que tous les services facturés par Google et non Google sont listés.

Vous pouvez utiliser les ressources suivantes pour trouver les informations correctes sur les tarifs des produits :

• Liste des prix des produits Google Cloud
• Présentation des tarifs Firebase

Pour toutes les extensions, incluez cette section afin d'aider vos utilisateurs à comprendre les implications en termes de facturation :

Billing

This extension uses other Firebase or Google Cloud services which may have
  associated charges:

*   <list Google services / products that your extension uses>
*   <list Firebase services that your extension uses>
*   Cloud Secret Manager <if the extension uses secret params>
*   Cloud Functions

When you use Firebase Extensions, you're only charged for the underlying
resources that you use. A paid-tier billing plan is only required if the
extension uses a service that requires a paid-tier plan, for example calling to
a Google Cloud API or making outbound network requests to non-Google services.
All Firebase services offer a no-cost tier of usage.
[Learn more about Firebase billing.](https://firebase.google.com/pricing)

<Applicable info about billing implications for non-Google services, such as:>
Usage of this extension also requires you to have a <non-Google-service> account.
You are responsible for any associated costs with your usage of <non-Google-service>.

Écrire un fichier POSTINSTALL

Le fichier POSTINSTALL est la page d'instructions détaillée de votre extension après l'installation.

Quel contenu contient ce fichier ?

• Instructions détaillées pour toutes les tâches obligatoires après l'installation, comme la configuration des règles de sécurité Firebase ou l'ajout de code côté client (exemple)
• Instructions génériques pour essayer immédiatement l'extension installée (par exemple, "accédez à la console, puis procédez comme suit")
• Informations de base sur le déclenchement de l'extension, en particulier pour les extensions déclenchées par des requêtes HTTP
• Brèves instructions pour surveiller l'extension installée (commencez par un texte standard)

Où ce contenu s'affiche-t-il pour l'utilisateur ?

Console Firebase">

Contenu post-installation dans la Firebase console

Console Firebase">

• Dans la console Firebase après qu'un utilisateur a installé votre extension (dans la fiche d'informations de l'extension installée )

  • Assurez-vous de vérifier l'affichage du contenu POSTINSTALL en installant votre extension dans un projet réel.

• Dans le dépôt de code source de votre extension (dans le répertoire de l'extension)

Les fichiers POSTINSTALL peuvent accéder aux valeurs des paramètres et à plusieurs variables liées aux fonctions de l'extension. Lorsque le POSTINSTALL contenu s'affiche dans la Firebase console, les valeurs réelles s'affichent plutôt que les références de paramètres ou de variables. Pour en savoir plus sur la façon de référencer des paramètres et variables dans votre fichier POSTINSTALL, consultez la section ci-dessous.

Quelles bonnes pratiques suivre ?

• Limitez le contenu complet du fichier POSTINSTALL à un texte concis, mais descriptif.
• Divisez le contenu en sections à l'aide de titres pour séparer les tâches ou les concepts distincts.
• Envisagez de publier des instructions détaillées pour un workflow ou une tâche spécifique sur votre site Web (exemple) ou dans des fichiers Markdown supplémentaires dans le dépôt d'extension (exemple).
• Référencez les paramètres et les variables liées aux fonctions afin que l'utilisateur voie les valeurs configurées dans le contexte des instructions .

Référencer des paramètres et des variables

Après l'installation, la Firebase console affiche le contenu du fichier POSTINSTALL de l'extension. Si vous référencez des paramètres et des variables liées aux fonctions (voir le tableau ci-dessous) dans votre fichier POSTINSTALL, la console remplit ces références avec les valeurs réelles de l'instance installée.

Conseil : Pour les valeurs qui peuvent être longues (comme un chemin d'accès à une base de données ou une URL de fonction), référencez le paramètre ou la variable à la fin des phrases et des sections. Cette bonne pratique facilite la lecture des phrases dans la console Firebase lorsque le contenu du fichier POSTINSTALL est affiché avec des valeurs réelles.

Accédez aux valeurs de paramètres configurées dans le fichier POSTINSTALL à l'aide de la syntaxe suivante : ${param:PARAMETER_NAME}

Vous pouvez également référencer les variables liées aux fonctions suivantes uniquement dans votre fichier POSTINSTALL. Firebase est compatible avec ces variables afin que vous puissiez plus facilement fournir des conseils à vos utilisateurs après l'installation. Elles ne sont disponibles que dans le fichier POSTINSTALL car les valeurs de ces variables ne sont disponibles qu'après l'installation.

Dans ce tableau, function-name correspond à la valeur du name champ dans l'objet de ressource de la fonction dans extension.yaml.

Référence pour la variable liée à la fonction	Description	Valeur de la variable (remplie automatiquement par Firebase après l'installation de l'extension)
${function:function-name.location}
	Emplacement où la fonction est déployée	Exemple de valeur: us-central1
${function:function-name.name}
	Nom de la fonction déployée finale, qui inclut l' ID d'instance de l'extension	Format généralisé : ext-extension-instance-id-function-name Exemple de valeur : ext-my-awesome-extension-6m31-yourFunctionName
${function:function-name.url} (ne s'applique qu'aux fonctions HTTP)
	URL de la fonction déployée finale, à laquelle le code client peut envoyer des requêtes HTTP	Format généralisé : https://deployment-location-project-id.cloudfunctions.net/name-of-final-deployed-function Exemple de valeur : https://us-central1-project-123.cloudfunctions.net/ext-my-awesome-extension-6m31-yourFunctionName

Texte standard utile POSTINSTALL

Nous vous recommandons d'utiliser autant que possible le texte standard suivant, le cas échéant pour votre extension.

Pour toutes les extensions, incluez la section suivante afin d'aider vos utilisateurs à surveiller leur extension installée :

Monitoring

As a best practice, you can
[monitor the activity](https://firebase.google.com/docs/extensions/manage-installed-extensions_community#monitor)
of your installed extension, including checks on its health, usage, and logs.

Documenter le déclenchement d'une extension

Dans la documentation utilisateur de votre extension, vous devez indiquer à vos utilisateurs comment la déclencher. Ces instructions peuvent être aussi détaillées que vous le jugez nécessaire, mais gardez à l'esprit les bonnes pratiques pour écrire un POSTINSTALL fichier. Pour obtenir des conseils sur la façon de fournir ces instructions, développez la section ci-dessous qui s'applique à votre extension.

Extensions déclenchées par des événements en arrière-plan

Vos utilisateurs peuvent déclencher une extension déclenchée par un événement en arrière-plan de différentes manières, en fonction des produits concernés.

Apporter des modifications directement dans la console

Vous pouvez demander à vos utilisateurs d'apporter des modifications qui déclenchent l'extension directement dans la Firebase console, en particulier pour les tests initiaux de votre extension. Supposons, par exemple, que votre extension crée un nouveau document Cloud Firestore chaque fois qu'un nouvel utilisateur Firebase Authentication est créé. Vous pouvez demander à vos utilisateurs de tester une instance installée de votre extension en ajoutant manuellement un nouvel utilisateur Authentication dans la console. Ils peuvent ensuite observer le nouveau document créé dans la Cloud Firestore section de la console.

Ajouter du code côté client

Le cas échéant, vous pouvez également indiquer à vos utilisateurs comment ajouter du code côté client pour déclencher votre extension. Vous devez rediriger les utilisateurs vers la documentation officielle des API qu'ils devront utiliser. Vous pouvez également inclure des exemples d'applications ou des exemples de clients compilés pour aider vos utilisateurs à intégrer l'extension dans leur application (consultez l' extension _Distributed Counter_ pour obtenir un exemple).

Extensions déclenchées par des requêtes HTTP

Pour que vos utilisateurs puissent déclencher une fonction déclenchée par une requête HTTP (et donc l' extension), vous devez leur fournir le nom de la fonction déployée ou son URL.

Le nom de la fonction déployée finale n'est pas le même que le name que vous avez spécifié dans l'objet de ressource de la fonction dans extension.yaml. Pour prendre en charge plusieurs installations de la même extension dans un projet, Firebase renomme la fonction au format suivant : ext-extension-instance-id-function-name.

Les puces suivantes sont suggérées comme texte standard à inclure dans le fichier POSTINSTALL de votre extension. Après l'installation, la Firebase console affiche le contenu du fichier POSTINSTALL et remplit ces références avec les valeurs configurées réelles de l'instance installée. Par exemple, si vous avez défini une fonction nommée yourFunction, vous pouvez inclure les éléments suivants (le cas échéant) :

• Pour les fonctions HTTP onRequest

  To trigger this extension, make a request to or visit the following URL:
  **`${function:yourFunction.url}`**.
  

• Pour les fonctions HTTP appelables (onCall)

  This extension is implemented as an HTTP callable function. To call it from your client app,
  follow the instructions in the
  [callable functions documentation](https://firebase.google.com/docs/functions/callable#call_the_function).
  The name of the function to call is **`${function:yourFunction.name}`**,
  and its region is **`${function:yourFunction.location}`**.
  

Important : Avant que vos utilisateurs puissent utiliser une extension déclenchée par une requête HTTP, ils doivent rendre les fonctions déployées pour l’extension accessibles au public. Les instructions détaillées à fournir à vos utilisateurs se trouvent dans les exemples de texte standard ci-dessus.

Écrire un fichier CHANGELOG

Quel contenu contient ce fichier ?

Chaque extension doit comporter un fichier CHANGELOG.md qui documente les modifications incluses dans chaque nouvelle version de votre extension que vous publiez. Placez chaque version sous un en-tête de niveau 2 (##). Sinon, vous pouvez utiliser la mise en forme Markdown de votre choix.

L'exemple suivant est un extrait de l'une des extensions officielles :

## Version 0.1.3

feature - Support deletion of directories (issue #148).

## Version 0.1.2

feature - Add a new param for recursively deleting subcollections in Cloud
Firestore (issue #14).

fixed - Fixed "cold start" errors experienced when the extension runs after a
period of inactivity (issue #48).

## Version 0.1.1

Initial release of the _Delete User Data_ extension.

Où ce contenu s'affiche-t-il pour l'utilisateur ?

• Dans la Firebase console et la CLI, lorsque les utilisateurs passent à de nouvelles versions de votre extension. La console Firebase et la CLI n'affichent que les modifications qui prendraient effet si l'utilisateur effectuait la mise à niveau.
• Dans le dépôt de code source de votre extension (dans le répertoire de l'extension).