Utwórz dokumentację użytkownika dla swojego rozszerzenia

Każde rozszerzenie musi mieć dokumentację, która uczy użytkowników, co robi rozszerzenie i jak z niego korzystać.

Minimalna wymagana dokumentacja to zestaw trzech plików przecen:

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

Ponadto należy rozważyć produkcję:

• Plik README dla publicznego repozytorium rozszerzenia.
• Dłuższe samouczki, przewodniki i odniesienia opublikowane na Twojej własnej stronie internetowej i połączone w pliku PREINSTALL.md .

Aby poznać najlepsze praktyki oraz typowe sformułowania i strukturę, zalecamy przejrzenie plików dostępnych z oficjalnymi rozszerzeniami Firebase .

Tworzenie pliku README

Twój katalog rozszerzeń może opcjonalnie zawierać plik README. Pamiętaj, że polecenie firebase ext:dev:init nie generuje go automatycznie.

Interfejs Firebase CLI obsługuje jednak następujące wygodne polecenie automatycznego generowania pliku README zawierającego treść pobraną z pliku extension.yaml i pliku PREINSTALL.md :

firebase ext:info ./path/to/extension --markdown > README.md

Wszystkie pliki README dla oficjalnych rozszerzeń Firebase są generowane za pomocą tego polecenia.

Dodaj informacje o instalacji

Po napisaniu lub wygenerowaniu pliku README dodaj do niego informacje dotyczące instalacji. Możesz użyć następującego fragmentu jako szablonu:

---

## 🧩 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)

---

Zapisywanie pliku PREINSTALL

Plik PREINSTALL to przegląd Twojego rozszerzenia, rodzaj strony „marketingowej”.

Jaka zawartość znajduje się w tym pliku?

• Kompleksowy opis funkcjonalności Twojego rozszerzenia
• Lista wymagań wstępnych, takich jak konfiguracja bazy danych lub dostęp do usługi innej niż Google ( przykład )
• Krótki opis wszelkich zadań przedinstalacyjnych i ich instrukcji
• Krótki opis wszelkich zadań poinstalacyjnych ( przykład ) (szczegółowe instrukcje znajdują się w POSTINSTALL )
• Krótki opis wszelkich konsekwencji rozliczeniowych (zacznij od standardowego tekstu )

Gdzie ta treść jest wyświetlana użytkownikowi?

Wstępnie zainstaluj zawartość w konsoli Firebase

• Na stronie rozszerzenia w witrynie rozszerzenia.dev .
• Repozytorium kodu źródłowego Twojego rozszerzenia (w katalogu rozszerzenia)
• Jako część pliku README rozszerzenia (jeśli używasz interfejsu CLI Firebase --markdown > README.md )

Pliki PREINSTALL nie mają dostępu do wartości parametrów rozszerzenia, dlatego nie należy oczekiwać, że odniesienia do parametrów będą renderowane z rzeczywistymi wartościami.

Jakie są najlepsze praktyki?

• Jeśli to możliwe, przechowuj pełną zawartość pliku PREINSTALL na jednej stronie
• Podaj poziom szczegółowości, który użytkownik końcowy musi znać przed zainstalowaniem rozszerzenia
• Umieść szczegółowe instrukcje w pliku POSTINSTALL lub innych plikach uzupełniających
• Krótko wspomnij, czy udostępniasz inne narzędzia lub skrypty do obsługi rozszerzenia

Pomocny tekst standardowy PREINSTALL

Zalecamy użycie jak największej ilości poniższego standardowego tekstu, odpowiedniego dla Twojego rozszerzenia. Podaliśmy kilka przykładów, ale najważniejsze jest, aby upewnić się, że na liście znajdują się wszystkie usługi rozliczane przez Google i inne usługi.

Aby znaleźć prawidłowe informacje o cenach produktów, możesz skorzystać z następujących zasobów:

• Cennik produktów Google Cloud
• Przegląd cen Firebase

W przypadku wszystkich rozszerzeń dołącz tę sekcję, aby pomóc użytkownikom zrozumieć konsekwencje rozliczeniowe:

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

Zapisywanie pliku POSTINSTALL

Plik POSTINSTALL to szczegółowa strona z instrukcjami poinstalacyjnymi dla Twojego rozszerzenia.

Jaka zawartość znajduje się w tym pliku?

