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.md
POSTINSTALL.md
CHANGELOG.md
Außerdem sollten Sie Folgendes produzieren:
- Eine
README
-Datei für das öffentliche Repository der Erweiterung. - Längere Anleitungen, Leitfäden und Referenzmaterialien, die auf Ihrer eigenen Website veröffentlicht und in Ihrer
PREINSTALL.md
verlinkt 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 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) ---
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?
- 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 Firebase
in der Befehlszeile verwenden)--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
PREINSTALL
nach Möglichkeit auf weniger als eine Seite. - Geben Sie die Details an, die ein Endnutzer unbedingt wissen muss, bevor er die Erweiterung installiert.
- Fügen Sie eine detaillierte Anleitung in die Datei
POSTINSTALL
oder andere ergänzende Dateien ein. - Geben Sie kurz an, ob Sie andere Tools oder Scripts zur Unterstützung der Erweiterung bereitstellen.
POSTINSTALL
-Datei schreiben
Die Datei POSTINSTALL
enthält eine detaillierte Anleitung für die 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?
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 der Nutzer die konfigurierten Werte im Kontext der Anleitung sieht.
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.
Rufe mit der folgenden Syntax auf konfigurierte Parameterwerte in der Datei POSTINSTALL
zu: ${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: |
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.
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)