Publier votre extension

Cette page explique comment publier une extension sur Extensions Hub.

Avant que tu commences

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

Sources vérifiables

Toutes les extensions publiées sur Extensions Hub doivent avoir une source publiquement vérifiable. Plutôt que de télécharger le code source de votre extension directement sur Extensions Hub, vous spécifiez plutôt l'emplacement source et Extension Hub le téléchargera et le construira à partir de là.

Actuellement, cela signifie rendre le code source de votre extension disponible sur un référentiel GitHub public.

Le téléchargement à 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 télécharger uniquement ce que vous avez l'intention de télécharger et non, par exemple, des travaux en cours ou des fichiers parasites restant du développement.

Cycle de développement recommandé

Les outils de développement d'extensions Firebase prennent en charge le téléchargement de versions préliminaires de vos extensions, ce qui vous permet de tester facilement vos extensions et le processus d'installation des extensions dans le même environnement dans lequel elles seront finalement publiées.

Cette capacité rend possible un cycle de développement comme le suivant :

  1. Développez et itérez rapidement sur votre extension à l'aide de Firebase Emulator Suite .

  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. Téléchargez une version préliminaire sur Extensions Hub (voir ci-dessous). Distribuez le lien d'installation pour des tests plus larges et répétez en téléchargeant davantage de versions préliminaires si nécessaire.

  4. Téléchargez la version finale et stable sur Extensions Hub (voir ci-dessous) et soumettez-la pour examen. Si l’extension réussit l’examen, elle sera publiée sur Extension Hub.

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

Téléchargez une nouvelle extension

Pour télécharger une extension pour la première fois :

  1. Facultatif : validez votre code dans un référentiel GitHub public.

  2. Exécutez la commande ext:dev:upload 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, vous spécifiez les éléments suivants :

    • L'identifiant d'éditeur que vous avez enregistré .

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

    La commande vous demandera des informations supplémentaires :

    • Si vous téléchargez depuis GitHub :

      • L'URL du référentiel de l'extension dans GitHub. Notez qu'un référentiel peut contenir plusieurs extensions à condition que chaque extension ait une racine unique.

        Lorsque vous téléchargez une nouvelle extension pour la première fois, le référentiel sera enregistré comme source canonique de votre extension.

      • Le répertoire du référentiel qui contient votre extension.

      • La 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 validation, d'une balise ou d'un nom de branche.

    • L'étape de publication de la version que vous téléchargez.

      Les étapes alpha , beta et rc (release candidate) sont destinées au téléchargement de versions préliminaires que les testeurs doivent installer. Utilisez l'une de ces étapes pour le téléchargement initial d'une nouvelle extension.

      L'étape stable est utilisée pour les versions publiques à publier sur Extensions Hub. Le téléchargement d’une version stable lancera automatiquement une révision et, si elle réussit, publiera l’extension.

    Notez que vous ne spécifiez pas de numéro de version : cette valeur provient du fichier extension.yaml . Lorsque vous téléchargez une version d'extension préliminaire, l'étape et le numéro de téléchargement sont ajoutés à la version. Par exemple, si extension.yaml spécifie la version 1.0.1 et que vous téléchargez une version candidate, cela donnera la version 1.0.1-rc.0 ; le téléchargement d'une autre version candidate de la même version incrémenterait automatiquement le décompte, ce qui donnerait 1.0.1-rc.1 , et ainsi de suite.

Maintenant que vous avez téléchargé une version préliminaire de l'extension, vous pouvez la partager avec d'autres à des fins de test. 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 passant 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

Télécharger une version mise à jour

Après avoir téléchargé la première version d'une extension, vous pouvez télécharger des mises à jour pour résoudre des problèmes, ajouter des fonctionnalités ou avancer dans la phase de publication. Lorsque vous téléchargez une nouvelle version, les utilisateurs qui ont installé une ancienne version de votre extension seront invités dans la console Firebase à effectuer la mise à niveau.

Pour télécharger une mise à jour :

  1. Facultatif : validez votre code dans un référentiel Git public.

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

    GitHub

    firebase ext:dev:upload your_publisher_id/your_extension_id

    Cette fois, vous ne serez pas invité à spécifier le référentiel GitHub ou le répertoire racine de l'extension puisqu'ils ont déjà été configurés pour votre extension. Si vous avez depuis refactorisé la structure de votre référentiel ou migré vers un nouveau référentiel, vous pouvez les modifier avec les arguments de commande --root et --repo .

    Source locale

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

Soumettre une extension pour publication

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

  1. Validez votre code dans un référentiel 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, le téléchargement d'une nouvelle version stable soumettra automatiquement l'extension pour examen.

    Si vous avez téléchargé la première version stable de l'extension, recherchez l'extension sur le tableau de bord de votre éditeur , puis cliquez sur Publier sur Extensions Hub .

Une fois soumis, l’examen peut prendre quelques jours. Si elle est acceptée, l’extension sera publiée sur Extensions Hub. En cas de refus, vous recevrez un message expliquant la raison ; vous pouvez ensuite résoudre les problèmes signalés et soumettre à nouveau pour examen.

Pour accélérer l'examen et augmenter vos chances de réussite du premier coup, avant de soumettre, vérifiez les éléments suivants :

  • Vous avez minutieusement testé votre extension et le processus d'installation.
  • Votre documentation est complète et correcte, et s'affiche bien dans la console Firebase.
  • Votre nom d'éditeur et votre image de 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 l'objectif de votre extension.
  • Vous avez appliqué des balises utiles et précises.
  • 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 demandez l’accès uniquement aux rôles nécessaires au fonctionnement de l’extension et vous avez clairement expliqué aux utilisateurs pourquoi vous avez besoin d’un tel accès.
  • Vos fichiers sources sont clairement sous licence selon les termes d' Apache-2.0 .

Gérer les extensions téléchargées et publiées

Répertoriez vos extensions téléchargées

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

Tableau de bord de l'éditeur

Consultez-les sur 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 de vos extensions téléchargées

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

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

Déprécier une version d'une extension

À un moment donné, vous souhaiterez peut-être rendre obsolète une ancienne version de votre extension. Par exemple, si vous publiez une nouvelle version qui corrige un bogue 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 de l'éditeur

  1. Sur 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 rendre obsolète.
  3. Cliquez sur 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 répertoriées sur Extensions Hub et ne peuvent pas être installées. Les utilisateurs dont les projets ont une version obsolète installée verront un message les encourageant à mettre à niveau ; ils peuvent toujours utiliser et reconfigurer l'extension entre-temps.

Si chaque version d'une extension est obsolète, l'extension est considérée comme obsolète et elle sera supprimée de la liste d'Extensions Hub. Le téléchargement d’une nouvelle version d’une extension obsolète lancera automatiquement une révision et, une fois acceptée, la publiera à nouveau sur Extensions Hub.

Pour annuler une dépréciation, 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 : Dépannage des erreurs de build

Lorsque vous téléchargez votre extension, le backend crée d'abord votre code source en suivant le processus suivant :

  1. Clone votre référentiel 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 Cloud Function resources ).

    Notez ce qui suit :

    • Chaque fichier package.json doit avoir un fichier package-lock.json correspondant. Pour plus d’informations, consultez npm-ci .

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

  3. Construit 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 obtenez des erreurs de build lors du téléchargement de votre extension, répliquez les étapes de build ci-dessus localement dans un nouveau répertoire jusqu'à ce qu'il n'y ait plus d'erreurs, puis réessayez de télécharger.