• Szczegółowe instrukcje dotyczące wszelkich wymaganych zadań poinstalacyjnych, takich jak konfigurowanie reguł bezpieczeństwa Firebase lub dodawanie kodu po stronie klienta ( przykład )
• Ogólne instrukcje dotyczące natychmiastowego wypróbowania zainstalowanego rozszerzenia (na przykład „przejdź do konsoli, a następnie wykonaj to”)
• Podstawowe informacje o tym, jak uruchomić rozszerzenie, szczególnie w przypadku rozszerzeń uruchamianych żądaniem HTTP
• Krótkie wskazówki dotyczące monitorowania zainstalowanego rozszerzenia (zacznij od tekstu schematycznego )

Gdzie ta treść jest wyświetlana użytkownikowi?

Zawartość poinstalacyjna w konsoli Firebase

• W konsoli Firebase po zainstalowaniu przez użytkownika rozszerzenia (na karcie szczegółów zainstalowanego rozszerzenia)

  • Upewnij się, że sprawdziłeś wyświetlanie zawartości POSTINSTALL , instalując rozszerzenie w rzeczywistym projekcie .

• Repozytorium kodu źródłowego Twojego rozszerzenia (w katalogu rozszerzenia)

Pliki POSTINSTALL mogą uzyskać dostęp do wartości parametrów i kilku zmiennych związanych z funkcjami rozszerzenia. Gdy w konsoli Firebase wyświetlana jest treść POSTINSTALL , wyświetlane są rzeczywiste wartości , a nie odwołania do parametrów lub zmiennych. Poniżej dowiesz się więcej o tym, jak odwoływać się do parametrów i zmiennych w pliku POSTINSTALL .

Jakie są najlepsze praktyki?

• Zachowaj zwięzłą, ale opisową pełną zawartość pliku POSTINSTALL .
• Podziel treść za pomocą nagłówków, aby rozdzielić odrębne zadania lub koncepcje.
• Rozważ opublikowanie szczegółowych instrukcji dotyczących konkretnego przepływu pracy lub zadania na swojej stronie internetowej ( przykład ) lub w dodatkowych plikach przecen w repozytorium rozszerzeń ( przykład ).
• Parametry referencyjne i zmienne związane z funkcjami , aby użytkownik widział ich skonfigurowane wartości w kontekście instrukcji

Odwoływanie się do parametrów i zmiennych

Po instalacji konsola Firebase wyświetla zawartość pliku POSTINSTALL rozszerzenia. Jeśli w pliku POSTINSTALL odwołujesz się do parametrów i zmiennych związanych z funkcjami (patrz tabela poniżej), konsola wypełnia te odniesienia rzeczywistymi wartościami zainstalowanej instancji.

Wskazówka: w przypadku wartości, które mogą być długie (takich jak ścieżka bazy danych lub adres URL funkcji), odwołaj się do parametru lub zmiennej na końcu zdań i sekcji. Ta najlepsza praktyka ułatwia czytanie zdań w konsoli Firebase, gdy zawartość pliku POSTINSTALL jest renderowana z rzeczywistymi wartościami.

Uzyskaj dostęp do skonfigurowanych wartości parametrów w pliku POSTINSTALL , korzystając z następującej składni: ${param: PARAMETER_NAME }

Możesz także odwoływać się do następujących zmiennych związanych z funkcjami , tylko w pliku POSTINSTALL . Firebase obsługuje te zmienne, dzięki czemu możesz łatwiej udzielać użytkownikom wskazówek po instalacji. Można ich używać tylko w pliku POSTINSTALL , ponieważ wartości tych zmiennych są dostępne dopiero po instalacji.

W tej tabeli function-name jest wartością pola name w obiekcie zasobu funkcji w pliku extension.yaml .

Odniesienie do zmiennej związanej z funkcją	Opis	Wartość zmiennej (automatycznie wypełniana przez Firebase po instalacji rozszerzenia)
${function: function-name .location}
	Lokalizacja , w której wdrożono funkcję	Przykładowa wartość: us-central1
${function: function-name .name}
	Nazwa ostatecznie wdrożonej funkcji, która zawiera identyfikator instancji rozszerzenia	Uogólniony format: ext- extension-instance-id - function-name Przykładowa wartość: ext-my-awesome-extension-6m31-yourFunctionName
${function: function-name .url} (dotyczy tylko funkcji HTTP)
	Adres URL ostatecznie wdrożonej funkcji, do której kod klienta może wysyłać żądania HTTP	Uogólniony format: https:// deployment-location - project-id .cloudfunctions.net/ name-of-final-deployed-function Przykładowa wartość: https://us-central1-project-123.cloudfunctions.net/ext-my-awesome-extension-6m31-yourFunctionName

Pomocny tekst standardowy POSTINSTALL

Zalecamy użycie jak największej ilości poniższego standardowego tekstu, odpowiedniego dla Twojego rozszerzenia.

