Membuat dokumentasi pengguna untuk ekstensi Anda

Setiap ekstensi harus memiliki dokumentasi yang menjelaskan kepada pengguna tentang fungsi ekstensi dan cara menggunakannya.

Dokumentasi minimum dan wajib adalah kumpulan tiga file markdown ini:

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

Selain itu, Anda juga harus mempertimbangkan untuk memproduksi:

  • File README untuk repositori publik ekstensi.
  • Tutorial, panduan, dan referensi yang lebih panjang yang dipublikasikan di situs Anda sendiri dan ditautkan di PREINSTALL.md.

Untuk mempelajari beberapa praktik terbaik serta frasa dan struktur umum, sebaiknya tinjau file yang disediakan bersama ekstensi Firebase resmi.

Membuat README

Direktori ekstensi Anda dapat berisi file README, jika diinginkan. Perhatikan bahwa perintah firebase ext:dev:init tidak otomatis membuat file ini untuk Anda.

Meskipun begitu, Firebase CLI mendukung perintah praktis berikut untuk otomatis membuat file README berisi konten yang diambil dari file extension.yaml dan PREINSTALL.md:

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

Semua file README untuk ekstensi Firebase resmi dibuat menggunakan perintah tersebut.

Menambahkan informasi penginstalan

Setelah Anda menulis atau membuat README, tambahkan informasi penginstalan pada README. Anda dapat menggunakan cuplikan berikut sebagai template:

---

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

---

Menulis file PREINSTALL

File PREINSTALL adalah ringkasan ekstensi Anda, yaitu sejenis halaman "pemasaran".

Konten apa yang ada dalam file ini?

  • Deskripsi lengkap fungsionalitas ekstensi Anda
  • Daftar prasyarat, seperti penyiapan database atau akses ke layanan non-Google (contoh)
  • Deskripsi singkat semua tugas pra-penginstalan dan petunjuknya
  • Deskripsi singkat semua tugas pasca-penginstalan (contoh) (petunjuk terperinci dapat dilihat di POSTINSTALL)
  • Deskripsi singkat semua implikasi penagihan (dimulai dengan teks boilerplate)

Di mana konten ini ditampilkan kepada pengguna?

Gambar konten pra-penginstalan di <span class=Firebase console">
Konten pra-penginstalan di Firebase console

Gambar besar konten pra-penginstalan di <span class=Firebase console">

  • Di halaman ekstensi di extensions.dev.
  • Repositori kode sumber untuk ekstensi Anda (di dalam direktori ekstensi)
  • Sebagai bagian dari README ekstensi (jika Anda menggunakan flag --markdown > README.md Firebase CLI)

File PREINSTALL tidak dapat mengakses parameter value untuk ekstensi, jadi jangan berharap referensi parameter akan dirender dengan nilai sebenarnya.

Apa saja praktik terbaik?

  • Batasi isi lengkap file PREINSTALL di bawah satu halaman, jika memungkinkan
  • Sediakan level detail yang benar-benar perlu diketahui pengguna akhir sebelum menginstal ekstensi
  • Cantumkan petunjuk terperinci dalam file POSTINSTALL atau file tambahan lainnya
  • Sebutkan secara singkat apakah Anda menyediakan alat atau skrip lain untuk mendukung ekstensi

Sebaiknya Anda menggunakan teks boilerplate berikut sebanyak mungkin, sesuai yang berlaku untuk ekstensi Anda. Kami telah memberikan beberapa contoh, tetapi poin yang paling penting adalah memastikan semua layanan yang ditagih Google dan non-Google tercantum.

Anda dapat menggunakan resource berikut untuk menemukan detail harga produk yang tepat:

Untuk semua ekstensi, sertakan bagian ini untuk membantu pengguna memahami implikasi penagihan:

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

Menulis file POSTINSTALL

File POSTINSTALL adalah halaman petunjuk pasca-penginstalan terperinci untuk ekstensi Anda.

