Utwórz dokumentację użytkownika dotyczącą rozszerzenia

Każde rozszerzenie musi mieć dokumentację z informacjami dla użytkowników i jak z nich korzystać.

Wymagana dokumentacja to co najmniej 3 pliki Markdown:

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

Dodatkowo warto też zadbać o produkty:

• Plik README publicznego repozytorium rozszerzenia.
• Dłuższe samouczki, przewodniki i materiały referencyjne opublikowane na własnej stronie internetowej połączone w PREINSTALL.md.

Aby poznać sprawdzone metody oraz typowe sformułowania i strukturę, zalecamy przeglądać pliki dostępne oficjalnych rozszerzeń Firebase.

Tworzenie pliku README

Katalog rozszerzenia może opcjonalnie zawierać plik README. Pamiętaj, że parametr Polecenie firebase ext:dev:init nie generuje go automatycznie.

Interfejs wiersza poleceń Firebase obsługuje jednak poniższe wygodne polecenie, aby automatycznie wygeneruj plik README zawierający treści pobrane z Twojego Plik extension.yaml i Twój plik PREINSTALL.md:

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

Wszystkie pliki README dla oficjalne rozszerzenia Firebase generowane za pomocą tego polecenia.

Dodaj informacje o instalacji

Po napisaniu lub wygenerowaniu pliku README dodaj do niego informacje o instalacji. Ty Możesz użyć tego 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 streszczenie rozszerzenia, typ „marketingowy” stronę.

Jaką zawartość zawiera ten plik?

• Wyczerpujący opis funkcji rozszerzenia
• Lista wymagań wstępnych, takich jak konfiguracja bazy danych lub dostęp do usługa (przykład)
• Krótki opis zadań preinstalacyjnych i ich instrukcje
• Krótki opis zadań po instalacji (przykład) (szczegółowe instrukcje znajdziesz w POSTINSTALL)
• Krótki opis wpływu na płatności (zaczyna się od tekst stały)

Gdzie użytkownik zobaczy te treści?

Wstępne instalowanie treści w konsoli Firebase

.

• Na stronie rozszerzenia extensions.dev.
• Repozytorium kodu źródłowego rozszerzenia (w katalogu rozszerzeń)
• W pliku README rozszerzenia (jeśli używasz interfejsu wiersza poleceń Firebase) --markdown > README.md)

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

Jakie są sprawdzone metody?

• Całą zawartość pliku PREINSTALL umieść na jednej stronie, jeśli to możliwe
• Podaj poziom szczegółowości, który musi znać użytkownik zanim zainstalujesz rozszerzenie.
• Umieść szczegółowe instrukcje w pliku POSTINSTALL lub w innym pliki dodatkowe
• Krótko wspomnij, czy udostępniasz inne narzędzia lub skrypty do obsługi rozszerzenie

Przydatny tekst w polu PREINSTALL

Zalecamy użycie jak największej ilości z tych tekstów standardowych, dotyczące danego rozszerzenia. Podaliśmy kilka przykładów, ale najbardziej ważne jest, aby zapewnić, że wszystkie usługi Google i spoza Google są na liście produktów.

Szczegółowe informacje o cenach produktów znajdziesz w tych materiałach:

• Cennik usług Google Cloud
• Omówienie cennika Firebase

W przypadku wszystkich rozszerzeń uwzględnij tę sekcję, aby ułatwić użytkownikom zrozumienie płatności konsekwencje:

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ółowe dane rozszerzenia po instalacji z instrukcjami.

Jaką zawartość zawiera ten plik?

• szczegółowe instrukcje dotyczące wymaganych zadań po instalacji; np. przez skonfigurowanie reguł zabezpieczeń Firebase lub dodanie kodu po stronie klienta. (przykład)
• Ogólne instrukcje dotyczące natychmiastowego testowania zainstalowane rozszerzenie (na przykład „otwórz konsolę, a następnie wykonaj to działanie”)
• Podstawowe informacje o tym, jak aktywować rozszerzenie, zwłaszcza w przypadku: Rozszerzenia wywoływane przez żądania HTTP
• Krótkie instrukcje monitorowania zainstalowanego rozszerzenia (zaczynając od tekst stały)

Gdzie użytkownik zobaczy te treści?

Publikowanie treści po instalacji w konsoli Firebase

.

• Gdy użytkownik zainstaluje rozszerzenie w konsoli Firebase (w sekcji karty szczegółów zainstalowanego rozszerzenia).

  • Sprawdź wyświetlanie treści POSTINSTALL do zainstalowanie rozszerzenia w projektu.

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

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

Jakie są sprawdzone metody?

• Pełna treść pliku POSTINSTALL powinna być zwięzła, ale opisowa.
• Podziel treści na sekcje za pomocą nagłówków, aby rozdzielić zadania lub zadania. i koncepcjach.
• Rozważ opublikowanie szczegółowych instrukcji przepływ pracy lub zadanie w Twojej witrynie (przykład) lub w dodatkowych plikach Markdown w repozytorium rozszerzeń (przykład).
• Parametry odwołania i związane z funkcjami zmienne tak aby użytkownik widział swoje skonfigurowane wartości w kontekście instrukcji

Parametry i zmienne odwołania

Po instalacji w konsoli Firebase wyświetli się zawartość pliku POSTINSTALL rozszerzenia. Jeśli odwołasz się do parametrów i funkcji związanych zmiennych (patrz tabela poniżej) w pliku POSTINSTALL, a następnie uzupełnia te odwołania wartościami rzeczywistymi dotyczącymi zainstalowanej instancji.

