Pubblicare l'estensione

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

Prima di iniziare

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

Fonti verificabili

Tutte le estensioni pubblicate su Extensions Hub devono avere una fonte pubblicamente verificabile. Invece di caricare il codice sorgente dell'estensione direttamente su Extensions Hub, specifichi invece la posizione di origine e Extension Hub lo scaricherà e lo creerà da lì.

Attualmente, ciò significa rendere disponibile il codice sorgente dell'estensione su un repository GitHub pubblico.

Il caricamento da una fonte verificabile presenta diversi vantaggi:

  • Gli utenti possono controllare 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 vaganti rimanenti dallo sviluppo.

Ciclo di sviluppo consigliato

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

Questa capacità rende possibile un ciclo di sviluppo come il seguente:

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

  2. Metti alla prova la tua estensione in un progetto reale installandola dalla fonte locale:

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

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

  4. Carica la versione finale, stabile, sull'Hub Estensioni (vedi sotto) e inviala per la revisione. Se l'estensione supera la revisione, verrà pubblicata su Extension Hub.

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

Carica una nuova estensione

Per caricare un'estensione per la prima volta:

  1. Facoltativo : salva il tuo codice in un repository GitHub pubblico.

  2. Esegui il comando ext:dev:upload della CLI di Firebase:

    GitHub

    firebase ext:dev:upload your_publisher_id/your_extension_id

    Fonte locale

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

    Nell'invocazione del comando, specifichi quanto segue:

    • L'ID editore che hai registrato .

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

    Il comando richiederà ulteriori informazioni:

    • Se stai caricando da GitHub:

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

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

      • La directory nel repository che contiene la tua estensione.

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

    • La fase di rilascio della versione che stai caricando.

      Le fasi alpha , beta e rc (release candidate) servono per caricare le versioni pre-release che i tester potranno installare. Utilizza una di queste fasi per il caricamento iniziale di una nuova estensione.

      La fase stable viene utilizzata per le versioni pubbliche da pubblicare su Extensions Hub. Il caricamento di una versione stable avvierà automaticamente una revisione e, se superata, pubblicherà l'estensione.

    Nota che non specifichi un numero di versione: questo valore proviene dal file extension.yaml . Quando carichi una versione di estensione pre-release, alla versione vengono aggiunti la fase e il numero di caricamento. Ad esempio, se extension.yaml specifica la versione 1.0.1 e carichi una release candidate, il risultato sarà la versione 1.0.1-rc.0 ; caricare un'altra release candidate della stessa versione incrementerebbe automaticamente il conteggio, risultando in 1.0.1-rc.1 e così via.

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

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

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

    Puoi condividere il collegamento diretto con i tuoi 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

Carica una versione aggiornata

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

Per caricare un aggiornamento:

  1. Facoltativo : salva il tuo codice in un repository Git pubblico.

  2. Esegui il comando ext:dev:upload della CLI 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 root dell'estensione poiché sono già stati configurati per la tua estensione. Se da allora hai effettuato il refactoring della struttura del repository o la migrazione a un nuovo repository, puoi modificarli con gli argomenti del comando --root e --repo .

    Fonte locale

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

Inviare un'estensione per la pubblicazione

Quando sei pronto per rilasciare pubblicamente la tua estensione:

  1. Invia il tuo codice a un repository Git pubblico. (Obbligatorio per le versioni pubbliche.)

  2. Esegui il comando ext:dev:upload della CLI di Firebase, specificando stable come fase di rilascio:

    firebase ext:dev:upload your_publisher_id/your_extension_id

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

    Se hai caricato la prima versione stabile dell'estensione, trova l'estensione nella dashboard dell'editore e fai clic su Pubblica nell'hub delle estensioni .

Una volta inviato, la revisione può richiedere alcuni giorni. Se accettata, l'estensione verrà pubblicata nell'hub estensioni. In caso di rifiuto riceverai un messaggio che ne spiega il motivo; è quindi possibile risolvere i problemi segnalati e inviarli nuovamente per la revisione.

Per velocizzare la revisione e aumentare le possibilità di superarla al primo tentativo, prima di inviare, ricontrolla quanto segue:

  • Hai testato a fondo la tua estensione e il processo di installazione.
  • La documentazione è completa e corretta e viene visualizzata bene nella console Firebase.
  • Il nome e il brand dell'editore ti identificano in modo chiaro e accurato 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 perché hai bisogno di tale accesso.
  • I tuoi file sorgente sono chiaramente concessi in licenza secondo i termini di Apache-2.0 .

Gestisci le estensioni caricate e pubblicate

Elenca le estensioni caricate

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

Cruscotto dell'editore

Visualizzali sulla dashboard dell'editore .

CLI Firebase

Esegui il comando ext:dev:list :

firebase ext:dev:list your_publisher_id

Visualizza l'utilizzo delle estensioni caricate

Per visualizzare l'utilizzo delle estensioni che hai caricato con il tuo ID editore, esegui una delle seguenti operazioni:

Cruscotto dell'editore

La dashboard dell'editore presenta metriche di utilizzo cumulative per tutte le tue estensioni e metriche individuali per ciascuna estensione.

CLI Firebase

Esegui il comando ext:dev:usage :

firebase ext:dev:usage your_publisher_id

Deprecare una versione di un'estensione

Ad un certo punto, potresti voler deprecare 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 di sicurezza, è importante impedire ai nuovi utenti di installare una versione precedente e incoraggiare gli utenti esistenti a eseguire l'aggiornamento.

Per deprecare una versione di un'estensione, effettuare una delle seguenti operazioni:

Cruscotto dell'editore

  1. Nella dashboard dell'editore , fai clic sull'estensione per aprire la relativa visualizzazione dei dettagli.
  2. Seleziona la versione che desideri deprecare.
  3. Fai clic su Versione obsoleta .

CLI Firebase

Esegui il comando ext:dev:deprecate :

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

È possibile 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 estensioni e non possono essere installate. Gli utenti i cui progetti hanno una versione deprecata installata vedranno un messaggio che li incoraggia ad aggiornare; nel frattempo potranno comunque utilizzare e riconfigurare l'estensione.

Se ogni versione di un'estensione è deprecata, l'estensione sarà considerata deprecata e verrà rimossa dall'hub delle estensioni. Il caricamento di una nuova versione di un'estensione obsoleta avvierà automaticamente una revisione e, dopo l'accettazione, la pubblicherà nuovamente sull'hub delle estensioni.

Per annullare una deprecazione, utilizza il dashboard dell'editore o esegui il comando ext:dev:undeprecate della CLI di Firebase:

firebase ext:dev:undeprecate your_publisher_id/your_extension_id versions

Appendice: risoluzione dei problemi relativi agli errori di creazione

Quando carichi la tua estensione, il backend crea prima il tuo codice sorgente utilizzando il seguente processo:

  1. Clona il tuo repository GitHub ed effettua il check-out del riferimento sorgente specificato.

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

    Tieni presente quanto segue:

    • Ogni file package.json deve avere un file package-lock.json corrispondente. Per ulteriori informazioni, vedere 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. Crea il tuo codice eseguendo npm run build in ogni directory di origine della funzione specificata in extension.yaml .

Solo la directory root della tua estensione verrà salvata nel pacchetto di estensione finale che verrà condiviso.

Se ricevi errori di creazione durante il caricamento dell'estensione, replica i passaggi di creazione precedenti localmente in una nuova directory finché non si verificano più errori, quindi prova a eseguire nuovamente il caricamento.