Memublikasikan ekstensi

Halaman ini menjelaskan cara memublikasikan ekstensi di Extensions Hub.

Sebelum memulai

Untuk memublikasikan ekstensi, Anda harus terlebih dahulu mendaftar sebagai penayang ekstensi.

Sumber yang dapat diverifikasi

Semua ekstensi yang dipublikasikan di Extensions Hub harus memiliki sumber yang dapat diverifikasi secara publik. Daripada mengupload kode sumber ekstensi langsung ke Extensions Hub, Anda justru sebaiknya menentukan lokasi sumber, lalu Extensions Hub akan mendownloadnya dan mem-build ekstensi dari sana.

Saat ini, hal itu berarti membuat kode sumber ekstensi Anda tersedia di repositori GitHub publik.

Mengupload dari sumber yang dapat diverifikasi memiliki beberapa manfaat:

  • Pengguna dapat memeriksa kode sumber revisi tertentu dari ekstensi yang akan diinstal.
  • Anda dapat memastikan hanya mengupload kode sumber yang ingin Anda upload, dan bukan, misalnya, kode sumber yang sedang dikerjakan atau file yang salah dari proses pengembangan.

Siklus pengembangan yang direkomendasikan

Alat pengembangan Firebase Extensions mendukung upload ekstensi versi pra-rilis, yang memudahkan Anda menguji ekstensi dan proses penginstalan ekstensi di lingkungan yang sama dengan yang pada akhirnya akan menjadi lingkungan rilis.

Kemampuan ini memungkinkan siklus pengembangan seperti berikut:

  1. Mengembangkan dan melakukan iterasi dengan cepat pada ekstensi Anda menggunakan Firebase Emulator Suite.

  2. Menguji ekstensi Anda di project sungguhan dengan menginstalnya dari sumber lokal:

    firebase ext:install /path/to/extension
firebase deploy --only extensions

  3. Mengupload versi pra-rilis ke Extensions Hub (lihat di bawah). Mendistribusikan link penginstalan untuk pengujian yang lebih luas, dan melakukan iterasi dengan mengupload lebih banyak versi pra-rilis sesuai kebutuhan.

  4. Mengupload versi final yang stabil ke Extensions Hub (lihat di bawah) dan mengirimkannya untuk ditinjau. Jika lulus peninjauan, ekstensi akan dipublikasikan di Extensions Hub.

  5. Menambahkan nomor versi di extension.yaml dan mengulangi siklus ini untuk versi ekstensi berikutnya.

Mengupload ekstensi baru

Untuk mengupload ekstensi untuk pertama kalinya:

  1. Opsional: Commit kode Anda ke repositori GitHub publik.

  2. Jalankan perintah ext:dev:upload Firebase CLI:

    GitHub

    firebase ext:dev:upload your_publisher_id/your_extension_id

    Sumber lokal

    cd /path/to/extension
firebase ext:dev:upload your_publisher_id/your_extension_id --local

    Dalam pemanggilan perintah, Anda menentukan hal berikut:

    • ID penayang yang Anda daftarkan.

    • String ID yang akan mengidentifikasi ekstensi. Beri nama ekstensi Anda dengan format berikut: firebase-product-description-of-tasks-performed. Contoh: firestore-bigquery-export

    Perintah tersebut akan meminta informasi tambahan:

    • Jika Anda mengupload dari GitHub:

      • URL ke repositori ekstensi di GitHub. Perhatikan bahwa repositori dapat berisi beberapa ekstensi asalkan setiap ekstensi memiliki root unik.

        Saat Anda mengupload ekstensi baru untuk pertama kalinya, repositori akan terdaftar sebagai sumber kanonis untuk ekstensi Anda.

      • Direktori di repositori yang berisi ekstensi Anda.

      • Referensi Git dari commit tempat Anda ingin mem-build sumber versi ekstensi. Ini dapat berupa hash commit, tag, atau nama cabang.

    • Tahap rilis dari versi yang Anda upload.

      Tahap alpha, beta, dan rc (kandidat rilis) ditujukan untuk mengupload versi pra-rilis yang akan diinstal oleh penguji. Gunakan salah satu tahapan ini untuk upload awal ekstensi baru.

      Tahap stable digunakan untuk rilis publik yang akan dipublikasikan di Extensions Hub. Mengupload rilis stable akan otomatis memulai peninjauan, dan jika dinyatakan lulus peninjauan, ekstensi akan dipublikasikan.

    Perhatikan bahwa Anda tidak menentukan nomor versi—nilai ini berasal dari file extension.yaml. Saat Anda mengupload ekstensi versi pra-rilis, tahap dan nomor upload akan ditambahkan ke versi tersebut. Misalnya, jika extension.yaml menyebutkan versi 1.0.1 dan Anda mengupload kandidat rilis, versi tersebut akan menghasilkan versi 1.0.1-rc.0; mengupload kandidat rilis lain dari versi yang sama akan otomatis menaikkan hitungan, sehingga menghasilkan 1.0.1-rc.1, dan seterusnya.

