Nutzerdokumentation für die Erweiterung erstellen

Für jede Erweiterung muss eine Dokumentation vorhanden sein, aus der hervorgeht, und wie sie verwendet werden.

Die erforderliche Dokumentation umfasst mindestens diese drei Markdown-Dateien:

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

Darüber hinaus solltest du Folgendes in Betracht ziehen:

• Eine README-Datei für das öffentliche Repository der Erweiterung.
• Längere Tutorials, Leitfäden und Referenzen, die auf Ihrer eigenen Website veröffentlicht sind, und mit PREINSTALL.md verknüpft.

Um einige Best Practices und gängige Formulierungen und Strukturen kennenzulernen, empfehlen wir Sie überprüfen die Dateien, die im offizielle Firebase-Erweiterungen.

README-Datei erstellen

Ihr Erweiterungsverzeichnis kann optional eine README-Datei enthalten. Das Feld Der Befehl firebase ext:dev:init erstellt nicht automatisch einen Code.

Die Firebase-Befehlszeile unterstützt jedoch den folgenden Convenience-Befehl, um automatisch eine README-Datei mit Inhalten generieren, die aus Ihrem extension.yaml-Datei und Ihre 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 Datei „PREINSTALL“ enthält eine Übersicht über deine Erweiterung, ein Typ vom Typ „Marketing“ Seite.

Welcher Inhalt befindet sich in dieser Datei?

• Umfassende Beschreibung der Funktionen Ihrer Erweiterung
• Liste der Voraussetzungen, z. B. die Einrichtung der Datenbank oder der Zugriff auf ein nicht von Google stammendes Dienst (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 (beginnen mit Standardtext)

Wo werden diese Inhalte dem Nutzer angezeigt?

Firebase Console">

Firebase Console">

• Auf der Seite der Erweiterung unter extensions.dev
• Ihr Quellcode-Repository für Ihre Erweiterung (im Erweiterungsverzeichnis)
• Im README-Dokument der Erweiterung (wenn Sie das Flag Firebase --markdown > README.md in der Befehlszeile verwenden)

PREINSTALL-Dateien können nicht auf die Parameterwerte für die Erweiterung zugreifen. Sie können sollte nicht davon ausgehen, dass Parameterverweise mit tatsächlichen Werten gerendert werden.

Welche Best Practices gibt es?

• Bewahren Sie den gesamten Inhalt der PREINSTALL-Datei auf einer Seite auf. wenn möglich
• Geben Sie den Detaillierungsgrad an, den Endnutzer unbedingt kennen müssen. bevor Sie die Erweiterung installieren
• Füge eine detaillierte Anleitung in der Datei POSTINSTALL oder an einer anderen ergänzende Dateien
• Erwähnen Sie kurz, ob Sie andere Tools oder Skripte zur Unterstützung der Erweiterung

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 die detaillierten Informationen nach der Installation Ihrer Erweiterung Anleitung.

Welche Inhalte sind in dieser Datei enthalten?

• Eine detaillierte Anleitung für alle erforderlichen Aufgaben nach der Installation wie das Einrichten von Firebase-Sicherheitsregeln oder das Hinzufügen von clientseitigem Code (Beispiel)
• Allgemeine Anleitung zum sofortigen Ausprobieren der installierte Erweiterung (z. B. „Geh zur Konsole und tu das“)
• Grundlegende Informationen zum Auslösen der Erweiterung, insbesondere für Durch HTTP-Anfragen ausgelöste Erweiterungen
• Kurze Anweisungen zur Überwachung der installierten Erweiterung (beginnen mit Standardtext)

Wo werden diese Inhalte dem Nutzer angezeigt?

Firebase Console">

Firebase Console">

• In der Firebase-Konsole, nachdem ein Nutzer Ihre Erweiterung installiert hat (im Detailkarte der installierten Erweiterung)

  • Bitte überprüfe die Anzeige der POSTINSTALL-Inhalte, indem du die Installation der Erweiterung in einer Projekt.

• Das Quellcode-Repository für Ihre Erweiterung (im Erweiterungsverzeichnis)

POSTINSTALL-Dateien können auf die Parameterwerte und mehrere funktionsbezogene Variablen für die Erweiterung. 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 auf Parameter und Variablen in der Datei POSTINSTALL.

Welche Best Practices gibt es?

• Der gesamte Inhalt der Datei POSTINSTALL sollte kurz, aber aussagekräftig sein.
• Unterteilen Sie den Inhalt mit Überschriften, um verschiedene Aufgaben oder Konzepte zu trennen.
• Erwägen Sie, detaillierte Anweisungen für eine bestimmte Workflow oder Aufgabe auf Ihrer Website (Beispiel) oder in zusätzlichen Markdown-Dateien im Erweiterungs-Repository (Beispiel)
• Referenzparameter und funktionsbezogene Variablen damit der Nutzer die konfigurierten Werte im Kontext der Anleitung sieht

Parameter und Variablen referenzieren

Nach der Installation zeigt die Firebase-Konsole den Inhalt der die Datei POSTINSTALL der Erweiterung. Wenn Sie auf Parameter und funktionsbezogene Variablen (siehe Tabelle unten) in der Datei POSTINSTALL und dann in der Console übergibt diese Referenzen die tatsächlichen Werte für die installierte Instanz.

Rufe die konfigurierten Parameterwerte in der Datei POSTINSTALL mit der folgenden Syntax auf: ${param:PARAMETER_NAME}

Sie können auch auf die folgenden funktionsbezogenen Variablen in Ihrem Nur POSTINSTALL-Datei. Firebase unterstützt diese Variablen, damit Sie Ihren Nutzern nach der Installation leichter eine Orientierungshilfe bieten. Sie sind nur können in der Datei POSTINSTALL verwendet werden, da Werte für diese Variablen sind erst nach der Installation verfügbar.

In dieser Tabelle ist function-name der Wert des Felds name im Ressourcenobjekt der Funktion in extension.yaml.

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 Ihre Nutzer über wie die Erweiterung ausgelöst wird. Diese Anleitung kann so detailliert sein wie die Sie als notwendig erachten, beachten Sie jedoch die Best Practices für das Verfassen 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. Jede Version einfügen unter einer Überschrift der Ebene 2 (##); Andernfalls können Sie beliebige Markdown-Elemente die Ihnen gefällt.

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 dem Nutzer angezeigt?

• In der Firebase-Konsole und der Befehlszeile, wenn Nutzer ein Upgrade auf neue Versionen Ihrer . 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 der Erweiterung (im Erweiterungsverzeichnis).