Konten apa yang ada dalam file ini?

  • Petunjuk terperinci semua tugas pasca-penginstalan yang diperlukan, seperti menyiapkan aturan keamanan Firebase atau menambahkan kode sisi klien (contoh)
  • Petunjuk umum tentang cara untuk segera mencoba ekstensi yang diinstal (contohnya, "buka konsol, lalu lakukan ini")
  • Informasi dasar tentang cara memicu ekstensi, terutama untuk ekstensi yang dipicu permintaan HTTP
  • Petunjuk singkat tentang cara memantau ekstensi yang diinstal (dimulai dengan teks boilerplate)

Di mana konten ini ditampilkan kepada pengguna?

Gambar konten pasca-penginstalan di <span class=Firebase console">
Konten pasca-penginstalan di Firebase console

Gambar besar konten pasca-penginstalan di <span class=Firebase console">

  • Di Firebase console setelah pengguna menginstal ekstensi Anda (di kartu detail ekstensi yang diinstal)

  • Repositori kode sumber untuk ekstensi Anda (di dalam direktori ekstensi)

File POSTINSTALL dapat mengakses parameter value dan beberapa variabel terkait fungsi untuk ekstensi. Saat konten POSTINSTALL ditampilkan di Firebase console, nilai sebenarnya akan ditampilkan, bukan referensi parameter atau variabel. Pelajari lebih lanjut cara mereferensikan parameter dan variabel dalam file POSTINSTALL Anda di bawah.

Apa saja praktik terbaik?

  • Buat konten lengkap file POSTINSTALL tetap ringkas, tetapi deskriptif.
  • Kelompokkan konten menggunakan judul untuk memisahkan tugas atau konsep yang berbeda.
  • Pertimbangkan untuk memublikasikan petunjuk terperinci terkait alur kerja atau tugas tertentu di situs Anda (contoh) atau dalam file markdown tambahan dalam repositori ekstensi (contoh ).
  • Referensikan parameter dan variabel terkait fungsi sehingga pengguna melihat nilai yang dikonfigurasi dalam konteks petunjuk

Mereferensikan parameter dan variabel

Setelah penginstalan, Firebase console akan menampilkan isi file POSTINSTALL ekstensi. Jika Anda mereferensikan parameter dan variabel terkait fungsi (lihat tabel di bawah) di file POSTINSTALL, maka konsol akan mengisi referensi ini dengan nilai sebenarnya untuk instance yang diinstal.

Akses parameter value yang dikonfigurasi dalam file POSTINSTALL menggunakan sintaksis berikut: ${param:PARAMETER_NAME}

Anda juga dapat mereferensikan variabel terkait fungsi berikut dalam file POSTINSTALL saja. Firebase mendukung variabel ini sehingga Anda dapat lebih mudah memberikan panduan bagi pengguna pasca-penginstalan. Variabel ini hanya tersedia untuk digunakan dalam file POSTINSTALL karena nilainya baru tersedia setelah penginstalan.

Dalam tabel ini, function-name adalah nilai untuk kolom name di objek resource fungsi dalam extension.yaml.

Referensi untuk variabel terkait fungsi Deskripsi Nilai variabel (diisi otomatis oleh Firebase setelah ekstensi diinstal)
${function:function-name.location}
Lokasi fungsi di-deploy Contoh nilai:
us-central1
${function:function-name.name}
Nama fungsi akhir yang di-deploy, yang menyertakan ID instance ekstensi

Format umum:
ext-extension-instance-id-function-name

Contoh nilai:
ext-my-awesome-extension-6m31-yourFunctionName

${function:function-name.url} (hanya berlaku untuk fungsi HTTP)
URL dari fungsi akhir yang di-deploy, yang dapat menerima permintaan HTTP dari kode klien

Format umum:
https://deployment-location-project-id.cloudfunctions.net/name-of-final-deployed-function

Contoh nilai:
https://us-central1-project-123.cloudfunctions.net/ext-my-awesome-extension-6m31-yourFunctionName

Sebaiknya Anda menggunakan teks boilerplate berikut sebanyak mungkin, sesuai yang berlaku untuk ekstensi Anda.

