Creare la documentazione utente per l'estensione

Ogni estensione deve disporre di una documentazione che spieghi agli utenti il funzionamento e come utilizzarla.

La documentazione minima obbligatoria è questo insieme di tre file markdown:

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

Dovresti anche valutare la possibilità di produrre:

• Un file README per il repository pubblico dell'estensione.
• Tutorial, guide e riferimenti più lunghi pubblicati sul tuo sito web e collegati nel tuo PREINSTALL.md.

Per conoscere alcune best practice e la formulazione e la struttura comuni, ti consigliamo di esaminare i file disponibili con le estensioni Firebase ufficiali.

Creazione di un file README in corso...

La directory dell'estensione può contenere facoltativamente un file README. Tieni presente che Il comando firebase ext:dev:init non ne genera automaticamente uno.

L'interfaccia a riga di comando Firebase, tuttavia, supporta il seguente comando pratico per generare automaticamente un file README con contenuti estratti dal tuo extension.yaml file e il tuo file PREINSTALL.md:

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

Tutti i file README per le estensioni Firebase ufficiali vengono generati utilizzando questo comando.

Aggiungi informazioni di installazione

Dopo aver scritto o generato un file README, aggiungi le informazioni di installazione. Tu puoi usare il seguente snippet come modello:

---

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

---

Scrittura di un file PREINSTALL in corso...

Il file PREINSTALL è la panoramica dell'estensione, un tipo di "marketing" .

Quali contenuti sono presenti in questo file?

• Descrizione completa delle funzionalità della tua estensione
• Elenco di prerequisiti, come la configurazione del database o l'accesso a un server non Google servizio (esempio)
• Breve descrizione di eventuali attività di preinstallazione e relative istruzioni
• Breve descrizione di eventuali attività di post-installazione (esempio) (istruzioni dettagliate in POSTINSTALL)
• Breve descrizione delle eventuali implicazioni relative alla fatturazione (inizia con il testo standard)

Dove vengono mostrati questi contenuti all'utente?

Console Firebase">

Preinstalla i contenuti nella Firebaseconsole

Console Firebase">

• Nella pagina dell'estensione su extensions.dev.
• Il repository del codice sorgente dell'estensione (all'interno della directory dell'estensione)
• Nell'ambito del file README dell'estensione (se utilizzi il flag Firebase CLI --markdown > README.md)

I file PREINSTALL non possono accedere ai valori parametro per l'estensione, pertanto tu non dovrebbero aspettarsi che i riferimenti ai parametri vengano visualizzati con i valori effettivi.

Quali sono alcune best practice?

• Se possibile, mantieni i contenuti completi del file PREINSTALL in meno di una pagina
• Fornisci il livello di dettaglio che un utente finale deve assolutamente conoscere prima di installare l'estensione
• Inserisci istruzioni dettagliate nel file POSTINSTALL o in un altro file supplementari
• Menziona brevemente se fornisci altri strumenti o script per supportare l'estensione

Testo boilerplate PREINSTALL utile

Ti consigliamo di utilizzare il più possibile il seguente testo standard, in base alle caratteristiche della tua estensione. Abbiamo fornito alcuni esempi, ma il punto più importante è assicurarsi che tutti i servizi fatturati di Google e non Google siano elencati.

Per trovare i dettagli corretti dei prezzi dei prodotti, puoi utilizzare le seguenti risorse:

• Listino prezzi dei prodotti Google Cloud
• Panoramica dei prezzi di Firebase

Per tutte le estensioni, includi questa sezione per aiutare gli utenti a comprendere le implicazioni della 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 in corso...

Il file POSTINSTALL è la post-installazione dettagliata della tua estensione pagina di istruzioni.

Quali sono i contenuti di questo file?

