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

Każde rozszerzenie musi mieć dokumentację, która informuje użytkowników, do czego służy i jak go używać.

Minimalna wymagana dokumentacja to ten zestaw 3 plików Markdown:

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

Warto też rozważyć przygotowanie:

• Plik README publicznego repozytorium rozszerzenia.
• Dłuższe samouczki, przewodniki i materiały referencyjne opublikowane w Twojej witrynie i połączone z PREINSTALL.md.

Aby poznać sprawdzone metody oraz typowe sformułowania i struktury, zalecamy zapoznanie się z plikami dostępnymi w oficjalnych rozszerzeniach Firebase.

Tworzenie pliku README

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

Interfejs wiersza poleceń Firebase obsługuje jednak to wygodne polecenie, które automatycznie generuje plik README zawierający treści pobrane z plików extension.yaml i PREINSTALL.md:

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

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

Dodawanie informacji o instalacji

Po napisaniu lub wygenerowaniu pliku README dodaj do niego informacje o instalacji. Możesz użyć tego fragmentu kodu 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)

---

Zapisuję plik PREINSTALL

Plik PREINSTALL zawiera przegląd rozszerzenia, czyli rodzaj strony „marketingowej”.

Jakie treści znajdują się w tym pliku?

• wyczerpujący opis funkcji rozszerzenia;
• Lista wymagań wstępnych, takich jak konfiguracja bazy danych lub dostęp do usługi innej niż Google (przykład)
• Krótki opis wszystkich zadań przed instalacją i instrukcje ich wykonania.
• Krótki opis zadań po instalacji (przykład) (szczegółowe instrukcje znajdują się w pliku POSTINSTALL)
• Krótki opis wpływu na płatności (zacznij od standardowego tekstu)

Gdzie te treści wyświetlają się użytkownikowi?

konsola Firebase">

Fabrycznie zainstalowane treści w konsoli Firebase

Konsola Firebase">

• na stronie rozszerzenia w witrynie extensions.dev,
• repozytorium kodu źródłowego rozszerzenia (w katalogu rozszerzenia);
• w pliku README rozszerzenia (jeśli używasz flagi --markdown > README.md interfejsu wiersza poleceń Firebase).

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 postępowania w takiej sytuacji?

• Jeśli to możliwe, cała treść pliku PREINSTALL powinna mieścić się na jednej stronie.
• Podaj poziom szczegółowości, który użytkownik musi znać przed zainstalowaniem rozszerzenia.
• Szczegółowe instrukcje umieść w pliku POSTINSTALL lub innych plikach dodatkowych.
• Krótko wspomnij, czy udostępniasz inne narzędzia lub skrypty do obsługi rozszerzenia.

Przydatny tekst standardowy PREINSTALL

Zalecamy użycie jak największej ilości poniższego tekstu, o ile ma on zastosowanie do Twojego rozszerzenia. Podaliśmy kilka przykładów, ale najważniejsze jest, aby wymienić wszystkie usługi rozliczane przez Google i inne firmy.

Aby znaleźć prawidłowe informacje o cenach produktów, możesz skorzystać z tych materiałów:

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

W przypadku wszystkich rozszerzeń dodaj tę sekcję, aby pomóc użytkownikom zrozumieć konsekwencje związane z płatnościami:

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

Zapisuję plik POSTINSTALL

Plik POSTINSTALL to strona ze szczegółowymi instrukcjami po instalacji rozszerzenia.

Jakie treści znajdują się w tym pliku?

• Szczegółowe instrukcje dotyczące wymaganych zadań po instalacji, takich jak konfigurowanie reguł zabezpieczeń Firebase lub dodawanie kodu po stronie klienta (przykład).
• Ogólne instrukcje dotyczące natychmiastowego wypróbowania zainstalowanego rozszerzenia (np. „Przejdź do konsoli, a następnie wykonaj te czynności”).
• podstawowe informacje o tym, jak aktywować rozszerzenie, zwłaszcza w przypadku rozszerzeń aktywowanych przez żądanie HTTP;
• Krótkie instrukcje dotyczące monitorowania zainstalowanego rozszerzenia (zacznij od standardowego tekstu).

Gdzie te treści wyświetlają się użytkownikowi?

Konsola Firebase">

Treści po instalacji w konsoli Firebase

Konsola Firebase">

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

  • Sprawdź, jak wyświetlają się treści POSTINSTALL, instalując rozszerzenie w rzeczywistym projekcie.

• repozytorium kodu źródłowego rozszerzenia (w katalogu rozszerzenia);

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

Jakie są sprawdzone metody postępowania w takiej sytuacji?

• Treść pliku POSTINSTALL powinna być zwięzła, ale opisowa.
• Podziel treść na sekcje za pomocą nagłówków, aby oddzielić różne zadania lub pojęcia.
• Rozważ opublikowanie szczegółowych instrukcji dotyczących konkretnego przepływu pracy lub zadania w swojej witrynie (przykład) lub w dodatkowych plikach Markdown w repozytorium rozszerzenia (przykład).
• Parametry referencyjne i zmienne związane z funkcjami, aby użytkownik widział 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 odwołania rzeczywistymi wartościami zainstalowanej instancji.

