Chaque extension doit disposer d'une documentation qui explique aux utilisateurs ce que fait l'extension et comment l'utiliser.
La documentation minimale requise est cet ensemble de trois fichiers de démarque :
-
PREINSTALL.md -
POSTINSTALL.md -
CHANGELOG.md
De plus, vous devriez également envisager de produire :
- Un fichier
READMEpour le référentiel public de l'extension. - Tutoriels, guides et références plus longs publiés sur votre propre site Web et liés dans votre
PREINSTALL.md.
Pour découvrir quelques bonnes pratiques ainsi que la formulation et la structure courantes, nous vous recommandons de consulter les fichiers disponibles avec les extensions Firebase officielles .
Création d'un fichier README
Votre répertoire d'extension peut éventuellement contenir un README. Notez que la commande firebase ext:dev:init n'en génère pas automatiquement pour vous.
Cependant, la CLI Firebase prend en charge la commande pratique suivante pour générer automatiquement un fichier README contenant le contenu extrait de votre fichier extension.yaml et de votre fichier PREINSTALL.md :
firebase ext:info ./path/to/extension --markdown > README.md
Tous les fichiers README pour les extensions officielles Firebase sont générés à l'aide de cette commande.
Ajouter des informations d'installation
Après avoir écrit ou généré un fichier README, ajoutez-y les informations d'installation. Vous pouvez utiliser l'extrait suivant comme modèle :
--- ## 🧩 Install this extension ### Console [][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) ---
Ecrire un fichier PREINSTALL
Le fichier PREINSTALL est la présentation de votre extension, une sorte de page "marketing".
Quel est le contenu de ce fichier ?
- Description complète des fonctionnalités de votre extension
- Liste des prérequis, tels que la configuration d'une base de données ou l'accès à un service non Google ( exemple )
- Brève description de toutes les tâches de pré-installation et de leurs instructions
- Brève description de toutes les tâches post-installation ( exemple ) (les instructions détaillées se trouvent dans
POSTINSTALL) - Brève description de toutes les implications en matière de facturation (commencer par un texte passe-partout )
Où ce contenu s'affiche-t-il pour l'utilisateur ?
- Sur la page de l'extension sur extensions.dev .
- Votre référentiel de code source pour votre extension (dans le répertoire de l'extension)
- Dans le cadre du README de l'extension (si vous utilisez la CLI Firebase
--markdown > README.md
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 aux paramètres s'affichent avec les valeurs réelles.
Quelles sont les bonnes pratiques ?
- Conservez l'intégralité du contenu du fichier
PREINSTALLsur moins d'une page , si possible. - Fournir le niveau de détail qu'un utilisateur final doit absolument connaître avant d'installer l'extension
- Mettez des instructions détaillées dans le fichier
POSTINSTALLou dans d'autres fichiers supplémentaires - Mentionnez brièvement si vous fournissez d'autres outils ou scripts pour prendre en charge l'extension
Nous vous recommandons d’utiliser autant que possible le texte standard suivant, selon le cas pour votre extension. Nous avons fourni quelques exemples, mais le point le plus important est de garantir que tous les services facturés par Google et non Google sont répertoriés.
Vous pouvez utiliser les ressources suivantes pour trouver les détails corrects des prix des produits :
Pour toutes les extensions, incluez cette section pour aider vos utilisateurs à comprendre les implications en matière 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>.
Ecriture d'un fichier POSTINSTALL
Le fichier POSTINSTALL est la page d'instructions post-installation détaillée de votre extension.
Quel est le contenu de ce fichier ?
- Instructions détaillées pour toutes les tâches post-installation requises , comme la configuration des règles de sécurité Firebase ou l'ajout de code côté client ( exemple )
- Instructions génériques expliquant comment essayer immédiatement l'extension installée (par exemple, "allez sur la console, puis faites ceci")
- Informations de base sur la façon de déclencher l'extension, en particulier pour les extensions déclenchées par une requête HTTP
- Brèves instructions sur la façon de surveiller l'extension installée (commencer par un texte passe-partout )
Où ce contenu s'affiche-t-il pour l'utilisateur ?
Dans la console Firebase après qu'un utilisateur a installé votre extension (dans la fiche détaillée de l'extension installée)
- Assurez-vous de revoir l'affichage du contenu
POSTINSTALLen installant votre extension dans un projet réel .
- Assurez-vous de revoir l'affichage du contenu
Votre référentiel de code source pour 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 contenu POSTINSTALL est affiché dans la console Firebase, les valeurs réelles s'affichent plutôt que les références de paramètres ou de variables. Découvrez ci-dessous comment référencer des paramètres et des variables dans votre fichier POSTINSTALL .
Quelles sont les bonnes pratiques ?
- Gardez le contenu complet du fichier
POSTINSTALLconcis, mais descriptif. - Divisez le contenu en utilisant des titres pour séparer les tâches ou les concepts distincts.
- Envisagez de publier des instructions détaillées pour un flux de travail ou une tâche spécifique sur votre site Web ( exemple ) ou dans des fichiers de démarques supplémentaires dans le référentiel d'extensions ( exemple ).
- Paramètres de référence et variables liées aux fonctions afin que l'utilisateur voie leurs valeurs configurées dans le contexte des instructions
Référencer des paramètres et des variables
Après l'installation, la console Firebase 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.
Accédez aux valeurs des paramètres configurés 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 dans votre fichier POSTINSTALL uniquement . Firebase prend en charge ces variables afin que vous puissiez plus facilement fournir des conseils à vos utilisateurs après l'installation. Ils ne peuvent être utilisés que dans le fichier POSTINSTALL car les valeurs de ces variables ne sont disponibles qu'après l'installation.
Dans ce tableau, function-name est la valeur du champ name dans l'objet 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} | ||
| Lieu 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é : Exemple de valeur : | |
${function: function-name .url} (applicable uniquement pour les fonctions HTTP) | ||
| URL de la fonction finale déployée , à laquelle le code client peut effectuer des requêtes HTTP | Format généralisé : Exemple de valeur : | |
Nous vous recommandons d’utiliser autant que possible le texte standard suivant, selon le cas pour votre extension.
Pour toutes les extensions, incluez la section suivante pour 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 comment déclencher une extension
Dans la documentation utilisateur de votre extension, vous devez expliquer à vos utilisateurs comment déclencher votre extension. Ces instructions peuvent être aussi détaillées que vous le jugez nécessaire, mais gardez à l'esprit les meilleures pratiques pour écrire un fichier POSTINSTALL . Pour savoir comment fournir ces instructions, développez la section ci-dessous qui s'applique à votre extension.
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 déclenchant l'extension directement dans la console Firebase, en particulier pour leurs tests initiaux de votre extension. Par exemple, supposons que votre extension crée un nouveau document Cloud Firestore chaque fois qu'un nouvel utilisateur d'authentification Firebase est créé. Vous pouvez demander à vos utilisateurs de tester une instance installée de votre extension en ajoutant manuellement un nouvel utilisateur d'authentification dans la console. Ils peuvent ensuite observer le nouveau document créé dans la section Cloud Firestore 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 diriger 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 (reportez-vous à l' extension Distributed Counter pour un exemple).
Afin 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 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 dans ce format :ext- extension-instance-id - function-name .
Les puces suivantes sont des suggestions de texte passe-partout à inclure dans le fichier POSTINSTALL de votre extension. Après l'installation, la console Firebase affiche le contenu du fichier POSTINSTALL et remplit ces références avec les valeurs réellement configurées pour 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
onRequestTo 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}`**.
Ecrire un fichier CHANGELOG
Quel contenu contient ce fichier ?
Chaque extension doit avoir 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 le formatage Markdown de votre choix.
L'exemple suivant est un extrait d'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 console Firebase et la CLI, lorsque les utilisateurs effectuent une mise à niveau vers de nouvelles versions de votre extension. La console Firebase et la CLI affichent uniquement les modifications qui prendraient effet si l'utilisateur terminait la mise à niveau.
- Le référentiel du code source de votre extension (dans le répertoire de l'extension).