W przypadku wszystkich rozszerzeń dołącz następującą sekcję, aby pomóc użytkownikom monitorować zainstalowane rozszerzenia:

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.

Dokumentowanie sposobu uruchomienia rozszerzenia

W dokumentacji użytkownika rozszerzenia musisz poinstruować użytkowników, jak uruchomić rozszerzenie. Instrukcje te mogą być tak szczegółowe, jak uznasz to za konieczne, ale pamiętaj o najlepszych praktykach pisania pliku POSTINSTALL . Aby uzyskać wskazówki dotyczące podawania tych instrukcji, rozwiń poniższą sekcję dotyczącą Twojego rozszerzenia.

Rozszerzenia wywoływane zdarzeniami w tle

Użytkownicy mogą uruchamiać rozszerzenie uruchamiane zdarzeniem w tle na różne sposoby, w zależności od używanych produktów.

Wprowadź zmiany bezpośrednio w konsoli

Możesz poinstruować użytkowników, aby wprowadzali zmiany uruchamiające rozszerzenie bezpośrednio w konsoli Firebase, szczególnie na potrzeby wstępnego testowania rozszerzenia. Załóżmy na przykład, że Twoje rozszerzenie tworzy nowy dokument Cloud Firestore za każdym razem, gdy tworzony jest nowy użytkownik Firebase Authentication. Możesz poinstruować użytkowników, aby przetestowali zainstalowaną instancję Twojego rozszerzenia, ręcznie dodając nowego użytkownika uwierzytelniającego w konsoli. Następnie mogą obserwować nowy dokument utworzony w sekcji Cloud Firestore konsoli.

Dodaj kod po stronie klienta

Jeśli ma to zastosowanie, możesz także poinstruować użytkowników, jak dodać kod po stronie klienta, aby uruchomić rozszerzenie. Powinieneś skierować użytkowników do oficjalnej dokumentacji interfejsów API, z których będą musieli korzystać. Możesz także dołączyć przykładowe aplikacje lub skompilowane próbki klientów, aby pomóc użytkownikom zintegrować rozszerzenie z ich aplikacją (przykład znajdziesz w rozszerzeniu Distributed Counter ).

Rozszerzenia wywoływane żądaniem HTTP

Aby użytkownicy mogli uruchomić funkcję wyzwalaną żądaniem HTTP (a tym samym rozszerzenie), musisz podać im nazwę wdrożonej funkcji lub jej adres URL .

Nazwa ostatecznie wdrożonej funkcji różni się od name określonej w obiekcie zasobu funkcji w pliku extension.yaml . Aby uwzględnić w projekcie wiele instalacji tego samego rozszerzenia, Firebase zmienia nazwę funkcji w następującym formacie: ext- extension-instance-id - function-name .

Poniższe punktory to sugerowany szablonowy tekst, który należy umieścić w pliku POSTINSTALL rozszerzenia. Po instalacji konsola Firebase wyświetla zawartość pliku POSTINSTALL i wypełnia te odniesienia faktycznie skonfigurowanymi wartościami dla zainstalowanej instancji. Na przykład, jeśli zdefiniowałeś funkcję o nazwie yourFunction , możesz dołączyć następujące elementy (jeśli ma to zastosowanie):

• Dla funkcji HTTP onRequest

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

• Dla funkcji wywoływalnych przez HTTP ( 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}`**.
  

Ważne: zanim użytkownicy będą mogli korzystać z rozszerzenia wywoływanego żądaniem HTTP, muszą udostępnić publicznie funkcje wdrożone dla rozszerzenia. Szczegółowe instrukcje, które należy przekazać użytkownikom, znajdują się w powyższych przykładowych tekstach .

Zapisywanie pliku CHANGELOG

Jaka zawartość znajduje się w tym pliku?

Każde rozszerzenie musi mieć plik CHANGELOG.md , który dokumentuje zmiany zawarte w każdej nowej wersji Twojego rozszerzenia, którą publikujesz. Umieść każdą wersję pod nagłówkiem poziomu 2 ( ## ); w przeciwnym razie możesz użyć dowolnego formatowania Markdown.

Poniższy przykład jest fragmentem jednego z oficjalnych rozszerzeń:

## 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.

Gdzie ta treść jest wyświetlana użytkownikowi?

• W konsoli Firebase i CLI, gdy użytkownicy uaktualnią Twoje rozszerzenie do nowych wersji. Konsola Firebase i interfejs CLI wyświetlają tylko zmiany, które weszły w życie, gdyby użytkownik ukończył aktualizację.
• Repozytorium kodu źródłowego Twojego rozszerzenia (w katalogu rozszerzenia).