Publier votre extension

Cette page explique comment publier une extension sur le Hub des extensions.

Avant de commencer

Pour publier une extension, vous devez d'abord vous enregistrer en tant qu'éditeur d'extensions.

Sources vérifiables

Toutes les extensions publiées sur le Hub des extensions doivent disposer d'un source. Au lieu d'importer le code source de votre extension directement sur le Hub des extensions, vous devez spécifier l'emplacement de la source. Le Hub des extensions le téléchargera et le compilera à partir de là.

Actuellement, cela signifie que vous devez rendre le code source de votre extension disponible dans un dépôt GitHub public.

L'importation à partir d'une source vérifiable présente plusieurs avantages:

  • Les utilisateurs peuvent inspecter le code source de la révision spécifique de l'extension qui va être installé.
  • Vous pouvez vous assurer de n'importer que ce que vous avez l'intention d'importer, par exemple, des travaux en cours ou des fichiers distincts restants du développement.

Cycle de développement recommandé

Les outils de développement d'extensions Firebase permettent d'importer des versions préliminaires de vos extensions, ce qui vous permet de les tester facilement d'installation des extensions dans le même environnement par la suite.

Cette fonctionnalité permet un cycle de développement semblable à celui-ci :

  1. Développez et itérez rapidement sur votre extension à l'aide de la suite d'émulateurs Firebase.

  2. Testez votre extension dans un projet réel en l'installant à partir d'une source locale:

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

  3. Importez une version préliminaire sur le Hub des extensions (voir ci-dessous). Distribuez les lien d'installation pour des tests à plus grande échelle, puis effectuez des itérations en important d'autres des versions préliminaires, le cas échéant.

  4. Importez la version stable finale sur Extensions Hub (voir ci-dessous) et envoyez-la. pour examen. Si l'extension est approuvée, elle sera publiée sur le Hub des extensions.

  5. Incrémentez le numéro de version dans extension.yaml et répétez ce cycle pour la prochaine version de votre extension.

Importer une nouvelle extension

Pour importer une extension pour la première fois :

  1. Facultatif: Validez votre code dans un dépôt GitHub public.

  2. Exécutez la commande ext:dev:upload de la CLI Firebase :

    GitHub

    firebase ext:dev:upload your_publisher_id/your_extension_id

    Source locale

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

    Dans votre appel de commande, spécifiez les éléments suivants:

    • Référence éditeur que vous avez enregistrée.

    • Une chaîne d'ID qui permettra d'identifier l'extension. Nommez vos extensions au format suivant : firebase-product-description-of-tasks-performed. Par exemple : firestore-bigquery-export

    La commande vous invite à saisir des informations supplémentaires:

    • Si vous importez des données depuis GitHub :

      • URL du dépôt de l'extension sur GitHub. Notez qu'un peut contenir plusieurs extensions tant que chaque extension dispose une racine unique.

        Lorsque vous importez une nouvelle extension pour la première fois, le dépôt est enregistré en tant que source canonique de votre extension.

      • Répertoire du dépôt contenant votre extension.

      • Référence Git du commit à partir duquel vous souhaitez compiler la source de la version de votre extension. Il peut s'agir d'un hachage de validation, d'un tag ou d'un nom de branche.

    • Phase de la version que vous importez.

      Les étapes alpha, beta et rc (version finale) concernent l'importation afin que les testeurs puissent les installer. Utilisez l'une de ces étapes pour la mise en ligne initiale d'une nouvelle extension.

      L'étape stable est utilisée pour les versions publiques à publier sur Hub des extensions. L'importation d'une version stable lance automatiquement une et, s'il est accepté, il publie l'extension.

    Notez que vous ne spécifiez pas de numéro de version. Cette valeur provient du fichier extension.yaml. Lorsque vous importez une version préliminaire d'une extension, l'étape et le numéro d'importation sont ajoutés à la version. Par exemple, si extension.yaml spécifie la version 1.0.1 et que vous importez un candidat à la version, la version 1.0.1-rc.0 est générée. Si vous importez un autre candidat à la version de la même version, le nombre est automatiquement incrémenté, ce qui génère 1.0.1-rc.1, et ainsi de suite.

Maintenant que vous avez importé une version préliminaire de l'extension, vous pouvez la partager avec d'autres utilisateurs pour les tests. Les utilisateurs peuvent installer votre extension différentes manières:

  • Depuis la console: les utilisateurs peuvent installer l'extension en cliquant sur un lien. au format suivant:

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

    Vous pouvez partager le lien direct avec vos testeurs.

  • Avec la CLI : les utilisateurs peuvent installer l'extension en transmettant la chaîne d'ID de l'extension à la commande ext:install :

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

Importer une version mise à jour

Une fois que vous avez importé la première version d'une extension, vous pouvez importer des mises à jour pour résoudre des problèmes, ajouter des fonctionnalités ou avancer dans l'étape de publication. Lorsque vous importez une nouvelle version, les utilisateurs disposant d'une ancienne version l'extension installée sera invitée à la mettre à niveau dans la console Firebase.

Pour importer une mise à jour :

  1. Facultatif : validez votre code dans un dépôt Git public.

  2. Exécutez la commande ext:dev:upload de la CLI Firebase:

    GitHub

    firebase ext:dev:upload your_publisher_id/your_extension_id

    Cette fois, vous n'êtes pas invité à spécifier le dépôt GitHub ni le répertoire racine de l'extension, car ils ont déjà été configurés pour votre extension. Si vous avez depuis refactorisé la structure de votre dépôt ou migré vers un nouveau dépôt, vous pouvez les modifier à l'aide des arguments de commande --root et --repo.

    Source locale

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

Envoyer une extension pour publication

