Nutzerdokumentation für die Erweiterung erstellen

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, die mit den offiziellen Firebase-Erweiterungen verfügbar sind.

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?

Firebase Console">

Inhalte in der Firebase Console vorab installieren

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 --markdown > README.md der Firebase-Befehlszeile verwenden)

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.

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 korrekten Produktpreise finden Sie in den folgenden Ressourcen:

• Preisliste für Google Cloud-Produkte
• Firebase-Preisübersicht

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">

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 Darstellung der POSTINSTALL-Inhalte, indem Sie Ihre Erweiterung in einem echten 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 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.

Tipp:Verweisen Sie bei langen Werten (z. B. einem Datenbankpfad oder einer Funktions-URL) am Ende von Sätzen und Abschnitten auf den Parameter oder die Variable. Durch diese Best Practice sind Sätze in der Firebase-Konsole leichter zu lesen, wenn der Inhalt der POSTINSTALL-Datei mit tatsächlichen Werten gerendert wird.

Rufe die konfigurierten Parameterwerte in der Datei POSTINSTALL mit der folgenden Syntax auf: ${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: 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 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

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 zum Erstellen dieser Anleitung zu erhalten.

Hintergrund-ereignisbasierte Erweiterungen

Nutzer können eine im Hintergrund ausgeführte, ereignisbasierte Erweiterung auf verschiedene Weise auslösen, je nach den beteiligten Produkten.

Änderungen direkt in der Konsole vornehmen

Sie können Ihre Nutzer bitten, Ä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 der APIs verweisen, die sie verwenden müssen. Sie können auch Beispiel-Apps oder kompilierte Client-Beispiele einfügen, um Nutzern die Einbindung der Erweiterung in ihre App zu erleichtern. Ein Beispiel hierfür ist die Distributed Counter-Erweiterung.

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 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-Funktionen

  To 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}`**.
  

Wichtig :Damit Ihre Nutzer eine über eine HTTP-Anfrage ausgelöste Erweiterung verwenden können, müssen sie die für die Erweiterung bereitgestellten Funktionen öffentlich zugänglich machen. Eine ausführliche Anleitung für Ihre Nutzer finden Sie in den Musterbeispielen für den Text oben.

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)