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

Minimalna wymagana dokumentacja to zestaw 3 plików Markdown:

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

Dodatkowo warto też zadbać o produkty:

• Plik README dla publicznego repozytorium rozszerzenia.
• dłuższe samouczki, przewodniki i materiały referencyjne opublikowane w Twojej witrynie i powiązane z nią przez link 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 parametr Polecenie firebase ext:dev:init nie generuje go automatycznie.

Interfejs wiersza poleceń Firebase obsługuje jednak to polecenie ułatwiające automatyczne generowanie pliku README zawierającego treści pobrane 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 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ń wykonywanych po instalacji (przykład). Szczegółowe instrukcje znajdziesz w dokumentacji POSTINSTALL.
• Krótki opis wpływu na płatności (zaczyna się od tekst stały)

Gdzie użytkownik zobaczy te treści?

Konsola Firebase">

Wstępnie zainstaluj treści w konsoli Firebase

Konsola Firebase">

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

Pliki PREINSTALL nie mają dostępu do wartości parametrów rozszerzenia, więc nie należy się spodziewać, ż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 PREINSTALL tekst standardowy

Zalecamy użycie jak największej części tego tekstu w przypadku rozszerzenia. Podaliśmy kilka przykładów, ale najważniejsze jest to, aby uwzględnić wszystkie usługi płatne Google i niepochodzące od Google.

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

• Lista cen 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 wszystkich wymaganych zadań po instalacji, takich jak konfigurowanie reguł zabezpieczeń Firebase czy dodawanie 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 wskazówki dotyczące monitorowania zainstalowanego rozszerzenia (zacznij od tekstu standardowego).

Gdzie te treści są wyświetlane użytkownikowi?

Konsola Firebase">

Umieszczanie treści po zainstalowaniu w konsoli Firebase

Konsola 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 rozszerzenia);

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

Jakie są sprawdzone metody?

• Plik POSTINSTALL powinien zawierać zwięzłą, ale jednocześnie wyczerpująco opisową treść.
• Podziel treści na sekcje za pomocą nagłówków, aby oddzielić od siebie poszczególne zadania lub pojęcia.
• Zastanów się nad opublikowaniem szczegółowych instrukcji dotyczących konkretnego procesu lub zadania na swojej stronie internetowej (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

Odwoływanie się do parametrów i zmiennych

Po zainstalowaniu 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 zainstalowanego wystąpienia.

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

Aby uzyskać dostęp do skonfigurowanych wartości parametru w pliku POSTINSTALL, użyj tej składni: ${param:PARAMETER_NAME}

Możesz też odwoływać się do tych zmiennych związanych z funkcją tylko w pliku POSTINSTALL. Firebase obsługuje te zmienne, aby ułatwić użytkownikom korzystanie z aplikacji po jej zainstalowaniu. 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ść 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 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 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 funkcji rozmieszczonej, 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 w polu POSTINSTALL

Zalecamy użycie jak największej części tego tekstu w przypadku 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 rozszerzenia musisz poinformować użytkowników, jak je aktywować. Te instrukcje mogą być tak szczegółowe, jak uznasz to za konieczne, ale pamiętaj o sprawdzonym sposobie tworzenia pliku POSTINSTALL. Aby uzyskać wskazówki dotyczące przekazywania tych instrukcji, rozwiń sekcję poniżej dotyczy Twojego rozszerzenia.

rozszerzenia wywoływane przez zdarzenia 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 poprosić użytkowników o wprowadzenie zmian bezpośrednio w konsoli Firebase, zwłaszcza na potrzeby wstępnego testowania rozszerzenia. Załóżmy, że Twoja rozszerzenie tworzy nowy dokument Cloud Firestore za każdym razem, gdy zostanie utworzony nowy użytkownik Firebase Authentication. Możesz poprosić użytkowników o przetestowanie zainstalowanego wystąpienia rozszerzenia, ręcznie dodając nowego użytkownika Authentication w konsoli. Następnie mogą obserwować nowy dokument w sekcji Cloud Firestore konsoli.

Dodaj kod po stronie klienta

W stosownych przypadkach możesz też poinformować użytkowników, jak dodać kod po stronie klienta, aby wywołać rozszerzenie. Należy skierować użytkowników do oficjalnej dokumentacji interfejsów API, których będą potrzebować. Możesz też dołączyć przykładowe aplikacje lub skompilowane przykładowe aplikacje klienckie, aby ułatwić użytkownikom zintegrowanie rozszerzenia z ich aplikacją (np. rozszerzenie Distributed Counter).

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. Aby uwzględnić wiele instalacji tego samego rozszerzenia w projekcie, Firebase zmienia nazwę funkcji w tym formacie: ext-extension-instance-id-function-name.

Podane niżej punkty to sugerowany tekst, który należy umieścić w pliku POSTINSTALL rozszerzenia. Po zainstalowaniu konsola Firebase wyświetla zawartość pliku POSTINSTALL i wypełnia te odwołania z rzeczywistymi wartościami skonfigurowanymi dla zainstalowanej instancji. Jeśli na przykład zdefiniujesz funkcję o nazwie yourFunction, możesz użyć tego kodu:

• Funkcje HTTP onRequest

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

• W przypadku wywoływalnych przez HTTP (onCall) funkcji

  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, które należy przekazać użytkownikom, znajdują się w standardowych tekstach powyżej.

Zapisywanie pliku CHANGELOG

Jakie treści 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 innych przypadkach możesz użyć dowolnego formatowania Markdown.

Poniżej znajduje się 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 są wyświetlane użytkownikowi?

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