• Istruzioni dettagliate per qualsiasi attività obbligatoria post-installazione, come impostare le regole di sicurezza di Firebase o aggiungere codice lato client (esempio)
• Istruzioni generiche su come provare immediatamente l'estensione installata (ad es. "vai alla console, poi fai così")
• Informazioni di base su come attivare l'estensione, in particolare per Estensioni attivate da richieste HTTP
• Brevi istruzioni su come monitorare l'estensione installata (inizia con testo boilerplate)

Dove vengono mostrati all'utente questi contenuti?

Console Firebase">

Contenuti post-installazione nella console Firebase

Console Firebase">

• Nella console Firebase dopo che un utente ha installato la tua estensione (nella scheda dettagliata dell'estensione installata)

  • Assicurati di esaminare la visualizzazione dei contenuti di POSTINSTALL entro di installare un'estensione in un progetto.

• Il repository del codice sorgente dell'estensione (all'interno della directory dell'estensione)

I file POSTINSTALL possono accedere ai valori parametro e a diverse funzioni correlate variabili per l'estensione. Quando i contenuti di POSTINSTALL vengono visualizzati nella console Firebase, vengono visualizzati i valori effettivi anziché i riferimenti ai parametri o alle variabili. Scopri di più di seguito su come fare riferimento a parametri e variabili nel file POSTINSTALL.

Quali sono alcune best practice?

• Mantieni l'intero contenuto del file POSTINSTALL conciso, ma descrittivo.
• Suddividi i contenuti utilizzando le intestazioni per suddividere attività o concetti distinti.
• Valuta la possibilità di pubblicare istruzioni dettagliate per un determinato flusso di lavoro o un'attività sul tuo sito web (esempio) o in file Markdown supplementari all'interno del repository dell'estensione (esempio).
• Parametri di riferimento e relativi funzioni variabili in modo che l'utente veda i valori configurati nel contesto delle istruzioni

Fare riferimento a parametri e variabili

Dopo l'installazione, la console Firebase mostra i contenuti del file POSTINSTALL dell'estensione. Se nel file POSTINSTALL fai riferimento a parametri e variabili correlate alle funzioni (vedi la tabella di seguito), la console compila questi riferimenti con i valori effettivi dell'istanza installata.

Suggerimento: per i valori che possono essere lunghi (ad esempio un percorso del database o un URL di funzione), fai riferimento al parametro o alla variabile alla fine delle frasi e delle sezioni. Questa best practice semplifica la lettura delle frasi nella console Firebase quando i contenuti del file POSTINSTALL sono visualizzato con valori effettivi.

Accedi ai valori dei parametri configurati nel file POSTINSTALL utilizzando il metodo seguente sintassi: ${param:PARAMETER_NAME}

Puoi anche fare riferimento alle seguenti variabili relative alle funzioni solo nel POSTINSTALL. Firebase supporta queste variabili in modo da poter fornire più facilmente indicazioni agli utenti dopo l'installazione. Sono solo disponibili per l'uso nel file POSTINSTALL perché i valori di queste variabili disponibili solo dopo l'installazione.

In questa tabella, function-name è il valore del parametro name nel campo all'interno di extension.yaml.

Riferimento per la variabile relativa alla funzione	Descrizione	Valore variabile (compilato automaticamente da Firebase dopo l'installazione dell'estensione)
${function:function-name.location}
	Località in cui è eseguita il deployment della funzione	Valore di esempio: us-central1
${function:function-name.name}
	Nome della funzione implementata finale, che include l'ID istanza dell'estensione	Formato generalizzato: ext-extension-instance-id-function-name Valore di esempio: ext-my-awesome-extension-6m31-yourFunctionName
${function:function-name.url} (applicabile solo per le funzioni HTTP)
	URL della funzione di cui è stato eseguito il deployment finale, a cui il codice client può effettuare richieste HTTP	Formato generalizzato: https://deployment-location-project-id.cloudfunctions.net/name-of-final-deployed-function Valore di esempio: https://us-central1-project-123.cloudfunctions.net/ext-my-awesome-extension-6m31-yourFunctionName

Testo boilerplate POSTINSTALL utile

Ti consigliamo di utilizzare la maggior quantità possibile del seguente testo boilerplate, applicabile per la tua estensione.

Per tutte le estensioni, includi la seguente sezione per aiutare gli utenti a monitorare le estensioni installate:

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.

Documentazione su come attivare un'estensione

Nella documentazione per gli utenti dell'estensione, devi indicare agli utenti come attivare l'estensione. Queste istruzioni possono essere il più dettagliate possibile ritenuto necessario, ma tieni a mente le best practice per scrivere un POSTINSTALL. Per indicazioni su come fornire queste istruzioni, espandi la sezione di seguito che si applica alla tua estensione.

Estensioni attivate da eventi in background

Gli utenti possono attivare un'estensione in background attivata da eventi in vari modi, a seconda dei prodotti coinvolti.

Apportare modifiche direttamente nella console

Puoi chiedere agli utenti di apportare modifiche che attivano l'estensione direttamente nella consoleFirebase, in particolare per i test iniziali dell'estensione. Per ad esempio, supponiamo che l'estensione crei un nuovo documento Cloud Firestore ogni volta viene creato un nuovo utente Firebase Authentication. Puoi chiedere agli utenti di testare un'istanza installata della tua estensione aggiungendo manualmente un nuovo utente Authentication nella console. Potrà quindi osservare il nuovo documento creato nella sezione Cloud Firestore della console.

Aggiungi codice lato client

Se applicabile, puoi anche indicare agli utenti come aggiungere codice lato client per attivare l'estensione. Devi indirizzare gli utenti alla documentazione ufficiale per le API che dovranno utilizzare. Puoi anche includere app di esempio o esempi di client compilati per aiutare gli utenti a integrare l'estensione nella loro app (consulta l'estensione Contatore distribuito per un esempio).

Estensioni attivate da richieste HTTP

Per fare in modo che gli utenti possano attivare una funzione attivata da richieste HTTP (e quindi il estensione), devi fornire la funzione deployed name o alle relative URL.

Il nome della funzione finale di cui è stato eseguito il deployment non è uguale a name che specificato nell'oggetto di risorsa della funzione all'interno di extension.yaml. Per supportare più installazioni della stessa estensione in un progetto, Firebase rinomina la funzione in questo formato: ext-extension-instance-id-function-name.

I seguenti elenchi puntati sono testi di boilerplate suggeriti da includere nel file POSTINSTALL dell'estensione. Dopo l'installazione, la console Firebase visualizza i contenuti del file POSTINSTALL e compila questi riferimenti con i valori configurati effettivi per l'istanza installata. Ad esempio, se hai definito una funzione denominata yourFunction, puoi includere quanto segue (a seconda dei casi):

• Per le funzioni HTTP onRequest

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

Importante: prima che gli utenti possano utilizzare un'estensione attivata da richieste HTTP, Occorre rendere pubblicamente accessibili le funzioni di cui è stato eseguito il deployment per l'estensione. Le istruzioni dettagliate da fornire agli utenti si trovano nel testo del boilerplate esempi riportati sopra.

Scrittura di un file CHANGELOG

Quali sono i contenuti di questo file?

Ogni estensione deve avere un file CHANGELOG.md che documenti le modifiche incluse in ogni nuova versione dell'estensione pubblicata. Inserisci ogni versione sotto un'intestazione di livello 2 (##); in caso contrario, puoi utilizzare la formattazione Markdown che preferisci.

L'esempio seguente è un estratto di 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 mostrati questi contenuti all'utente?

• Nella console Firebase e nella CLI, quando gli utenti eseguono l'upgrade alle nuove versioni della tua estensione. La console Firebase e la CLI mostrano solo le modifiche che entrerebbero in vigore se l'utente completasse l'upgrade.
• Il repository del codice sorgente dell'estensione (all'interno della directory dell'estensione).