Pubblicare l'estensione

Questa pagina spiega come pubblicare un'estensione in Extensions Hub.

Prima di iniziare

Per pubblicare un'estensione, devi prima registrarti come editore di estensioni.

Fonti verificabili

Tutte le estensioni pubblicate nell'hub delle estensioni devono avere un'origine verificabile pubblicamente. Anziché caricare il codice sorgente dell'estensione direttamente nell'hub delle estensioni, specifica la posizione dell'origine e l'hub delle estensioni lo scaricherà e lo creerà da lì.

Al momento, ciò significa rendere disponibile il codice sorgente dell'estensione in un repository GitHub pubblico.

Il caricamento da una fonte verificabile presenta diversi vantaggi:

  • Gli utenti possono ispezionare il codice sorgente della revisione specifica dell'estensione che verrà installata.
  • Puoi assicurarti di caricare solo ciò che intendi caricare e non, ad esempio, lavori in corso o file sparsi rimasti dallo sviluppo.

Ciclo di sviluppo consigliato

Gli strumenti di sviluppo delle estensioni Firebase supportano il caricamento delle versioni pre-release delle estensioni, il che ti consente di testare facilmente le estensioni e la procedura di installazione delle estensioni nello stesso ambiente in cui verranno rilasciate.

Questa funzionalità consente un ciclo di sviluppo come il seguente:

  1. Sviluppa ed esegui rapidamente l'iterazione della tua estensione utilizzando Firebase Emulator Suite.

  2. Testa l'estensione in un progetto reale installandola da un'origine locale:

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

  3. Carica una versione pre-release nell'hub delle estensioni (vedi di seguito). Distribuisci il link di installazione per test più ampi e itera caricando altre versioni pre-release, se necessario.

  4. Carica la versione finale e stabile nell'hub delle estensioni (vedi sotto) e inviala per la revisione. Se l'estensione supera la revisione, verrà pubblicata nell'hub delle estensioni.

  5. Incrementa il numero di versione in extension.yaml e ripeti questo ciclo per la versione successiva dell'estensione.

Caricare una nuova estensione

Per caricare un'estensione per la prima volta:

  1. (Facoltativo) Esegui il commit del codice in un repository GitHub pubblico.

  2. Esegui il comando ext:dev:upload dell'interfaccia a riga di comando di Firebase:

    GitHub

    firebase ext:dev:upload your_publisher_id/your_extension_id

    Codice sorgente locale

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

    Nell'invocazione del comando, specifica quanto segue:

    • L'ID publisher che hai registrato.

    • Una stringa ID che identificherà l'estensione. Assegna un nome alle estensioni nel seguente formato: firebase-product-description-of-tasks-performed. Ad esempio: firestore-bigquery-export

    Il comando ti chiederà informazioni aggiuntive:

    • Se esegui il caricamento da GitHub:

      • L'URL del repository dell'estensione in GitHub. Tieni presente che un repository può contenere più estensioni, purché ognuna abbia una radice univoca.

        Quando carichi una nuova estensione per la prima volta, il repository verrà registrato come origine canonica per l'estensione.

      • La directory nel repository che contiene l'estensione.

      • Il riferimento Git del commit da cui vuoi creare l'origine della versione dell'estensione. Può essere un hash di commit, un tag o un nome di branch.

    • La fase di rilascio della versione che stai caricando.

      Le fasi alpha, beta e rc (release candidate) sono per il caricamento delle versioni pre-release da installare per i tester. Utilizza una di queste fasi per il caricamento iniziale di una nuova estensione.

      La fase stable viene utilizzata per pubblicare le release pubbliche nell'hub delle estensioni. Il caricamento di una release stable avvierà automaticamente una revisione e, se la supera, pubblicherà l'estensione.

    Tieni presente che non devi specificare un numero di versione. Questo valore proviene dal file extension.yaml. Quando carichi una versione pre-release dell'estensione, il numero di fase e di caricamento viene aggiunto alla versione. Ad esempio, se extension.yaml specifica la versione 1.0.1 e carichi una release candidata, il risultato sarà la versione 1.0.1-rc.0; il caricamento di un'altra release candidata della stessa versione incrementerà automaticamente il conteggio, con il risultato 1.0.1-rc.1 e così via.

Ora che hai caricato una versione pre-release dell'estensione, puoi condividerla con altri utenti per il test. Gli utenti possono installare la tua estensione in due modi:

  • Con la console: gli utenti possono installare l'estensione facendo clic su un link con il seguente formato:

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

    Puoi condividere il link diretto con i tester.

  • Con la CLI: gli utenti possono installare l'estensione passando la stringa dell'ID dell'estensione al comando ext:install:

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

Caricare una versione aggiornata

Dopo aver caricato la prima versione di un'estensione, puoi caricare gli aggiornamenti per risolvere problemi, aggiungere funzionalità o avanzare la fase di rilascio. Quando carichi una nuova versione, agli utenti che hanno installato una versione precedente della tua estensione verrà chiesto di eseguire l'upgrade nella console Firebase.

Per caricare un aggiornamento:

  1. (Facoltativo) Esegui il commit del codice in un repository Git pubblico.

  2. Esegui il comando ext:dev:upload dell'interfaccia a riga di comando di Firebase:

    GitHub

    firebase ext:dev:upload your_publisher_id/your_extension_id

    Questa volta non ti verrà chiesto di specificare il repository GitHub o la directory principale dell'estensione, poiché sono già stati configurati per la tua estensione. Se nel frattempo hai eseguito il refactoring della struttura del repository o hai eseguito la migrazione a un nuovo repository, puoi modificarli con gli argomenti del comando --root e --repo.

    Codice sorgente locale

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

Inviare un'estensione per la pubblicazione

