Ogni estensione deve avere una documentazione che insegni agli utenti cosa fa l'estensione e come usarla.
La documentazione minima richiesta è questo insieme di tre file di markdown:
-
PREINSTALL.md -
POSTINSTALL.md -
CHANGELOG.md
Inoltre, dovresti anche considerare di produrre:
- Un file
READMEper il repository pubblico dell'estensione. - Tutorial, guide e riferimenti di forma più lunga pubblicati sul tuo sito Web e collegati nel tuo
PREINSTALL.md.
Per apprendere alcune best practice, frasi e strutture comuni, ti consigliamo di esaminare i file disponibili con le estensioni Firebase ufficiali .
Creazione di un README
La directory dell'estensione può facoltativamente contenere un file README. Tieni presente che il comando firebase ext:dev:init non ne genera automaticamente uno per te.
La CLI di Firebase, tuttavia, supporta il seguente comodo comando per generare automaticamente un file README contenente contenuti estratti dal file extension.yaml e dal file PREINSTALL.md :
firebase ext:info ./path/to/extension --markdown > README.md
Tutti i file README per le estensioni ufficiali Firebase vengono generati utilizzando questo comando.
Aggiungi informazioni sull'installazione
Dopo aver scritto o generato un file README, aggiungivi le informazioni di installazione. Puoi utilizzare il seguente snippet come modello:
--- ## 🧩 Install this extension ### Console [][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) ---
Scrittura di un file PREINSTALL
Il file PREINSTALL è la panoramica della tua estensione, una sorta di pagina di "marketing".
Che contenuto c'è in questo file?
- Descrizione completa delle funzionalità della tua estensione
- Elenco dei prerequisiti, come la configurazione del database o l'accesso a un servizio non Google ( esempio )
- Breve descrizione delle eventuali attività di pre-installazione e relative istruzioni
- Breve descrizione di eventuali attività post-installazione ( esempio ) (le istruzioni dettagliate sono disponibili in
POSTINSTALL) - Breve descrizione di eventuali implicazioni sulla fatturazione (iniziare con il testo standard )
Dove vengono visualizzati questi contenuti all'utente?
- Nella pagina dell'estensione su extensions.dev .
- Il repository del codice sorgente per la tua estensione (all'interno della directory delle estensioni)
- Come parte del file README dell'estensione (se utilizzi la CLI Firebase
--markdown > README.md
I file PREINSTALL non possono accedere ai valori dei parametri per l'estensione, quindi non dovresti aspettarti che i riferimenti ai parametri vengano visualizzati con i valori effettivi.
Quali sono alcune delle migliori pratiche?
- Mantieni l'intero contenuto del file
PREINSTALLsotto una pagina , se possibile - Fornisci il livello di dettaglio che un utente finale deve assolutamente conoscere prima di installare l'estensione
- Inserisci istruzioni dettagliate nel file
POSTINSTALLo in altri file supplementari - Indica brevemente se fornisci altri strumenti o script per supportare l'estensione
Ti consigliamo di utilizzare quanto più testo standard possibile, a seconda della tua estensione. Abbiamo fornito alcuni esempi, ma il punto più importante è garantire che siano elencati tutti i servizi fatturati da Google e non Google.
Puoi utilizzare le seguenti risorse per trovare i dettagli corretti sui prezzi dei prodotti:
Per tutte le estensioni, includi questa sezione per aiutare gli utenti a comprendere le implicazioni sulla fatturazione:
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>.
Scrittura di un file POSTINSTALL
Il file POSTINSTALL è la pagina di istruzioni dettagliate post-installazione dell'estensione.
Che contenuto c'è in questo file?
- Istruzioni dettagliate per eventuali attività post-installazione richieste , come l'impostazione delle regole di sicurezza Firebase o l'aggiunta di codice lato client ( esempio )
- Istruzioni generiche su come provare immediatamente l'estensione installata (ad esempio, "vai alla console, quindi esegui questa operazione")
- Informazioni di base su come attivare l'estensione, in particolare per le estensioni attivate da richiesta HTTP
- Brevi indicazioni su come monitorare l'estensione installata (iniziare con il testo standard )
Dove vengono visualizzati questi contenuti all'utente?
Nella console Firebase dopo che un utente ha installato la tua estensione (nella scheda dei dettagli dell'estensione installata)
- Assicurati di rivedere la visualizzazione del contenuto
POSTINSTALLinstallando l'estensione in un progetto reale .
- Assicurati di rivedere la visualizzazione del contenuto
Il repository del codice sorgente per la tua estensione (all'interno della directory delle estensioni)
I file POSTINSTALL possono accedere ai valori dei parametri e a diverse variabili relative alle funzioni per l'estensione. Quando il contenuto POSTINSTALL viene visualizzato nella console Firebase, vengono visualizzati i valori effettivi anziché i parametri o i riferimenti alle variabili. Scopri di più di seguito su come fare riferimento a parametri e variabili nel file POSTINSTALL .
Quali sono alcune delle migliori pratiche?
- Mantieni l'intero contenuto del file
POSTINSTALLconciso ma descrittivo. - Separare il contenuto utilizzando intestazioni per suddividere compiti o concetti distinti.
- Valuta la possibilità di pubblicare istruzioni dettagliate per un flusso di lavoro o un'attività specifica sul tuo sito web ( esempio ) o in file di markdown supplementari all'interno del repository delle estensioni ( esempio ).
- Parametri di riferimento e variabili correlate alle funzioni in modo che l'utente possa vederne i valori configurati nel contesto delle istruzioni
Riferimento a parametri e variabili
Dopo l'installazione, la console Firebase visualizza il contenuto del file POSTINSTALL dell'estensione. Se fai riferimento a parametri e variabili correlate alle funzioni (vedi tabella seguente) nel file POSTINSTALL , la console popola questi riferimenti con i valori effettivi per l'istanza installata.
Accedi ai valori dei parametri configurati nel file POSTINSTALL utilizzando la seguente sintassi:${param: PARAMETER_NAME }
È inoltre possibile fare riferimento alle seguenti variabili relative alle funzioni solo nel file POSTINSTALL . Firebase supporta queste variabili in modo che tu possa fornire più facilmente indicazioni agli utenti dopo l'installazione. Sono disponibili solo per l'uso nel file POSTINSTALL perché i valori per queste variabili non sono disponibili fino a dopo l'installazione.
In questa tabella, function-name è il valore del campo name nell'oggetto risorsa della funzione all'interno di extension.yaml .
| Riferimento per la variabile correlata alla funzione | Descrizione | Valore variabile (popolato automaticamente da Firebase dopo l'installazione dell'estensione) |
|---|---|---|
${function: function-name .location} | ||
| Luogo in cui viene distribuita la funzione | Valore di esempio:us-central1 | |
${function: function-name .name} | ||
| Nome della funzione distribuita finale, che include l'ID istanza dell'estensione | Formato generalizzato: Valore di esempio: | |
${function: function-name .url} (applicabile solo per le funzioni HTTP) | ||
| URL della funzione distribuita finale, a cui il codice client può effettuare richieste HTTP | Formato generalizzato: Valore di esempio: | |
Ti consigliamo di utilizzare quanto più testo standard possibile, a seconda della tua estensione.
Per tutte le estensioni, includi la seguente sezione per aiutare gli utenti a monitorare l'estensione installata:
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.
Documentare come attivare un'estensione
Nella documentazione utente della tua estensione, devi istruire i tuoi utenti su come attivare la tua estensione. Queste istruzioni possono essere dettagliate quanto ritieni necessario, ma tieni presente le migliori pratiche per scrivere un file POSTINSTALL . Per indicazioni su come fornire queste istruzioni, espandi la sezione seguente applicabile alla tua estensione.
I tuoi utenti possono attivare un'estensione attivata da un evento in background in vari modi, a seconda dei prodotti coinvolti.
Apporta modifiche direttamente nella console
Puoi chiedere ai tuoi utenti di apportare modifiche che attivano l'estensione direttamente nella console Firebase, in particolare per il test iniziale della tua estensione. Ad esempio, supponiamo che la tua estensione crei un nuovo documento Cloud Firestore ogni volta che viene creato un nuovo utente di autenticazione Firebase. Puoi chiedere ai tuoi utenti di testare un'istanza installata della tua estensione aggiungendo manualmente un nuovo utente di autenticazione nella console. Possono quindi osservare il nuovo documento creato nella sezione Cloud Firestore della console.
Aggiungi codice lato client
Se applicabile, puoi anche istruire i tuoi utenti su come aggiungere codice lato client per attivare la tua estensione. Dovresti indirizzare gli utenti alla documentazione ufficiale per le API che dovranno utilizzare. Puoi anche includere app di esempio o esempi client compilati per aiutare gli utenti a integrare l'estensione nella loro app (fai riferimento all'estensione Distributed Counter per un esempio).
Affinché i tuoi utenti possano attivare una funzione attivata da una richiesta HTTP (e quindi l'estensione), devi fornire loro il nome della funzione distribuita o il suo URL .
Il nome della funzione distribuita finale non è lo stesso name specificato nell'oggetto risorsa della funzione all'interno di extension.yaml . Per ospitare più installazioni della stessa estensione in un progetto, Firebase rinomina la funzione in questo formato:ext- extension-instance-id - function-name .
I seguenti punti elenco sono testo standard suggerito da includere nel file POSTINSTALL dell'estensione. Dopo l'installazione, la console Firebase visualizza il contenuto del file POSTINSTALL e popola questi riferimenti con i valori effettivamente configurati per l'istanza installata. Ad esempio, se hai definito una funzione denominata yourFunction , potresti includere quanto segue (a seconda dei casi):
Per le funzioni HTTP
onRequestTo trigger this extension, make a request to or visit the following URL: **`${function:yourFunction.url}`**.Per le funzioni richiamabili 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}`**.
Scrivere un file CHANGELOG
Che contenuto c'è in questo file?
Ogni estensione deve avere un file CHANGELOG.md che documenta le modifiche incluse in ogni nuova versione dell'estensione che pubblichi. Metti ogni versione sotto un'intestazione di livello 2 ( ## ); altrimenti, puoi utilizzare la formattazione Markdown che preferisci.
L'esempio seguente è un estratto da una delle estensioni ufficiali:
## 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.
Dove vengono visualizzati questi contenuti all'utente?
- Nella console Firebase e nella CLI, quando gli utenti eseguono l'aggiornamento alle nuove versioni della tua estensione. La console Firebase e la CLI visualizzano solo le modifiche che avrebbero effetto se l'utente completasse l'aggiornamento.
- Il repository del codice sorgente della tua estensione (all'interno della directory dell'estensione).