Publier votre extension

Cette page explique comment publier une extension sur Extensions Hub.

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'une source vérifiable publiquement. Au lieu d'importer le code source de votre extension directement dans le Hub des extensions, vous spécifiez l'emplacement de la source. Le Hub des extensions le télécharge et le compile à partir de là.

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

Importer des données depuis 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 sera installée.
  • Vous pouvez ainsi vous assurer de n'importer que ce que vous souhaitez, et non, par exemple, des travaux en cours ou des fichiers inutiles laissés par le développement.

Cycle de développement recommandé

Les outils de développement Firebase Extensions permettent d'importer des versions préliminaires de vos extensions. Vous pouvez ainsi tester facilement vos extensions et le processus d'installation des extensions dans l'environnement dans lequel elles seront finalement publiées.

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

  1. Développez votre extension et itérez rapidement dessus à 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 dans le Hub des extensions (voir ci-dessous). Distribuez le lien d'installation pour effectuer des tests plus larges et itérez en important d'autres versions préliminaires si nécessaire.

  4. Importez la version finale et stable dans le Hub d'extensions (voir ci-dessous), puis 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 l'invocation de votre commande, vous spécifiez les éléments suivants :

    • La référence éditeur que vous avez enregistrée.

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

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

    • Si vous importez le fichier depuis GitHub :

      • URL du dépôt de l'extension sur GitHub. Notez qu'un dépôt peut contenir plusieurs extensions à condition que chacune d'elles ait une racine unique.

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

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

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

    • Phase de version de la version que vous importez.

      Les étapes alpha, beta et rc (version candidate) permettent d'importer des versions préliminaires que les testeurs peuvent installer. Utilisez l'une de ces étapes pour la mise en ligne initiale d'une nouvelle extension.

      L'étape stable est utilisée pour publier les versions publiques sur le Hub d'extensions. La mise en ligne d'une version stable lance automatiquement un examen. Si la version est approuvée, l'extension est publiée.

    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 une version candidate, la version 1.0.1-rc.0 sera générée. Si vous importez une autre version candidate de la même version, le nombre sera automatiquement incrémenté, ce qui donnera 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 qu'ils la testent. Les utilisateurs peuvent installer votre extension de deux manières :

  • Avec 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 la première version d'une extension importée, vous pouvez importer des mises à jour pour corriger des problèmes, ajouter des fonctionnalités ou faire progresser la phase de publication. Lorsque vous importez une nouvelle version, les utilisateurs qui ont installé une ancienne version de votre extension sont invités à effectuer une mise à 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 ne serez 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 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 :

  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 soumet automatiquement l'extension à un examen.

    Si vous avez importé la première version stable de l'extension, recherchez-la dans votre tableau de bord d'éditeur, puis cliquez sur Publier sur le Hub des extensions.

Une fois que vous les avez envoyés, l'examen peut prendre quelques jours. Si elle est acceptée, l'extension sera publiée sur le Hub des extensions. Si votre demande est refusée, vous recevrez un message expliquant pourquoi. Vous pourrez alors résoudre les problèmes signalés et renvoyer votre demande pour examen.

Pour accélérer l'examen et augmenter vos chances de réussite dès la première tentative, vérifiez les points suivants avant d'envoyer votre demande :

  • Vous avez testé minutieusement votre extension et la procédure d'installation.
  • Votre documentation est complète et correcte, et s'affiche correctement dans la console Firebase.
  • Le nom et le branding de votre éditeur vous identifient clairement et précisément en tant qu'éditeur.
  • Le nom, la description et l'icône de votre extension représentent clairement et fidèlement 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 termes de Apache-2.0.

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

Lister les extensions importées

Pour lister les extensions que vous avez importées sous votre ID d'éditeur, procédez de l'une des manières suivantes :

Tableau de bord des éditeurs

Vous pouvez les consulter dans le tableau de bord des éditeurs.

CLI Firebase

Exécutez la commande ext:dev:list :

firebase ext:dev:list your_publisher_id

Afficher l'utilisation de vos extensions importées

Pour afficher l'utilisation des extensions que vous avez importées sous votre ID d'éditeur, effectuez l'une des opérations suivantes :

Tableau de bord des éditeurs

Le tableau de bord des éditeurs contient des métriques d'utilisation cumulées pour toutes vos extensions 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 rendre obsolète une version d'une extension, effectuez l'une des opérations suivantes :

Tableau de bord des éditeurs

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

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 dans le Hub des extensions et ne peuvent pas être installées. Les utilisateurs dont les projets ont une version obsolète installée verront un message les encourageant à effectuer la mise à niveau. Ils pourront toujours utiliser et reconfigurer l'extension en attendant.

Si toutes les versions d'une extension sont obsolètes, l'extension est considérée comme obsolète et sera supprimée du Hub des extensions. Si vous importez une nouvelle version d'une extension obsolète, un examen sera automatiquement lancé. Si elle est acceptée, elle sera de nouveau publiée sur Extensions Hub.

Pour annuler une obsolescence, 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 en suivant le processus suivant :

  1. Clone votre dépôt GitHub et extrait la référence source spécifiée.

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

    Veuillez noter les points suivants :

    • Chaque fichier package.json doit avoir un fichier package-lock.json correspondant. Pour en savoir plus, consultez 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, refactorisez-le avant de l'importer.

  3. Compile votre code en exécutant npm run build dans chaque répertoire 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 vous rencontrez des erreurs de compilation lors de l'importation de votre extension, reproduisez les étapes de compilation ci-dessus en local dans un nouveau répertoire jusqu'à ce qu'il n'y ait plus d'erreurs, puis réessayez d'importer.