Lorsque vous êtes prêt à publier votre extension publiquement :

  1. Validez votre code dans un dépôt Git public. (Obligatoire pour les versions publiques.)

  2. Exécutez la commande ext:dev:upload de la CLI Firebase en spécifiant stable comme étape de publication :

    firebase ext:dev:upload your_publisher_id/your_extension_id

  3. Si vous avez déjà publié une version de votre extension, l'importation d'une nouvelle version stable entraînera automatiquement l'envoi de l'extension pour examen.

    Si vous avez importé la première version stable de l'extension, recherchez-la dans votre tableau de bord pour les éditeurs, puis cliquez sur Publier sur Extensions Hub.

Une fois envoyé, l'examen peut prendre quelques jours. Si elle est acceptée, l'extension sera publiée sur le Hub des extensions. En cas de refus, un message s'affiche pour vous expliquer motif ; vous pouvez alors résoudre les problèmes signalés et les renvoyer pour examen.

Pour accélérer l'examen et augmenter vos chances de réussir dès le premier essai, vérifiez les points suivants avant de l'envoyer :

  • Vous avez testé minutieusement votre extension et le processus d'installation.
  • Votre documentation est complète et correcte, et s'affiche correctement dans la console Firebase.
  • Votre nom d'éditeur et votre branding vous identifient clairement et précisément à un éditeur.
  • Le nom, la description et l'icône de votre extension représentent clairement et précisément son objectif.
  • Vous avez appliqué des tags utiles et précis.
  • Vous avez déclaré dans extension.yaml toutes les API Google et non Google que vous utilisez, ainsi que tous les types d'événements émis par votre extension.
  • Vous ne demandez l'accès qu'aux rôles nécessaires au fonctionnement de l'extension et vous avez clairement expliqué aux utilisateurs pourquoi vous avez besoin de cet accès.
  • Vos fichiers sources sont clairement concédés sous licence selon les conditions d'utilisation de Apache-2.0.

Gérer les extensions importées et publiées

Lister les extensions que vous avez importées

Pour répertorier les extensions que vous avez importées avec votre référence éditeur, effectuez l'une des opérations suivantes:

Tableau de bord de l'éditeur

Consultez-les dans le tableau de bord de l'éditeur.

CLI Firebase

Exécutez la commande ext:dev:list :

firebase ext:dev:list your_publisher_id

Afficher l'utilisation des extensions importées

Pour afficher l'utilisation des extensions que vous avez importées sous votre ID d'éditeur, procédez comme suit :

Tableau de bord de l'éditeur

Le tableau de bord de l'éditeur présente des métriques d'utilisation cumulées pour l'ensemble de vos et des métriques individuelles pour chaque extension.

CLI Firebase

Exécutez la commande ext:dev:usage :

firebase ext:dev:usage your_publisher_id

Abandonner une version d'une extension

À un moment donné, vous souhaiterez peut-être abandonner une ancienne version de votre extension. Par exemple, si vous publiez une nouvelle version qui corrige un bug critique ou met à jour une dépendance avec une mise à jour de sécurité importante, il est important d'empêcher les nouveaux utilisateurs d'installer une ancienne version et d'encourager les utilisateurs existants à effectuer la mise à niveau.

Pour abandonner une version d'extension, effectuez l'une des opérations suivantes:

Tableau de bord de l'éditeur

  1. Dans le tableau de bord de l'éditeur, cliquez sur l'extension pour ouvrir sa vue détaillée.
  2. Sélectionnez la version que vous souhaitez abandonner.
  3. Cliquez sur Rendre la version obsolète.

CLI Firebase

Exécutez la commande ext:dev:deprecate :

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

Vous pouvez spécifier une seule version ou une plage de versions. Exemples :

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

Les versions obsolètes d'une extension ne sont pas listées sur le Hub des extensions et ne peuvent pas être installé. Les utilisateurs dont les projets ont une version obsolète verront un message les encourageant à effectuer la mise à niveau ; ils peuvent toujours utiliser et reconfigurer pour le moment.

Si toutes les versions d'une extension sont obsolètes, l'extension est considérée comme obsolète et sera retirée du Hub des extensions. L'importation d'une nouvelle version d'une extension obsolète déclenche automatiquement un examen. Si l'extension est acceptée, elle est à nouveau publiée sur Extensions Hub.

Pour annuler une mise à l'abandon, utilisez le tableau de bord de l'éditeur ou exécutez la commande ext:dev:undeprecate de la CLI Firebase :

firebase ext:dev:undeprecate your_publisher_id/your_extension_id versions

Annexe : Résoudre les erreurs de compilation

Lorsque vous importez votre extension, le backend compile d'abord votre code source à l'aide du processus suivant :

  1. Il clone votre dépôt GitHub et vérifie la référence source spécifiée.

  2. Installe les dépendances NPM en exécutant npm clean-install dans chaque répertoire de source de fonction spécifié dans extension.yaml (voir sourceDirectory dans les ressources de fonction Cloud).

    Veuillez noter les points suivants :

    • Chaque fichier package.json doit avoir un élément package-lock.json correspondant . Pour en savoir plus, consultez la page sur npm-ci.

    • Les scripts post-installation ne seront pas exécutés lors de l'installation des dépendances. Si la compilation de votre code source repose sur des scripts post-installation, le refactoriser avant de l'importer.

  3. Compile votre code en exécutant npm run build dans chaque source de fonction spécifié dans extension.yaml.

Seul le répertoire racine de votre extension sera enregistré dans le package d'extension final qui sera partagé.

Si des erreurs de compilation se produisent lors de l'importation de votre extension, dupliquez-la les étapes ci-dessus en local dans un nouveau répertoire jusqu'à ce qu'il n'y ait plus d'erreurs, puis essayez à nouveau.