Jede Erweiterung muss über eine Dokumentation verfügen, die den Benutzern erklärt, was die Erweiterung bewirkt und wie sie verwendet wird.
Die erforderliche Mindestdokumentation besteht aus diesem Satz von drei Markdown-Dateien:
-
PREINSTALL.md -
POSTINSTALL.md -
CHANGELOG.md
Darüber hinaus sollten Sie Folgendes in Betracht ziehen:
- Eine
README-Datei für das öffentliche Repository der Erweiterung. - Längere Tutorials, Leitfäden und Referenzen werden auf Ihrer eigenen Website veröffentlicht und in Ihrer
PREINSTALL.mdverlinkt.
Um einige Best Practices sowie gängige Formulierungen und Strukturen kennenzulernen, empfehlen wir einen Blick auf die mit den offiziellen Firebase-Erweiterungen verfügbaren Dateien.
Erstellen einer README-Datei
Ihr Erweiterungsverzeichnis kann optional eine README-Datei enthalten. Beachten Sie, dass der firebase ext:dev:init nicht automatisch einen generiert.
Die Firebase-CLI unterstützt jedoch den folgenden praktischen Befehl zum automatischen Generieren einer README Datei mit Inhalten, die aus Ihrer Datei extension.yaml und Ihrer Datei PREINSTALL.md abgerufen wurden:
firebase ext:info ./path/to/extension --markdown > README.md
Mit diesem Befehl werden alle README-Dateien für die offiziellen Firebase-Erweiterungen generiert.
Fügen Sie Installationsinformationen hinzu
Nachdem Sie eine README-Datei geschrieben oder generiert haben, fügen Sie ihr Installationsinformationen hinzu. Sie können den folgenden Ausschnitt als Vorlage verwenden:
--- ## 🧩 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) ---
Schreiben einer PREINSTALL Datei
Die PREINSTALL Datei ist die Übersicht Ihrer Erweiterung, eine Art „Marketing“-Seite.
Welchen Inhalt enthält diese Datei?
- Umfassende Beschreibung der Funktionalität Ihrer Erweiterung
- Liste der Voraussetzungen, z. B. Datenbankeinrichtung oder Zugriff auf einen Nicht-Google-Dienst ( Beispiel )
- Kurze Beschreibung aller Vorinstallationsaufgaben und deren Anweisungen
- Kurze Beschreibung aller Aufgaben nach der Installation ( Beispiel ) (ausführliche Anweisungen finden Sie in
POSTINSTALL) - Kurze Beschreibung aller Auswirkungen auf die Abrechnung (beginnen Sie mit dem Standardtext )
Wo wird dieser Inhalt dem Benutzer angezeigt?
- Auf der Seite der Erweiterung auf extensions.dev .
- Ihr Quellcode-Repo für Ihre Erweiterung (im Erweiterungsverzeichnis)
- Als Teil der README-Datei der Erweiterung (wenn Sie die Firebase-CLI verwenden
--markdown > README.mdFlag
PREINSTALL Dateien können nicht auf die Parameterwerte für die Erweiterung zugreifen, daher sollten Sie nicht erwarten, dass Parameterverweise mit tatsächlichen Werten gerendert werden.
Was sind einige Best Practices?
- Beschränken Sie den gesamten Inhalt der
PREINSTALLDatei nach Möglichkeit auf weniger als eine Seite - Geben Sie den Detaillierungsgrad an, den ein Endbenutzer unbedingt wissen muss, bevor er die Erweiterung installiert
- Fügen Sie detaillierte Anweisungen in die
POSTINSTALLDatei oder andere Zusatzdateien ein - Erwähnen Sie kurz, ob Sie andere Tools oder Skripte zur Unterstützung der Erweiterung bereitstellen
Wir empfehlen, so viel wie möglich des folgenden Textbausteins zu verwenden, sofern er für Ihre Erweiterung relevant ist. Wir haben einige Beispiele bereitgestellt, aber der wichtigste Punkt ist, sicherzustellen, dass alle von Google und nicht von Google abgerechneten Dienste aufgelistet sind.
Sie können die folgenden Ressourcen verwenden, um die korrekten Produktpreisdetails zu finden:
Fügen Sie für alle Erweiterungen diesen Abschnitt hinzu, damit Ihre Benutzer die Auswirkungen auf die Abrechnung verstehen:
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>.
Schreiben einer POSTINSTALL Datei
Die POSTINSTALL Datei ist die detaillierte Anleitungsseite Ihrer Erweiterung nach der Installation.
Welchen Inhalt enthält diese Datei?
- Detaillierte Anweisungen für alle erforderlichen Aufgaben nach der Installation, wie das Einrichten von Firebase-Sicherheitsregeln oder das Hinzufügen von clientseitigem Code ( Beispiel )
- Allgemeine Anweisungen zum sofortigen Ausprobieren der installierten Erweiterung (z. B. „Gehen Sie zur Konsole und führen Sie dies aus“).
- Grundlegende Informationen zum Auslösen der Erweiterung, insbesondere für durch HTTP-Anfragen ausgelöste Erweiterungen
- Kurze Anleitung zur Überwachung der installierten Erweiterung (beginnen Sie mit dem Textbaustein )
Wo wird dieser Inhalt dem Benutzer angezeigt?
In der Firebase-Konsole, nachdem ein Benutzer Ihre Erweiterung installiert hat (in der Detailkarte der installierten Erweiterung)
- Überprüfen Sie unbedingt die Anzeige des
POSTINSTALLInhalts, indem Sie Ihre Erweiterung in einem tatsächlichen Projekt installieren .
- Überprüfen Sie unbedingt die Anzeige des
Ihr Quellcode-Repo für Ihre Erweiterung (im Erweiterungsverzeichnis)
POSTINSTALL Dateien können auf die Parameterwerte und mehrere funktionsbezogene Variablen für die Erweiterung zugreifen. Wenn der Inhalt POSTINSTALL in der Firebase-Konsole angezeigt wird, werden die tatsächlichen Werte und nicht die Parameter- oder Variablenverweise angezeigt. Erfahren Sie weiter unten mehr darüber, wie Sie Parameter und Variablen in Ihrer POSTINSTALL Datei referenzieren.
Was sind einige Best Practices?
- Halten Sie den gesamten Inhalt der
POSTINSTALLDatei prägnant, aber beschreibend. - Unterteilen Sie den Inhalt mithilfe von Überschriften, um bestimmte Aufgaben oder Konzepte aufzuschlüsseln.
- Erwägen Sie die Veröffentlichung detaillierter Anweisungen für einen bestimmten Arbeitsablauf oder eine bestimmte Aufgabe auf Ihrer Website ( Beispiel ) oder in zusätzlichen Markdown-Dateien im Erweiterungs-Repository ( Beispiel ).
- Referenzieren Sie Parameter und funktionsbezogene Variablen , damit der Benutzer ihre konfigurierten Werte im Kontext der Anweisungen sieht
Referenzieren von Parametern und Variablen
Nach der Installation zeigt die Firebase-Konsole den Inhalt der POSTINSTALL Datei der Erweiterung an. Wenn Sie in Ihrer POSTINSTALL Datei auf Parameter und funktionsbezogene Variablen verweisen (siehe Tabelle unten), füllt die Konsole diese Verweise mit den tatsächlichen Werten für die installierte Instanz.
Greifen Sie mit der folgenden Syntax auf konfigurierte Parameterwerte in der POSTINSTALL Datei zu:${param: PARAMETER_NAME }
Sie können die folgenden funktionsbezogenen Variablen auch nur in Ihrer POSTINSTALL Datei referenzieren. Firebase unterstützt diese Variablen, sodass Sie Ihren Benutzern nach der Installation einfacher Anleitungen geben können. Sie können nur in der Datei POSTINSTALL verwendet werden, da die Werte für diese Variablen erst nach der Installation verfügbar sind.
In dieser Tabelle ist function-name der Wert des name im Ressourcenobjekt der Funktion in extension.yaml .
| Referenz für funktionsbezogene Variable | Beschreibung | Variablenwert (wird von Firebase nach der Installation der Erweiterung automatisch ausgefüllt) |
|---|---|---|
${function: function-name .location} | ||
| Ort , an dem die Funktion bereitgestellt wird | Beispielwert:us-central1 | |
${function: function-name .name} | ||
| Name der endgültig bereitgestellten Funktion, einschließlich der Instanz-ID der Erweiterung | Verallgemeinertes Format: Beispielwert: | |
${function: function-name .url} (gilt nur für HTTP-Funktionen) | ||
| URL der endgültig bereitgestellten Funktion, an die der Clientcode HTTP-Anfragen stellen kann | Verallgemeinertes Format: Beispielwert: | |
Wir empfehlen, so viel wie möglich des folgenden Textbausteins zu verwenden, sofern er für Ihre Erweiterung relevant ist.
Fügen Sie für alle Erweiterungen den folgenden Abschnitt hinzu, um Ihren Benutzern die Überwachung ihrer installierten Erweiterung zu erleichtern:
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.
Dokumentieren, wie eine Verlängerung ausgelöst wird
In der Benutzerdokumentation Ihrer Erweiterung müssen Sie Ihre Benutzer darüber informieren, wie Sie Ihre Erweiterung auslösen. Diese Anweisungen können so detailliert sein, wie Sie es für notwendig halten. Beachten Sie jedoch die Best Practices zum Schreiben einer POSTINSTALL Datei . Um eine Anleitung zur Bereitstellung dieser Anweisungen zu erhalten, erweitern Sie den Abschnitt unten, der für Ihre Erweiterung gilt.
Abhängig von den beteiligten Produkten können Ihre Benutzer eine durch ein Hintergrundereignis ausgelöste Erweiterung auf unterschiedliche Weise auslösen.
Nehmen Sie Änderungen direkt in der Konsole vor
Sie können Ihre Benutzer anweisen, erweiterungsauslösende Änderungen direkt in der Firebase-Konsole vorzunehmen, insbesondere zum ersten Testen Ihrer Erweiterung. Angenommen, Ihre Erweiterung erstellt jedes Mal ein neues Cloud Firestore-Dokument, wenn ein neuer Firebase Authentication-Benutzer erstellt wird. Sie können Ihre Benutzer anweisen, eine installierte Instanz Ihrer Erweiterung zu testen, indem Sie manuell einen neuen Authentifizierungsbenutzer in der Konsole hinzufügen. Anschließend können sie das neue Dokument beobachten, das im Abschnitt „Cloud Firestore“ der Konsole erstellt wurde.
Fügen Sie clientseitigen Code hinzu
Gegebenenfalls können Sie Ihre Benutzer auch anweisen, wie sie clientseitigen Code hinzufügen, um Ihre Erweiterung auszulösen. Sie sollten Benutzer auf die offizielle Dokumentation der APIs verweisen, die sie verwenden müssen. Sie können auch Beispiel-Apps oder kompilierte Client-Beispiele hinzufügen, um Ihren Benutzern die Integration der Erweiterung in ihre App zu erleichtern (ein Beispiel finden Sie in der Erweiterung „Distributed Counter“ ).
Damit Ihre Benutzer eine durch eine HTTP-Anfrage ausgelöste Funktion (und damit die Erweiterung) auslösen können, müssen Sie ihnen den Namen oder die URL der bereitgestellten Funktion mitteilen.
Der Name der endgültig bereitgestellten Funktion ist nicht derselbe wie der name , den Sie im Ressourcenobjekt der Funktion in extension.yaml angegeben haben. Um mehrere Installationen derselben Erweiterung in einem Projekt zu ermöglichen, benennt Firebase die Funktion in diesem Format um:ext- extension-instance-id - function-name .
Bei den folgenden Aufzählungszeichen handelt es sich um vorgeschlagene Textbausteine, die in die POSTINSTALL Datei Ihrer Erweiterung eingefügt werden sollen. Nach der Installation zeigt die Firebase-Konsole den Inhalt der POSTINSTALL Datei an und füllt diese Referenzen mit den tatsächlich konfigurierten Werten für die installierte Instanz. Wenn Sie beispielsweise eine Funktion mit dem Namen yourFunction definiert haben, könnten Sie (sofern zutreffend) Folgendes einschließen:
Für HTTP-
onRequestFunktionenTo trigger this extension, make a request to or visit the following URL: **`${function:yourFunction.url}`**.Für HTTP-aufrufbare (
onCall) FunktionenThis 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}`**.
Schreiben einer CHANGELOG-Datei
Welchen Inhalt enthält diese Datei?
Jede Erweiterung muss über eine CHANGELOG.md Datei verfügen, die die Änderungen dokumentiert, die in jeder neuen Version Ihrer von Ihnen veröffentlichten Erweiterung enthalten sind. Platzieren Sie jede Version unter einem Level-2-Header ( ## ); Andernfalls können Sie die gewünschte Markdown-Formatierung verwenden.
Das folgende Beispiel ist ein Auszug aus einer der offiziellen Erweiterungen:
## 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.
Wo wird dieser Inhalt dem Benutzer angezeigt?
- In der Firebase-Konsole und CLI, wenn Benutzer auf neue Versionen Ihrer Erweiterung aktualisieren. Die Firebase-Konsole und die CLI zeigen nur die Änderungen an, die wirksam würden, wenn der Benutzer das Upgrade abschließen würde.
- Das Quellcode-Repository Ihrer Erweiterung (im Erweiterungsverzeichnis).