Nutzerdokumentation für die Erweiterung erstellen

Für jede Erweiterung muss eine Dokumentation vorhanden sein, in der Nutzer erfahren, was die Erweiterung tut und wie sie verwendet wird.

Die erforderliche Mindestdokumentation besteht aus diesen drei Markdown-Dateien:

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

Außerdem sollten Sie Folgendes erstellen:

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

Wenn Sie sich mit Best Practices und gängigen Formulierungen und Strukturen vertraut machen möchten, empfehlen wir Ihnen, die Dateien zu lesen, die mit den offiziellen Firebase-Erweiterungen verfügbar sind.

README erstellen

Das Verzeichnis der Erweiterung kann optional eine README-Datei enthalten. Beachten Sie, dass der Befehl firebase ext:dev:init nicht automatisch einen Schlüssel für Sie generiert.

Die Firebase-Befehlszeile unterstützt jedoch den folgenden praktischen Befehl, um automatisch eine README-Datei mit Inhalten aus Ihrer extension.yaml-Datei und Ihrer PREINSTALL.md-Datei zu generieren:

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

Nachdem Sie eine README-Datei geschrieben oder generiert haben, fügen Sie ihr 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 ist die Übersicht Ihrer Erweiterung, eine Art „Marketingseite“.

Welche Inhalte sind in dieser Datei enthalten?

• Umfassende Beschreibung der Funktionen Ihrer Erweiterung
• Liste der Voraussetzungen, z. B. Datenbankeinrichtung oder Zugriff auf einen Nicht-Google-Dienst (Beispiel)
• Kurze Beschreibung aller Aufgaben vor der Installation und entsprechende Anleitungen
• Kurze Beschreibung aller Aufgaben nach der Installation (Beispiel) (detaillierte Anleitung in POSTINSTALL)
• Kurze Beschreibung der Auswirkungen auf die Abrechnung (beginnen Sie mit dem Standardtext)

Wo werden diese Inhalte dem Nutzer angezeigt?

Firebase Console">

Inhalte in der Firebase Console vorinstallieren

Firebase Console">

• Auf der Seite der Erweiterung auf extensions.dev.
• Das Quellcode-Repository für Ihre Erweiterung (im Erweiterungsverzeichnis)
• In der README-Datei der Erweiterung (wenn Sie das Flag --markdown > README.md der Firebase-Befehlszeile verwenden)

PREINSTALL-Dateien können nicht auf die Parameterwerte für die Erweiterung zugreifen. Sie sollten also nicht erwarten, dass Parameterreferenzen mit tatsächlichen Werten gerendert werden.

Was sind einige Best Practices?

• Der gesamte Inhalt der Datei PREINSTALL sollte nach Möglichkeit weniger als eine Seite umfassen.
• Geben Sie den Detaillierungsgrad an, den ein Endnutzer unbedingt kennen muss, bevor er die Erweiterung installiert.
• Detaillierte Anweisungen in die Datei POSTINSTALL oder andere ergänzende Dateien einfügen
• Erwähne kurz, ob du andere Tools oder Skripts zur Unterstützung der Erweiterung bereitstellst.

Hilfreicher PREINSTALL-Textbaustein

Wir empfehlen, so viel wie möglich des folgenden Standardtexts zu verwenden, sofern er für deine Erweiterung relevant ist. Wir haben einige Beispiele aufgeführt. Am wichtigsten ist jedoch, dass alle von Google und nicht von Google abgerechneten Dienste aufgeführt sind.

In den folgenden Ressourcen finden Sie die richtigen Preisdetails für Produkte:

• Preisliste für Google Cloud-Produkte
• Firebase-Preise

Füge für alle Erweiterungen diesen Abschnitt hinzu, damit deine Nutzer 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>.

POSTINSTALL-Datei schreiben

Die Datei POSTINSTALL ist die detaillierte Seite mit der Anleitung für die Installation Ihrer Erweiterung.

Welche Inhalte sind in dieser Datei enthalten?

• Detaillierte Anleitungen für alle erforderlichen Aufgaben nach der Installation, z. B. das Einrichten von Firebase-Sicherheitsregeln oder das Hinzufügen von clientseitigem Code (Beispiel)
• Allgemeine Anleitung zum sofortigen Ausprobieren der installierten Erweiterung (z. B. „Rufen Sie die Console auf und führen Sie dann Folgendes aus“)
• Grundlegende Informationen zum Auslösen der Erweiterung, insbesondere für durch HTTP-Anfragen ausgelöste Erweiterungen
• Kurze Anleitung zum Monitoring der installierten Erweiterung (beginnen Sie mit dem Boilerplate-Text)

Wo werden diese Inhalte dem Nutzer angezeigt?

Firebase Console">

Inhalte nach der Installation in der 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 Anzeige des POSTINSTALL-Inhalts, indem Sie Ihre Erweiterung in einem tatsächlichen Projekt installieren.

• 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 Inhalt von POSTINSTALL in der Firebase-Konsole angezeigt wird, werden die tatsächlichen Werte anstelle der Parameter- oder Variablenreferenzen angezeigt. Weitere Informationen zum Verweisen auf Parameter und Variablen in Ihrer POSTINSTALL-Datei finden Sie unten.

Was sind einige Best Practices?

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

Parameter und Variablen referenzieren

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 Console mit den tatsächlichen Werten für die installierte Instanz ausgefüllt.

