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 avoir une source publiquement vérifiable. Plutôt que d'importer le code source de votre extension directement dans 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 version spécifique de l'extension qui sera installée.
  • Vous pouvez vous assurer d'importer uniquement ce que vous avez l'intention d'importer, et non, par exemple, un travail en cours ou des fichiers égarés restants du développement.

Cycle de développement recommandé

Les outils de développement des extensions Firebase 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 le même environnement dans lequel elles seront éventuellement publiées.

Cette fonctionnalité permet un cycle de développement comme suit:

  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 le lien d'installation pour des tests plus larges, puis itérez en important d'autres versions préliminaires si nécessaire.

  4. Importez la version finale et stable dans 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 l'appel de commande, vous devez spécifier les éléments suivants:

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

    • Chaîne d'ID qui identifie 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 des données depuis GitHub:

      • URL du dépôt de l'extension sur GitHub. Notez qu'un dépôt peut contenir plusieurs extensions, à condition que chaque extension dispose d'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 candidate) permettent d'importer des versions préliminaires à installer par les testeurs. Utilisez l'une de ces étapes pour la mise en ligne initiale d'une nouvelle extension.

      L'étape stable permet de publier les versions publiques sur Extensions Hub. La mise en ligne d'une version stable déclenche automatiquement un examen. Si celui-ci est concluant, 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 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 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 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 qui ont installé une ancienne version de votre extension sont invités à 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 l'examen terminé, il 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 le motif. Vous pourrez ensuite corriger les problèmes signalés et renvoyer votre demande 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 marque 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 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 sous licence conformément aux conditions de Apache-2.0.

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

Lister vos extensions importées

Pour lister les extensions que vous avez importées sous votre référence éditeur, procédez comme suit:

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

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. Si vous importez une nouvelle version d'une extension obsolète, un examen sera automatiquement lancé. Si l'extension est acceptée, elle sera de 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. 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 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 être associé à un fichier package-lock.json. 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 votre compilation de code source repose sur des scripts post-installation, refactorisez-la avant de l'importer.

  3. Compilé 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 recevez des erreurs de compilation lors de l'importation de votre extension, répliquez les étapes de compilation ci-dessus localement dans un nouveau répertoire jusqu'à ce qu'il n'y ait plus d'erreurs, puis réessayez d'importer.