Quando l'estensione è pronta per la pubblicazione:

  1. Esegui il commit del codice in un repository Git pubblico. (Obbligatorio per le release pubbliche.)

  2. Esegui il comando ext:dev:upload dell'interfaccia a riga di comando di Firebase, specificando stable come fase di rilascio:

    firebase ext:dev:upload your_publisher_id/your_extension_id

  3. Se hai già pubblicato una versione della tua estensione, il caricamento di una nuova release stabile invierà automaticamente l'estensione per la revisione.

    Se hai caricato la prima release stabile dell'estensione, trovala nella dashboard del publisher e fai clic su Pubblica nell'hub delle estensioni.

Una volta inviata, la revisione può richiedere alcuni giorni. Se accettata, l'estensione verrà pubblicata nell'hub delle estensioni. In caso di rifiuto, riceverai un messaggio che spiega il motivo. Potrai quindi risolvere i problemi segnalati e inviare nuovamente la richiesta per la revisione.

Per accelerare la revisione e aumentare le possibilità di superarla al primo tentativo, prima dell'invio, controlla quanto segue:

  • Hai testato a fondo l'estensione e la procedura di installazione.
  • La documentazione è completa e corretta e viene visualizzata correttamente nella console Firebase.
  • Il nome e il brand dell'editore ti identificano in modo chiaro e preciso come editore.
  • Il nome, la descrizione e l'icona dell'estensione rappresentano in modo chiaro e accurato lo scopo dell'estensione.
  • Hai applicato tag utili e precisi.
  • Hai dichiarato in extension.yaml tutte le API Google e non Google che utilizzi e tutti i tipi di eventi emessi dalla tua estensione.
  • Stai richiedendo l'accesso solo ai ruoli necessari per il funzionamento dell'estensione e hai spiegato chiaramente agli utenti il motivo per cui hai bisogno di questo accesso.
  • I file di origine sono chiaramente concessi in licenza ai sensi dei termini di Apache-2.0.

Gestire le estensioni caricate e pubblicate

Elencare le estensioni caricate

Per elencare le estensioni che hai caricato con il tuo ID publisher, esegui una delle seguenti operazioni:

Dashboard del publisher

Visualizzali nella dashboard del publisher.

Interfaccia a riga di comando di Firebase

Esegui il comando ext:dev:list:

firebase ext:dev:list your_publisher_id

Visualizzare l'utilizzo delle estensioni caricate

Per visualizzare l'utilizzo delle estensioni che hai caricato con il tuo ID publisher, procedi in uno dei seguenti modi:

Dashboard del publisher

La dashboard del publisher contiene metriche di utilizzo cumulative per tutte le tue estensioni e metriche individuali per ciascuna estensione.

Interfaccia a riga di comando di Firebase

Esegui il comando ext:dev:usage:

firebase ext:dev:usage your_publisher_id

Deprecare una versione di un'estensione

A un certo punto, potresti voler ritirare una vecchia versione della tua estensione. Ad esempio, se rilasci una nuova versione che corregge un bug critico o aggiorna una dipendenza con un importante aggiornamento della sicurezza, è importante impedire ai nuovi utenti di installare una versione precedente e incoraggiare gli utenti esistenti a eseguire l'upgrade.

Per ritirare una versione di un'estensione, esegui una delle seguenti operazioni:

Dashboard del publisher

  1. Nella dashboard del publisher, fai clic sull'estensione per aprire la visualizzazione dei dettagli.
  2. Seleziona la versione che vuoi ritirare.
  3. Fai clic su Depreca versione.

Interfaccia a riga di comando di Firebase

Esegui il comando ext:dev:deprecate:

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

Puoi specificare una singola versione o un intervallo di versioni. Esempi:

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

Le versioni deprecate di un'estensione non sono elencate nell'hub delle estensioni e non possono essere installate. Gli utenti i cui progetti hanno installato una versione ritirata visualizzeranno un messaggio che li invita a eseguire l'upgrade; nel frattempo possono comunque utilizzare e riconfigurare l'estensione.

Se ogni versione di un'estensione è obsoleta, l'estensione viene considerata obsoleta e verrà rimossa dall'hub delle estensioni. Il caricamento di una nuova versione di un'estensione deprecata avvierà automaticamente una revisione e, una volta accettata, la pubblicherà di nuovo nell'hub di Extensions.

Per annullare il ritiro, utilizza la dashboard del publisher o esegui il comando ext:dev:undeprecate dell'interfaccia a riga di comando di Firebase:

firebase ext:dev:undeprecate your_publisher_id/your_extension_id versions

Appendice: Risoluzione degli errori di build

Quando carichi l'estensione, il backend compila prima il codice sorgente utilizzando la seguente procedura:

  1. Clona il repository GitHub ed estrae il riferimento di origine specificato.

  2. Installa le dipendenze NPM eseguendo npm clean-install in ogni directory di origine della funzione specificata in extension.yaml (vedi sourceDirectory in Risorse di Cloud Functions).

    Tieni presente quanto segue:

    • Ogni file package.json deve avere un file package-lock.json corrispondente. Per ulteriori informazioni, consulta npm-ci.

    • Gli script post-installazione non verranno eseguiti durante l'installazione delle dipendenze. Se la build del codice sorgente si basa su script post-installazione, esegui il refactoring prima del caricamento.

  3. Compila il codice eseguendo npm run build in ogni directory di origine della funzione specificata in extension.yaml.

Nel pacchetto di estensione finale che verrà condiviso verrà salvata solo la directory principale dell'estensione.

Se si verificano errori di compilazione durante il caricamento dell'estensione, replica i passaggi di compilazione descritti sopra in locale in una directory nuova finché non si verificano errori, quindi prova a caricare di nuovo.