Setelah mengupload ekstensi versi pra-rilis, Anda dapat membagikannya kepada orang lain untuk pengujian. Pengguna dapat menginstal ekstensi Anda dengan salah satu dari dua cara berikut:

  • Dengan konsol: Pengguna dapat menginstal ekstensi dengan mengklik link dalam format berikut:

    https://console.firebase.google.com/project/_/extensions/install?ref=your_publisher_id/your_extension_id@version

    Anda dapat membagikan link langsung kepada penguji.

  • Dengan CLI: Pengguna dapat menginstal ekstensi dengan meneruskan string ID ekstensi ke perintah ext:install:

    firebase ext:install your_publisher_id/your_extension_id@version \
    --project=destination_project_id

Mengupload versi yang telah diperbarui

Setelah mengupload versi pertama ekstensi, Anda dapat mengupload update untuk memperbaiki masalah, menambahkan fitur, atau melanjutkan tahap rilis. Saat Anda mengupload versi baru, pengguna yang menginstal ekstensi versi lama akan diminta untuk melakukan upgrade di Firebase console.

Untuk mengupload update:

  1. Opsional: Commit kode Anda ke repositori Git publik.

  2. Jalankan perintah ext:dev:upload Firebase CLI:

    GitHub

    firebase ext:dev:upload your_publisher_id/your_extension_id

    Kali ini Anda tidak akan diminta untuk menentukan repositori GitHub atau direktori utama ekstensi karena sudah dikonfigurasi untuk ekstensi Anda. Jika telah memfaktorkan ulang struktur repositori atau bermigrasi ke repositori baru, Anda dapat mengubahnya dengan argumen perintah --root dan --repo.

    Sumber lokal

    cd /path/to/extension
firebase ext:dev:upload your_publisher_id/your_extension_id --local

Mengirim ekstensi untuk publikasi

Jika Anda sudah siap merilis ekstensi secara publik:

  1. Commit kode Anda ke repositori Git publik. (Wajib untuk rilis publik.)

  2. Jalankan perintah ext:dev:upload Firebase CLI, dengan menentukan stable sebagai tahap rilis:

    firebase ext:dev:upload your_publisher_id/your_extension_id

  3. Jika Anda sebelumnya telah memublikasikan versi ekstensi, mengupload rilis stabil yang baru akan otomatis mengirimkan ekstensi untuk ditinjau.

    Jika Anda mengupload rilis stabil pertama dari ekstensi tersebut, temukan ekstensi tersebut di dasbor penayang, lalu klik Publish to Extensions Hub.

Setelah dikirim, peninjauan dapat memakan waktu beberapa hari. Jika diterima, ekstensi akan dipublikasikan ke Extensions Hub. Jika ditolak, Anda akan menerima pesan yang menjelaskan alasannya; Anda kemudian dapat mengatasi masalah yang dilaporkan dan mengirimkannya kembali untuk ditinjau.

Untuk mempercepat peninjauan dan meningkatkan peluang lulus pada percobaan pertama, sebelum mengirimkan, periksa kembali hal berikut:

  • Anda telah menguji ekstensi dan proses penginstalan secara menyeluruh.
  • Dokumentasi Anda lengkap dan benar, serta dirender dengan baik di Firebase console.
  • Nama dan branding penayang mengidentifikasi Anda dengan jelas dan akurat sebagai penayang.
  • Nama, deskripsi, dan ikon ekstensi merepresentasikan tujuan ekstensi Anda dengan jelas dan akurat.
  • Anda telah menerapkan tag yang bermanfaat dan akurat.
  • Anda telah mendeklarasikan di extension.yaml semua API Google dan non-Google yang Anda gunakan, serta semua jenis peristiwa yang dikeluarkan oleh ekstensi Anda.
  • Anda meminta akses hanya ke peran yang diperlukan agar ekstensi dapat berfungsi, dan Anda telah menjelaskan dengan jelas kepada pengguna mengapa Anda memerlukan akses tersebut.
  • File sumber Anda dengan jelas dilisensikan berdasarkan persyaratan Apache-2.0.

