Creare la documentazione utente per l'estensione

Ogni estensione deve avere una documentazione che insegni agli utenti cosa fa l'estensione e come utilizzarla.

La documentazione minima richiesta è costituita da questo insieme di tre file Markdown:

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

Inoltre, dovresti prendere in considerazione anche la produzione di:

• 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 scoprire alcune best practice e la struttura e la formulazione comuni, ti consigliamo di esaminare i file disponibili con le estensioni Firebase ufficiali.

Creazione di un file README

La directory delle estensioni può contenere facoltativamente un file README. Tieni presente che il comando firebase ext:dev:init non ne genera automaticamente uno per te.

L'interfaccia a riga di comando Firebase, tuttavia, supporta il seguente comando di convenienza per generare automaticamente un file README contenente i 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 Firebase ufficiali vengono generati utilizzando questo comando.

Aggiungere informazioni sull'installazione

Dopo aver scritto o generato un file README, aggiungivi le informazioni sull'installazione. Puoi utilizzare 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)

---

Scrivere un file PREINSTALL

Il file PREINSTALL è la panoramica della tua estensione, un tipo di pagina "marketing".

Quali contenuti sono presenti in questo file?

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

Dove vengono visualizzati questi contenuti per l'utente?

Console Firebase">

Pre-install content in the Firebase console

Console Firebase">

• Nella pagina dell'estensione su extensions.dev.
• Il repository del codice sorgente per l'estensione (all'interno della directory dell'estensione)
• Come parte del file README dell'estensione (se utilizzi il flag Firebase dell'interfaccia a riga di comando --markdown > README.md)

I file PREINSTALL non possono accedere ai valori dei parametri per l'estensione, quindi non devi aspettarti 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 una sola 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 altri file supplementari
• Menziona brevemente se fornisci altri strumenti o script per supportare l'estensione

Testo boilerplate PREINSTALL utile

Ti consigliamo di utilizzare il maggior numero possibile di testo standard riportato di seguito, a seconda dei casi per la tua estensione. Abbiamo fornito alcuni esempi, ma il punto più importante è assicurarsi che tutti i servizi fatturati da Google e non Google siano elencati.

Puoi utilizzare le seguenti risorse per trovare i dettagli corretti sui prezzi dei prodotti:

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

Scrivere un file POSTINSTALL

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

Quali contenuti sono presenti in questo file?

• Istruzioni dettagliate per tutte le attività obbligatorie post-installazione, come la configurazione 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, poi fai questo")
• Informazioni di base su come attivare l'estensione, in particolare per le estensioni attivate da richieste HTTP
• Brevi istruzioni su come monitorare l'estensione installata (inizia con il testo standard)

Dove vengono visualizzati questi contenuti per l'utente?

Console Firebase">

Contenuti post-installazione nella Firebaseconsole

Console Firebase">

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

  • Assicurati di esaminare la visualizzazione dei contenuti POSTINSTALL installando l'estensione in un progetto reale.

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

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

Quali sono alcune best practice?

• Mantieni i contenuti completi del file POSTINSTALL concisi, ma descrittivi.
• Dividi i contenuti in sezioni utilizzando i titoli per separare attività o concetti distinti.
• Valuta la possibilità di pubblicare istruzioni dettagliate per un flusso di lavoro o un'attività specifici sul tuo sito web (esempio) o in file markdown supplementari all'interno del repository delle estensioni (esempio).
• Parametri di riferimento e variabili correlate alle funzioni 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 fai riferimento a parametri e variabili correlate alle funzioni (vedi la tabella di seguito) nel file POSTINSTALL, la console compila questi riferimenti con i valori effettivi per l'istanza installata.

Suggerimento:per i valori che possono essere lunghi (come un percorso di database o un URL di funzione), fai riferimento al parametro o alla variabile alla fine di frasi e sezioni. Questa best practice rende le frasi più facili da leggere nella console Firebase quando i contenuti del file POSTINSTALL vengono visualizzati con i valori effettivi.

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

Puoi anche fare riferimento alle seguenti variabili correlate alla funzione solo nel file POSTINSTALL. Firebase supporta queste variabili in modo che tu possa fornire più facilmente indicazioni ai tuoi utenti dopo l'installazione. Sono disponibili solo per l'utilizzo nel file POSTINSTALL perché i valori di queste variabili non sono disponibili fino al termine dell'installazione.

In questa tabella, function-name è il valore del campo name nell'oggetto risorsa della funzione all'interno di extension.yaml.

Riferimento alla variabile correlata alla funzione	Descrizione	Valore della variabile (compilato automaticamente da Firebase dopo l'installazione dell'estensione)
${function:function-name.location}
	Posizione in cui viene eseguito il deployment della funzione	Valore di esempio: us-central1
${function:function-name.name}
	Nome della funzione di cui è stato eseguito il deployment 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} (valido solo per le funzioni HTTP)
	URL della funzione di cui è stato eseguito il deployment, a cui il codice client può inviare 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 il maggior numero possibile di testo standard riportato di seguito, a seconda dei casi per la 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 dell'estensione, devi fornire istruzioni agli utenti su come attivare l'estensione. Queste istruzioni possono essere dettagliate quanto ritieni necessario, ma tieni presente le best practice per la scrittura di un file POSTINSTALL. Per indicazioni su come fornire queste istruzioni, espandi la sezione riportata di seguito che si applica alla tua estensione.

Estensioni attivate dagli eventi in background

I tuoi utenti possono attivare un'estensione basata su eventi in background 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 console Firebase, soprattutto per i test iniziali dell'estensione. Ad esempio, supponiamo che la tua estensione crei un nuovo documento Cloud Firestore ogni volta che viene creato un nuovo utente Firebase Authentication. Puoi chiedere ai tuoi utenti di provare un'istanza installata della tua estensione aggiungendo manualmente un nuovo utente Authentication nella console. Potranno quindi osservare il nuovo documento creato nella sezione Cloud Firestore della console.

Aggiungere il codice lato client

Se applicabile, puoi anche fornire istruzioni agli utenti su 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 (fai riferimento all'estensione Contatore distribuito per un esempio).

Estensioni attivate da richieste HTTP

Affinché gli utenti possano attivare una funzione attivata da una richiesta HTTP (e quindi l'estensione), devi fornire loro il nome o l'URL della funzione di cui è stato eseguito il deployment.

Il nome della funzione di cui è stato eseguito il deployment finale non corrisponde a name che hai specificato nell'oggetto 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 punti elenco sono un testo standard suggerito da includere nel file POSTINSTALL dell'estensione. Dopo l'installazione, la console Firebase mostra i contenuti del file POSTINSTALL e inserisce questi riferimenti con i valori effettivi 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 onRequest

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

• Per le funzioni HTTP chiamabili (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 una richiesta HTTP, devono rendere accessibili pubblicamente le funzioni implementate per l'estensione. Le istruzioni dettagliate da fornire agli utenti sono riportate negli esempi di testo standard sopra.

Scrivere un file CHANGELOG

Quali contenuti sono presenti in questo file?

Ogni estensione deve avere un file CHANGELOG.md che documenta le modifiche incluse in ogni nuova versione dell'estensione che pubblichi. Inserisci ogni versione sotto un'intestazione di livello 2 (##); altrimenti, 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 visualizzati questi contenuti per l'utente?

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