Wskazówka: w przypadku wartości, które mogą być długie (np. baza danych ścieżki lub adresu URL funkcji), odwołaj się do parametru lub zmiennej na końcu argumentu zdaniami i sekcjami. Ta sprawdzona metoda ułatwia czytanie zdań w w konsoli Firebase, gdy zawartość pliku POSTINSTALL zostanie renderowanych z rzeczywistymi wartościami.

Uzyskaj dostęp do skonfigurowanych wartości parametrów w pliku POSTINSTALL za pomocą ta składnia: ${param:PARAMETER_NAME}

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

W tej tabeli function-name to wartość atrybutu name w polu obiektu zasobu funkcji w ciągu extension.yaml.

Dokumentacja zmiennej związanej z funkcją	Opis	Wartość zmiennej (wypełniana automatycznie przez Firebase po zainstalowaniu rozszerzenia)
${function:function-name.location}
	Lokalizacja gdzie funkcja jest wdrożona	Przykładowa wartość: us-central1
${function:function-name.name}
	Nazwa ostatecznej wdrożonej funkcji, która zawiera identyfikator instancji rozszerzenia	Format uogólniony: 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 ostatecznej wdrożonej funkcji, do której można dodać kod klienta wykonywanie żądań HTTP	Format uogólniony: 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

Przydatny tekst w polu POSTINSTALL

Zalecamy użycie jak największej ilości z tych tekstów standardowych, dotyczące danego rozszerzenia.

W przypadku wszystkich rozszerzeń dołącz następującą sekcję, aby ułatwić użytkownikom monitorowanie zainstalowane rozszerzenie:

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 aktywowania rozszerzenia

W dokumentacji użytkownika rozszerzenia musisz poinformować użytkowników o tym, jak uruchomić rozszerzenie. Te instrukcje mogą być bardzo szczegółowe ale pamiętaj o sprawdzonych metodach tworzenia POSTINSTALL. Aby uzyskać wskazówki dotyczące przekazywania tych instrukcji, rozwiń sekcję poniżej dotyczy Twojego rozszerzenia.

Rozszerzenia wywoływane zdarzeniami w tle

Użytkownicy mogą aktywować rozszerzenie wywołane w tle przez zdarzenia w tle na różne sposoby, w zależności od produktów.

Wprowadzanie zmian bezpośrednio w konsoli

Możesz poinstruować użytkowników, aby wprowadzali zmiany wywołujące rozszerzenie bezpośrednio w w konsoli Firebase, zwłaszcza do wstępnego testowania rozszerzenia. Dla: Załóżmy na przykład, że rozszerzenie tworzy nowy dokument Cloud Firestore za każdym razem, zostanie utworzony nowy użytkownik Uwierzytelniania Firebase. Możesz polecić użytkownikom testowanie zainstalowana instancja Twojego rozszerzenia przez ręczne dodanie nowego użytkownika uwierzytelniania w konsoli. Mogą następnie obserwować nowy dokument utworzony Sekcja Cloud Firestore w konsoli.

Dodaj kod po stronie klienta

W razie potrzeby możesz też poinformować użytkowników o sposobie dodawania kodu po stronie klienta , aby uruchomić rozszerzenie. Wskaż użytkownikom oficjalną dokumentację dostępnych dla nich interfejsów API. Możesz również dołączyć przykładowe aplikacje lub skompilować przykładowe klienta, aby pomóc użytkownikom zintegrować to rozszerzenie ze aplikacji (zapoznaj się z Rozszerzenie Rozproszony licznik ).

Rozszerzenia aktywowane przez żądania HTTP

Aby użytkownicy mogli aktywować funkcję wywoływaną przez żądanie HTTP (a tym samym ), musisz udostępnić mu wdrożoną funkcję name lub parametr Adres URL.

Nazwa ostatecznej wdrożonej funkcji jest inna niż name określona w obiekcie zasobu funkcji w argumencie extension.yaml. Do wiele instalacji tego samego rozszerzenia w projekcie, Firebase zmienia nazwę funkcji w następujący sposób: ext-extension-instance-id-function-name.

Poniższe punktory to sugerowany tekst, który warto uwzględnić w POSTINSTALL rozszerzenia. Po instalacji konsola Firebase wyświetla zawartość pliku POSTINSTALL i wypełnia te odwołania z rzeczywistymi wartościami skonfigurowanymi dla zainstalowanej instancji. Na przykład, jeśli funkcję o nazwie yourFunction, możesz dodać funkcję następujące (stosownie do przypadku):

• Funkcje HTTP onRequest

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

• W przypadku funkcji wywoływanych 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: aby użytkownicy mogli używać rozszerzenia wywołanego przez żądania HTTP, muszą udostępnić publicznie funkcje wdrożone na potrzeby rozszerzenia. Szczegółowe instrukcje dla użytkowników znajdują się w tym artykule. przykłady powyżej.

Zapisywanie pliku CHANGELOG

Jaką zawartość zawiera ten plik?

Każde rozszerzenie musi mieć plik CHANGELOG.md zawierający dokumenty dotyczące zmian dołączana do każdej nowej wersji opublikowanego przez Ciebie rozszerzenia. Umieść każdą wersję pod nagłówkiem poziomu 2 (##); W przeciwnym razie użyj dowolnego formatu Markdown zgodnie z Twoim preferowanym formatem.

Poniższy przykład to fragment 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 użytkownik zobaczy te treści?

• W konsoli Firebase i w interfejsie wiersza poleceń, gdy użytkownicy przejdą na nowe wersje Twojego . Konsola Firebase i interfejs wiersza poleceń wyświetlają tylko te zmiany, które zacznie obowiązywać, jeśli użytkownik dokończy uaktualnienie.
• Repozytorium kodu źródłowego rozszerzenia (w katalogu rozszerzeń).