Tipp: Bei Werten, die lang sein können (z. B. ein Datenbankpfad oder eine Funktions-URL), sollten Sie den Parameter oder die Variable am Ende von Sätzen und Abschnitten angeben. Diese Best Practice erleichtert das Lesen von Sätzen in der Firebase-Konsole, wenn der Inhalt der POSTINSTALL-Datei mit tatsächlichen Werten gerendert wird.

Greifen Sie mit der folgenden Syntax auf konfigurierte Parameterwerte in der Datei POSTINSTALL zu: ${param:PARAMETER_NAME}

Sie können auch auf die folgenden funktionsbezogenen Variablen nur in Ihrer POSTINSTALL-Datei verweisen. Firebase unterstützt diese Variablen, damit Sie Ihren Nutzern nach der Installation leichter Anleitungen zur Verfügung stellen können. Sie sind nur in der Datei POSTINSTALL verfügbar, 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 Variablen	Beschreibung	Variablenwert (wird nach der Installation der Erweiterung automatisch von Firebase eingefügt)
${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: ext-extension-instance-id-function-name Beispielwert: ext-my-awesome-extension-6m31-yourFunctionName
${function:function-name.url} (gilt nur für HTTP-Funktionen)
	URL der endgültigen bereitgestellten Funktion, an die der Clientcode HTTP-Anfragen senden kann	Allgemeines Format: https://deployment-location-project-id.cloudfunctions.net/name-of-final-deployed-function Beispielwert: https://us-central1-project-123.cloudfunctions.net/ext-my-awesome-extension-6m31-yourFunctionName

Hilfreicher POSTINSTALL-Textbaustein

Wir empfehlen, so viel wie möglich des folgenden Standardtexts zu verwenden, sofern er für deine Erweiterung relevant ist.

Füge für alle Erweiterungen den folgenden Abschnitt ein, damit deine Nutzer die 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 Ihre Nutzer darüber informieren, wie sie Ihre Erweiterung auslösen können. Diese Anleitung kann so detailliert sein, wie Sie es für nötig halten. Beachten Sie jedoch die Best Practices zum Schreiben einer POSTINSTALL-Datei. Wenn Sie wissen möchten, wie Sie diese Anleitung bereitstellen, maximieren Sie den Abschnitt unten, der für Ihre Erweiterung gilt.

Durch Hintergrundereignisse ausgelöste Erweiterungen

Ihre Nutzer können eine durch ein Hintergrundereignis ausgelöste Erweiterung auf verschiedene Arten auslösen, je nachdem, welche Produkte beteiligt sind.

Ä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 ein neues Cloud Firestore-Dokument, wenn ein neuer Firebase Authentication-Nutzer erstellt wird. Sie können Ihre Nutzer anweisen, eine installierte Instanz Ihrer Erweiterung zu testen, indem Sie in der Console manuell einen neuen Authentication-Nutzer hinzufügen. Anschließend können sie das neue Dokument im Abschnitt Cloud Firestore der Console sehen.

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 Clientbeispiele einfügen, um Ihren Nutzern die Einbindung der Erweiterung in ihre App zu erleichtern. Ein Beispiel finden Sie in der Erweiterung Distributed Counter.

Durch HTTP-Anfragen ausgelöste Erweiterungen

Damit Ihre Nutzer 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 zur Verfügung stellen.

Der Name der endgültigen bereitgestellten Funktion ist nicht mit dem name identisch, 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 vorgeschlagene Textbausteine, die Sie in die POSTINSTALL-Datei Ihrer Erweiterung aufnehmen können. Nach der Installation werden in der Firebase-Konsole die Inhalte der Datei POSTINSTALL angezeigt und diese Verweise mit den tatsächlichen konfigurierten Werten für die installierte Instanz ausgefüllt. Wenn Sie beispielsweise eine Funktion mit dem Namen yourFunction definiert haben, können Sie Folgendes einfügen (falls zutreffend):

• Für HTTP-onRequest-Funktionen

  To trigger this extension, make a request to or visit the following URL:
  **`${function:yourFunction.url}`**.
  

• Für aufrufbare HTTP-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}`**.
  

Wichtig: Bevor Ihre Nutzer eine durch eine HTTP-Anfrage ausgelöste Erweiterung verwenden können, müssen sie die für die Erweiterung bereitgestellten Funktionen öffentlich zugänglich machen. Die detaillierten Anweisungen, die Sie Ihren Nutzern zur Verfügung stellen müssen, finden Sie oben in den Beispieltexten.

CHANGELOG-Datei schreiben

Welche Inhalte sind in dieser Datei enthalten?

Jede Erweiterung muss eine CHANGELOG.md-Datei enthalten, in der die Änderungen dokumentiert sind, die in jeder neuen Version Ihrer Erweiterung enthalten sind, die Sie veröffentlichen. Setzen Sie jede Version unter eine Überschrift der Ebene 2 (##). Ansonsten können Sie eine beliebige 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 werden diese Inhalte dem Nutzer angezeigt?

• In der Firebase-Konsole und der Befehlszeile, wenn Nutzer ein Upgrade auf neue Versionen Ihrer Erweiterung durchführen. In der Firebase-Konsole und der Befehlszeile werden nur die Änderungen angezeigt, die wirksam werden, wenn der Nutzer das Upgrade abschließt.
• Das Quellcode-Repository Ihrer Erweiterung (im Verzeichnis der Erweiterung).