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 Extensions Hub, vous devez spécifier l'emplacement source. Extension Hub le téléchargera et le créera à partir de cet emplacement.

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 sera installée.
  • Vous pouvez vous assurer de n'importer que ce que vous avez l'intention d'importer, et non, par exemple, des travaux en cours ou des fichiers distincts 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 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 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 commit, 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 est utilisée pour les versions publiques à publier sur le Hub des extensions. L'importation d'une version stable lance automatiquement un examen et, s'il 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 d'extension préliminaire, 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 finale, vous obtenez la version 1.0.1-rc.0. L'importation d'une autre version candidate de la même version incrémente automatiquement le nombre, ce qui génère 1.0.1-rc.1, etc.

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:

  • 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 d'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 les problèmes, ajouter des fonctionnalités ou passer à 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 et que vous importez une nouvelle version stable, l'extension est automatiquement envoyée 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. 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 d'obtenir la première tentative, vérifiez les points suivants avant d'envoyer votre demande:

  • 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 en tant qu'éditeur.
  • Le nom, la description et l'icône de votre extension représentent clairement et précisément l'objectif de votre extension.
  • 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 que vous avez 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 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 comportent une version obsolète installée verront un message les encourageant à passer à la version la plus récente. 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. L'importation d'une nouvelle version d'une extension obsolète lance automatiquement un examen. Une fois qu'elle aura été acceptée, elle sera de nouveau publiée sur le Hub des extensions.

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 crée d'abord votre code source en procédant comme suit:

  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.