Untuk semua ekstensi, sertakan bagian berikut untuk membantu pengguna memantau ekstensi yang mereka instal:

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.

Mendokumentasikan cara memicu ekstensi

Dalam dokumentasi pengguna ekstensi, Anda perlu memberikan petunjuk kepada pengguna tentang cara memicu ekstensi. Petunjuk ini dapat sangat terperinci, jika menurut Anda perlu, tetapi ingatlah praktik terbaik dalam menulis file POSTINSTALL. Untuk panduan cara memberikan petunjuk ini, perluas bagian di bawah yang sesuai dengan ekstensi Anda.

Pengguna dapat memicu ekstensi yang dipicu peristiwa latar belakang dalam berbagai cara, bergantung produk yang terlibat.

Membuat perubahan secara langsung di konsol

Anda dapat memberikan petunjuk kepada pengguna untuk membuat perubahan pemicu ekstensi secara langsung di Firebase console, terutama untuk pengujian awal ekstensi Anda. Misalnya, ekstensi Anda membuat dokumen Cloud Firestore baru setiap kali pengguna Firebase Authentication baru dibuat. Anda dapat memberikan petunjuk kepada pengguna untuk menguji instance ekstensi yang diinstal secara manual, dengan menambahkan pengguna Authentication baru di konsol. Selanjutnya, mereka dapat mengamati dokumen baru yang dibuat di bagian Cloud Firestore pada konsol.

Menambahkan kode sisi klien

Jika berlaku, Anda juga dapat memberikan petunjuk kepada pengguna tentang cara menambahkan kode sisi klien untuk memicu ekstensi. Anda harus mengarahkan pengguna ke dokumentasi resmi untuk API yang perlu digunakan. Anda juga dapat menyertakan contoh aplikasi atau contoh klien yang dikompilasi untuk membantu pengguna mengintegrasikan ekstensi ke dalam aplikasinya (sebagai contoh, lihat ekstensi Distributed Counter).

Agar pengguna dapat memicu fungsi yang dipicu permintaan HTTP (dan juga ekstensi), Anda perlu memberikan nama atau URL fungsi yang di-deploy kepada mereka.

Nama fungsi akhir yang di-deploy tidak sama dengan name yang Anda tentukan di objek resource fungsi dalam extension.yaml. Untuk mengakomodasi beberapa penginstalan ekstensi yang sama dalam sebuah project, Firebase mengganti nama fungsi tersebut dalam format: ext-extension-instance-id-function-name.

Poin-poin berikut adalah teks boilerplate yang disarankan untuk disertakan dalam file POSTINSTALL ekstensi Anda. Setelah penginstalan, Firebase console akan menampilkan isi file POSTINSTALL dan mengisi referensi ini dengan nilai sebenarnya yang dikonfigurasi untuk instance yang diinstal. Contohnya, jika menentukan fungsi bernama yourFunction, Anda dapat menyertakan yang berikut ini (sebagaimana berlaku):

  • Untuk fungsi onRequest HTTP

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

  • Untuk fungsi callable (onCall) HTTP

    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}`**.

Menulis file CHANGELOG

Konten apa yang ada dalam file ini?

Setiap ekstensi harus memiliki file CHANGELOG.md yang mendokumentasikan perubahan yang disertakan dalam setiap versi baru ekstensi yang Anda publikasikan. Letakkan setiap versi di bawah header level 2 (##); jika tidak, Anda dapat menggunakan pemformatan Markdown yang Anda sukai.

Contoh berikut adalah kutipan dari salah satu ekstensi resmi:

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

Di mana konten ini ditampilkan kepada pengguna?

  • Di Firebase console dan CLI, saat pengguna melakukan upgrade ke versi ekstensi yang baru. Firebase console dan CLI hanya menampilkan perubahan yang akan diterapkan jika pengguna ingin menyelesaikan upgrade.
  • Repositori kode sumber ekstensi Anda (di dalam direktori ekstensi).