Mengelola ekstensi yang diupload dan dipublikasikan

Menayangkan daftar ekstensi yang diupload

Untuk mencantumkan ekstensi yang telah Anda upload dengan ID penayang, lakukan salah satu hal berikut:

Dasbor penayang

Lihat daftar tersebut di dasbor penayang.

Firebase CLI

Jalankan perintah ext:dev:list:

firebase ext:dev:list your_publisher_id

Melihat penggunaan ekstensi yang diupload

Untuk melihat penggunaan ekstensi yang telah Anda upload dengan ID penayang, lakukan salah satu hal berikut:

Dasbor penayang

Dasbor penayang memiliki metrik penggunaan kumulatif untuk semua ekstensi dan metrik individual untuk setiap ekstensi.

Firebase CLI

Jalankan perintah ext:dev:usage:

firebase ext:dev:usage your_publisher_id

Menghentikan penggunaan versi ekstensi

Pada saat tertentu, Anda mungkin ingin menghentikan penggunaan ekstensi versi lama. Misalnya, jika Anda merilis versi baru yang memperbaiki bug kritis atau memperbarui dependensi dengan update keamanan penting, Anda harus mencegah pengguna baru menginstal versi lama dan mendorong pengguna lama untuk melakukan upgrade.

Untuk menghentikan penggunaan versi ekstensi, lakukan salah satu hal berikut:

Dasbor penayang

  1. Di dasbor penayang, klik ekstensi untuk membuka tampilan detailnya.
  2. Pilih versi yang tidak akan Anda gunakan lagi.
  3. Klik Penghentian versi.

Firebase CLI

Jalankan perintah ext:dev:deprecate:

firebase ext:dev:deprecate your_publisher_id/your_extension_id versions \
    [--message "deprecation_message"]

Anda dapat menentukan satu versi atau beberapa versi. Contoh:

  • 1.0.2
  • 1.1.0-1.1.7
  • <1.2.0
  • 1.1.*

Versi ekstensi yang tidak digunakan lagi tidak dicantumkan di Extensions Hub dan tidak dapat diinstal. Pengguna yang project-nya masih menginstal versi yang tidak lagi digunakan akan melihat pesan yang mendorong mereka untuk melakukan upgrade; sementara itu, mereka masih dapat menggunakan dan mengonfigurasi ulang ekstensi.

Jika semua versi ekstensi tidak digunakan lagi, ekstensi dianggap tidak digunakan lagi dan akan dihapus dari Extensions Hub. Mengupload versi baru dari ekstensi yang tidak digunakan lagi akan otomatis memulai peninjauan, dan jika diterima, ekstensi akan dipublikasikan lagi di Extensions Hub.

Untuk membalikkan penghentian penggunaan, gunakan dasbor penayang, atau jalankan perintah ext:dev:undeprecate Firebase CLI:

firebase ext:dev:undeprecate your_publisher_id/your_extension_id versions

Lampiran: Pemecahan masalah error build

Saat Anda mengupload ekstensi, backend akan terlebih dahulu mem-build kode sumber menggunakan proses berikut:

  1. Meng-clone repositori GitHub dan memeriksa referensi sumber yang ditentukan.

  2. Menginstal dependensi NPM dengan menjalankan npm clean-install di setiap direktori sumber fungsi yang ditentukan dalam extension.yaml (lihat sourceDirectory di resource Cloud Function).

    Perhatikan hal berikut:

    • Setiap file package.json harus memiliki file package-lock.json yang sesuai. Untuk informasi selengkapnya, lihat npm-ci.

    • Skrip pascapenginstalan tidak akan dijalankan selama penginstalan dependensi. Jika build kode sumber Anda mengandalkan skrip pascapenginstalan, faktorkan ulang sebelum mengupload.

  3. Mem-build kode Anda dengan menjalankan npm run build di setiap direktori sumber fungsi yang ditentukan di extension.yaml.

Hanya direktori utama ekstensi Anda yang akan disimpan di paket ekstensi akhir yang akan dibagikan.

Jika Anda mendapatkan error build saat mengupload ekstensi, ulangi langkah-langkah build di atas secara lokal di direktori baru sampai tidak ada error, lalu coba upload lagi.