Jede Erweiterung muss eine Dokumentation enthalten, in der Nutzer darüber informiert werden, welche Funktionen die Erweiterung hat und wie sie verwendet wird.
Die Mindestanforderungen an die Dokumentation sind diese drei Markdown-Dateien:
PREINSTALL.mdPOSTINSTALL.mdCHANGELOG.md
Außerdem sollten Sie Folgendes produzieren:
- Eine
README-Datei für das öffentliche Repository der Erweiterung. - Längere Anleitungen, Leitfäden und Referenzen, die auf Ihrer eigenen Website veröffentlicht und in Ihrer
PREINSTALL.mdverlinkt sind.
Best Practices sowie gängige Formulierungen und Strukturen finden Sie in den Dateien mit den offiziellen Firebase-Erweiterungen.
README-Datei erstellen
Das Erweiterungsverzeichnis kann optional eine README-Datei enthalten. Der Befehl firebase ext:dev:init erstellt keine automatisch für Sie.
Die Firebase-Befehlszeile unterstützt jedoch den folgenden Befehl zum automatischen Generieren einer README-Datei mit Inhalten aus der extension.yaml- und der PREINSTALL.md-Datei:
firebase ext:info ./path/to/extension --markdown > README.md
Alle README-Dateien für die offiziellen Firebase-Erweiterungen werden mit diesem Befehl generiert.
Installationsinformationen hinzufügen
Fügen Sie dem README-Dokument nach dem Erstellen oder Generieren Installationsinformationen hinzu. Sie können das folgende Snippet 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:installpublisher_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) ---
PREINSTALL-Datei schreiben
Die PREINSTALL-Datei ist die Übersicht Ihrer Erweiterung, eine Art „Marketingseite“.
Welche Inhalte sind in dieser Datei enthalten?
- Eine umfassende Beschreibung der Funktionen Ihrer Erweiterung
- Liste der Voraussetzungen, z. B. Datenbankeinrichtung oder Zugriff auf einen Drittanbieterdienst (Beispiel)
- Eine kurze Beschreibung aller Aufgaben vor der Installation und deren Anleitung
- Kurze Beschreibung aller Aufgaben nach der Installation
(Beispiel)
(Detaillierte Anleitung in
POSTINSTALL) - Kurze Beschreibung der Auswirkungen auf die Abrechnung (mit Standardtext beginnen)
Wo werden diese Inhalte für den Nutzer angezeigt?
Firebase Console">
Firebase Console">
- Auf der Seite der Erweiterung unter extensions.dev
- Das Quellcode-Repository für Ihre Erweiterung (im Erweiterungsverzeichnis)
- Im README-Dokument der Erweiterung (wenn Sie das Flag
--markdown > README.md
PREINSTALL-Dateien können nicht auf die Parameterwerte für die Erweiterung zugreifen. Daher sollten Parameterverweise nicht mit tatsächlichen Werten gerendert werden.
Was sind einige Best Practices?
- Begrenzen Sie den gesamten Inhalt der Datei
PREINSTALLnach Möglichkeit auf weniger als eine Seite. - Geben Sie so viele Details an, wie ein Endnutzer unbedingt wissen muss, bevor er die Erweiterung installiert.
- Fügen Sie eine detaillierte Anleitung in die Datei
POSTINSTALLoder andere ergänzende Dateien ein. - Geben Sie kurz an, ob Sie andere Tools oder Scripts zur Unterstützung der Erweiterung bereitstellen.
Hilfreiche PREINSTALL-Textbausteine
Wir empfehlen, so viel wie möglich des folgenden Textbausteins zu verwenden, der für Ihre Erweiterung geeignet ist. Wir haben einige Beispiele aufgeführt. Am wichtigsten ist jedoch, dass alle von Google und anderen Anbietern in Rechnung gestellten Dienste aufgeführt sind.
Die richtigen Produktpreise finden Sie in den folgenden Ressourcen:
Fügen Sie für alle Erweiterungen diesen Abschnitt hinzu, damit Nutzer die Auswirkungen auf die Abrechnung besser nachvollziehen können:
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>.
POSTINSTALL-Datei schreiben
Die Datei POSTINSTALL enthält eine detaillierte Anleitung für die Nutzung der Erweiterung nach der Installation.
Welche Inhalte sind in dieser Datei enthalten?
- Detaillierte Anleitungen für alle erforderlichen Aufgaben nach der Installation, z. B. zum Einrichten von Firebase-Sicherheitsregeln oder zum Hinzufügen von clientseitigem Code (Beispiel)
- Allgemeine Anleitung zum sofortigen Testen der installierten Erweiterung (z. B. „Gehen Sie zur Console und führen Sie dann Folgendes aus“)
- Allgemeine Informationen zum Auslösen der Erweiterung, insbesondere für HTTP-Anfrage-ausgelöste Erweiterungen
- Kurze Anleitung zum Überwachen der installierten Erweiterung (mit Standardtext beginnen)
Wo werden diese Inhalte für den Nutzer angezeigt?
Firebase Console">
Firebase Console">
In der Firebase-Konsole, nachdem ein Nutzer Ihre Erweiterung installiert hat (auf der Detailkarte der installierten Erweiterung)
- Prüfen Sie die Darstellung der
POSTINSTALL-Inhalte, indem Sie Ihre Erweiterung in einem echten Projekt installieren.
- Prüfen Sie die Darstellung der
Das Quellcode-Repository für Ihre Erweiterung (im Erweiterungsverzeichnis)
POSTINSTALL-Dateien können auf die Parameterwerte und mehrere funktionsbezogene Variablen für die Erweiterung zugreifen. Wenn der POSTINSTALL-Inhalt in der Firebase-Konsole angezeigt wird, werden die tatsächlichen Werte anstelle der Parameter- oder Variablenreferenzen angezeigt. Unten finden Sie weitere Informationen dazu, wie Sie in Ihrer POSTINSTALL-Datei auf Parameter und Variablen verweisen.
Was sind einige Best Practices?
- Der gesamte Inhalt der
POSTINSTALL-Datei sollte prägnant, aber aussagekräftig sein. - Unterteilen Sie den Inhalt mit Überschriften, um verschiedene Aufgaben oder Konzepte zu trennen.
- Sie können detaillierte Anleitungen für einen bestimmten Workflow oder eine bestimmte Aufgabe auf Ihrer Website (Beispiel) oder in ergänzenden Markdown-Dateien im Erweiterungsverzeichnis veröffentlichen (Beispiel).
- Verweisen Sie auf Parameter und funktionsbezogene Variablen, damit die Nutzer die konfigurierten Werte im Kontext der Anleitung sehen.
Verweise auf Parameter und Variablen
Nach der Installation wird in der Firebase-Konsole der Inhalt der POSTINSTALL-Datei der Erweiterung angezeigt. Wenn Sie in Ihrer POSTINSTALL-Datei auf Parameter und funktionsbezogene Variablen (siehe Tabelle unten) verweisen, werden diese Verweise in der Konsole mit den tatsächlichen Werten für die installierte Instanz ausgefüllt.
Mit der folgenden Syntax kannst du auf konfigurierte Parameterwerte in der Datei POSTINSTALL zugreifen: ${param:PARAMETER_NAME}
Außerdem kannst du auf die folgenden funktionsbezogenen Variablen nur in deiner POSTINSTALL-Datei verweisen. Firebase unterstützt diese Variablen, damit Sie Ihren Nutzern nach der Installation leichter helfen 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 Felds name im Ressourcenobjekt der Funktion in extension.yaml.
| Referenz für funktionsbezogene Variable | Beschreibung | Variabler Wert (wird nach der Installation der Erweiterung automatisch von Firebase ausgefüllt) |
|---|---|---|
${function:function-name.location}
|
||
| Standort, an dem die Funktion bereitgestellt wird |
Beispielwert:us-central1
|
|
${function:function-name.name}
|
||
| Name der endgültigen bereitgestellten Funktion, einschließlich der Instanz-ID der Erweiterung |
Allgemeines Format:
Beispielwert: |
|
${function:function-name.url}
(gilt nur für HTTP-Funktionen)
|
||
| URL der endgültigen bereitgestellten Funktion, an die Clientcode HTTP-Anfragen senden kann |
Allgemeines Format:
Beispielwert: |
|
Hilfreiche POSTINSTALL-Textbausteine
Wir empfehlen, so viel wie möglich des folgenden Textbausteins zu verwenden, der für Ihre Erweiterung geeignet ist.
Fügen Sie für alle Erweiterungen den folgenden Abschnitt hinzu, damit Nutzer ihre installierte Erweiterung im Blick behalten können:
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 Erweiterung ausgelöst wird
In der Nutzerdokumentation Ihrer Erweiterung müssen Sie Nutzern erklären, wie sie Ihre Erweiterung auslösen. Diese Anleitung kann so detailliert sein, wie Sie es für erforderlich halten. Beachten Sie jedoch die Best Practices für das Erstellen einer POSTINSTALL-Datei.
Maximieren Sie den Abschnitt unten, der für Ihre Erweiterung gilt, um eine Anleitung dazu aufzurufen.
Hintergrund-ereignisbasierte Erweiterungen
Nutzer können eine im Hintergrund ausgeführte, ereignisbasierte Erweiterung auf verschiedene Arten auslösen, je nach den beteiligten Produkten.
Änderungen direkt in der Konsole vornehmen
Sie können Ihre Nutzer anweisen, Änderungen, die die Erweiterung auslösen, direkt in der Firebase-Konsole vorzunehmen, insbesondere für die ersten Tests Ihrer Erweiterung. Angenommen, Ihre Erweiterung erstellt jedes Mal ein neues Cloud Firestore-Dokument, wenn ein neuer Firebase Authentication-Nutzer erstellt wird. Sie können Ihre Nutzer bitten, eine installierte Instanz Ihrer Erweiterung zu testen. Dazu fügen Sie manuell einen neuen Authentication-Nutzer in der Konsole hinzu. Das neue Dokument wird dann im Bereich Cloud Firestore der Konsole angezeigt.
Clientseitigen Code hinzufügen
Gegebenenfalls können Sie Ihre Nutzer auch anweisen, clientseitigen Code hinzuzufügen, um Ihre Erweiterung auszulösen. Sie sollten Nutzer auf die offizielle Dokumentation für die APIs verweisen, die sie verwenden müssen. Sie können auch Beispiel-Apps oder kompilierte Client-Beispiele hinzufügen, damit Ihre Nutzer die Erweiterung in ihre App einbinden können. Ein Beispiel hierfür ist die Distributed Counter-Erweiterung.
Durch HTTP-Anfragen ausgelöste Erweiterungen
Damit Ihre Nutzer eine HTTP-Anfrage auslösende 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 stimmt nicht mit name überein, den Sie im Ressourcenobjekt der Funktion in extension.yaml angegeben haben. Damit mehrere Installationen derselben Erweiterung in einem Projekt möglich sind, benennt Firebase die Funktion in diesem Format um: ext-extension-instance-id-function-name
Die folgenden Aufzählungspunkte sind Vorschläge für einen Textbaustein, der in die POSTINSTALL-Datei Ihrer Erweiterung aufgenommen werden kann. Nach der Installation wird in der Firebase-Konsole der Inhalt der Datei POSTINSTALL angezeigt und diese Verweise werden mit den tatsächlichen konfigurierten Werten für die installierte Instanz ausgefüllt. Wenn Sie beispielsweise eine Funktion namens yourFunction definiert haben, können Sie Folgendes angeben:
Für HTTP-
onRequest-FunktionenTo trigger this extension, make a request to or visit the following URL: **`${function:yourFunction.url}`**.Für HTTP-aufrufbare Funktionen (
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}`**.
CHANGELOG-Datei schreiben
Welche Inhalte sind in dieser Datei enthalten?
Jede Erweiterung muss eine CHANGELOG.md-Datei haben, in der die Änderungen dokumentiert sind, die in jeder neuen Version Ihrer Erweiterung enthalten sind. Geben Sie jede Version unter einem Level-2-Header (##) an. Andernfalls können Sie die Markdown-Formatierung verwenden, die Sie für angebracht halten.
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 werden diese Inhalte für den Nutzer angezeigt?
- In der Firebase Console und in der Befehlszeile, wenn Nutzer auf neue Versionen Ihrer Erweiterung umstellen. In der Firebase-Konsole und der Befehlszeile werden nur die Änderungen angezeigt, die wirksam werden, wenn der Nutzer das Upgrade durchführt.
- Das Quellcode-Repository Ihrer Erweiterung (im Erweiterungsverzeichnis)