Wskazówka: w przypadku wartości, które mogą być długie (np. ścieżka bazy danych lub adres URL funkcji), odwołuj się do parametru lub zmiennej na końcu zdań i sekcji. Dzięki tej sprawdzonej metodzie zdania są łatwiejsze do odczytania 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, używając tej składni: ${param:PARAMETER_NAME}

Możesz też odwoływać się do tych zmiennych związanych z funkcjami tylko w pliku POSTINSTALL. Firebase obsługuje te zmienne, aby ułatwić Ci przekazywanie 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 to wartość pola name w obiekcie zasobu funkcji w extension.yaml.

Dokumentacja zmiennej związanej z funkcją	Opis	Wartość zmiennej (wypełniana automatycznie przez Firebase po zainstalowaniu rozszerzenia)
${function:function-name.location}
	Lokalizacja, w której 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 ogólny: 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 końcowej wdrożonej funkcji, do której kod klienta może wysyłać żądania HTTP.	Format ogólny: 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 standardowy POSTINSTALL

Zalecamy użycie jak największej ilości poniższego tekstu, o ile ma on zastosowanie do Twojego rozszerzenia.

W przypadku wszystkich rozszerzeń dodaj tę sekcję, aby pomóc użytkownikom monitorować 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 rozszerzenia dla użytkowników musisz poinstruować ich, jak je aktywować. Instrukcje te mogą być tak szczegółowe, jak uważasz za konieczne, ale pamiętaj o sprawdzonych metodach pisania pliku POSTINSTALL. Aby dowiedzieć się, jak podać te instrukcje, rozwiń sekcję poniżej, która dotyczy Twojego rozszerzenia.

Rozszerzenia uruchamiane przez zdarzenia w tle

Użytkownicy mogą aktywować rozszerzenie wywoływane przez zdarzenie w tle na różne sposoby, w zależności od używanych usług.

Wprowadzanie zmian bezpośrednio w konsoli

Możesz poinstruować użytkowników, aby wprowadzali zmiany wywołujące rozszerzenie bezpośrednio w konsoli Firebase, zwłaszcza podczas wstępnego testowania rozszerzenia. Załóżmy na przykład, że 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ę rozszerzenia, ręcznie dodając nowego użytkownika Authentication w konsoli. Następnie mogą zobaczyć nowy dokument utworzony w sekcji Cloud Firestore konsoli.

Dodawanie kodu po stronie klienta

W stosownych przypadkach możesz też poinstruować użytkowników, jak dodać kod po stronie klienta, aby aktywować rozszerzenie. Użytkowników należy kierować do oficjalnej dokumentacji interfejsów API, których będą musieli używać. Możesz też dołączyć przykładowe aplikacje lub skompilowane przykłady klientów, aby ułatwić użytkownikom integrację rozszerzenia z ich aplikacją (przykład znajdziesz w rozszerzeniu Distributed Counter).

Rozszerzenia wywoływane przez żądanie HTTP

Aby użytkownicy mogli aktywować funkcję wywoływaną przez żądanie HTTP (a tym samym rozszerzenie), musisz podać im nazwę lub adres URL wdrożonej funkcji.

Nazwa ostatecznie wdrożonej funkcji nie jest taka sama jak name określona w obiekcie zasobu funkcji w extension.yaml. Aby umożliwić wielokrotną instalację tego samego rozszerzenia w projekcie, Firebase zmienia nazwę funkcji na ten format: ext-extension-instance-id-function-name.

Poniższe punkty zawierają sugerowany tekst, który można umieścić w pliku POSTINSTALL rozszerzenia. Po instalacji konsola Firebase wyświetla zawartość pliku POSTINSTALL i wypełnia te odwołania rzeczywistymi skonfigurowanymi wartościami zainstalowanej instancji. Jeśli na przykład zdefiniujesz funkcję o nazwie yourFunction, możesz uwzględnić te elementy (w zależności od potrzeb):

• 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: zanim użytkownicy będą mogli korzystać z rozszerzenia wywoływanego przez żądanie HTTP, muszą udostępnić publicznie funkcje wdrożone na potrzeby rozszerzenia. Szczegółowe instrukcje, które należy przekazać użytkownikom, znajdziesz w powyższych przykładowych tekstach.

Zapisywanie pliku CHANGELOG

Jakie treści znajdują się w tym pliku?

Każde rozszerzenie musi zawierać plik CHANGELOG.md, który dokumentuje zmiany wprowadzone w każdej nowej wersji rozszerzenia. Każdą wersję umieść pod nagłówkiem poziomu 2 (##). Poza tym możesz używać dowolnego formatowania Markdown.

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 te treści wyświetlają się użytkownikowi?

• W konsoli Firebase i interfejsie wiersza poleceń, gdy użytkownicy przechodzą na nowe wersje rozszerzenia. Konsola Firebase i interfejs wiersza poleceń wyświetlają tylko zmiany, które zostałyby wprowadzone, gdyby użytkownik dokończył uaktualnienie.
• Repozytorium kodu źródłowego rozszerzenia (w katalogu rozszerzenia).