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

Inhalte in der Firebase-Konsole vorinstallieren

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

Hilfreicher Textbaustein für PREINSTALL

Wir empfehlen, so viele der folgenden Textbausteine wie möglich zu verwenden, die für Ihre Erweiterung relevant sind. Wir haben einige Beispiele bereitgestellt, ist es wichtig, dass alle von Google und nicht von Google abgerechneten Dienste aufgeführt sind.

Sie können die folgenden Ressourcen verwenden, um die korrekten Angaben zu den Produktpreisen zu finden:

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

Fügen Sie diesen Abschnitt bei allen Erweiterungen hinzu, damit Ihre Nutzer die Abrechnung besser nachvollziehen können. Auswirkungen:

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

Inhalte nach der Installation in der Firebase-Konsole

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.

Tipp:Für Werte, die lang sein können (z. B. eine Datenbank), Pfad oder eine Funktions-URL), verweisen Sie auf den Parameter oder die Variable am Ende des Sätzen und Abschnitten. Diese Best Practice sorgt dafür, dass Sätze leichter in der Firebase-Konsole, wenn der Inhalt der Datei POSTINSTALL mit tatsächlichen Werten gerendert werden.

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.

Referenz für funktionsbezogene Variable	Beschreibung	Variabler Wert (wird nach der Installation der Erweiterung automatisch von Firebase ausgefüllt)
${function:function-name.location}
	Standort in dem die Funktion bereitgestellt wird	Beispielwert: us-central1
${function:function-name.name}
	Name der abschließenden bereitgestellten Funktion, die den Wert 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 abschließenden bereitgestellten Funktion, für die Clientcode verwendet werden kann HTTP-Anfragen stellen	Generalisiertes 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 Textbaustein für POSTINSTALL

Wir empfehlen, so viele der folgenden Textbausteine wie möglich zu verwenden, die für Ihre Erweiterung relevant sind.

Fügen Sie bei allen Erweiterungen den folgenden Abschnitt hinzu, damit Ihre Nutzer leichter überwachen können, installierte Erweiterung:

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.

Durch Hintergrundereignisse ausgelöste Erweiterungen

Ihre Nutzer können eine durch ein Hintergrundereignis ausgelöste Erweiterung auf verschiedene Arten auslösen: abhängig von 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 Nutzenden anweisen, Eine installierte Instanz Ihrer Erweiterung, indem Sie manuell einen neuen Authentication-Nutzer hinzufügen in der Konsole. Das neue Dokument wird dann im Bereich Cloud Firestore der Konsole angezeigt.

Clientseitigen Code hinzufügen

Gegebenenfalls können Sie Ihre Nutzer auch anweisen, wie sie clientseitigen Code hinzufügen. damit die Erweiterung ausgelöst wird. Nutzer müssen zur offiziellen Dokumentation weitergeleitet werden für die APIs, die sie verwenden müssen. Sie können auch Beispiel-Apps oder kompilierte Clientbeispiele, um Ihren Nutzern zu helfen, die Erweiterung in ihre App (siehe Erweiterung Distributed Counter .

Durch HTTP-Anfragen ausgelöste Erweiterungen

Damit Ihre Nutzer eine durch HTTP-Anfrage ausgelöste Funktion auslösen können (und somit Erweiterung), müssen Sie den Code der Funktion deployed name oder seine URL:

Der Name der abschließend bereitgestellten Funktion ist nicht mit dem der name, die Sie ist im Ressourcenobjekt der Funktion in extension.yaml angegeben. 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 zeigt die Firebase-Konsole zeigt den Inhalt der Datei POSTINSTALL an und füllt diese Referenzen aus durch die tatsächlichen konfigurierten Werte für die installierte Instanz. Wenn beispielsweise yourFunction definiert haben, können Sie den Parameter Folgendes (je nach zutreffendem Fall):

• Für HTTP-onRequest-Funktionen

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

• Für 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 Nutzer eine durch HTTP-Anfrage ausgelöste Erweiterung verwenden können, müssen die für die Erweiterung bereitgestellten Funktionen öffentlich zugänglich machen. Eine ausführliche Anleitung, die Sie Ihren Nutzern zur Verfügung stellen, finden Sie im Boilerplate-Text. Beispiele 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. 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).