Traitement des nouveaux achats et des essais gratuits

Lorsqu’un client achète un plan payant, un essai gratuit ou la version gratuite de votre application GitHub Marketplace, vous recevez le webhook d’événement marketplace_purchase avec l’action purchased, ce qui lance le processus d’achat.

Dans cet article

Remarque : cet article s’applique à la publication d’applications dans GitHub Marketplace uniquement. Pour plus d’informations sur la publication de GitHub Actions dans GitHub Marketplace, consultez « Publication d’actions dans GitHub Marketplace ».

Si vous proposez une GitHub App dans GitHub Marketplace, elle doit identifier les utilisateurs en suivant le flux d’autorisation OAuth. Vous n’avez pas besoin de configurer une OAuth app séparée pour prendre en charge ce flux. Pour plus d’informations, consultez « Authentification auprès d’une application GitHub pour le compte d’un utilisateur ».

Étape 1. Achat initial et événement de webhook

Avant d’acheter votre application GitHub Marketplace, le client sélectionne un plan de listing. Il choisit également s’il achète l’application à partir de son compte personnel ou d’un compte professionnel.

Le client effectue l’achat en cliquant sur Effectuer la commande et commencer l’installation.

GitHub envoie ensuite le webhook marketplace_purchase avec l’action purchased à votre application.

Lisez les objets effective_date et marketplace_purchase du webhook marketplace_purchase pour savoir quel plan le client a acheté, quand commence le cycle de facturation et quand commence le prochain cycle de facturation.

Si votre application propose un essai gratuit, lisez l’attribut marketplace_purchase[on_free_trial] du webhook. Si la valeur est true, votre application doit repérer la date de début de l’essai gratuit (effective_date) et la date de fin de l’essai gratuit (free_trial_ends_on). Utilisez la date free_trial_ends_on pour afficher les jours restants d’un essai gratuit dans l’interface utilisateur de votre application. Vous pouvez le faire dans une bannière ou dans votre interface utilisateur de facturation. Pour savoir comment traiter les annulations avant la fin d’un essai gratuit, consultez « Traitement des annulations de plan ». Consultez « Traitement des changements de plan » pour savoir comment passer d’un essai gratuit à un plan payant à l’expiration de l’essai gratuit.

Consultez « Événements de webhook pour l’API GitHub Marketplace » pour obtenir un exemple de charge utile d’événement marketplace_purchase.

Étape 2. Installation

Si votre application est une GitHub App, GitHub invite le client à sélectionner au moment de l’achat les dépôts auxquels l’application peut accéder. GitHub installe ensuite l’application sur le compte sélectionné par le client et accorde l’accès aux dépôts choisis.

À ce stade, si vous avez spécifié une URL de configuration dans vos paramètres d’GitHub App, GitHub redirige le client vers cette URL. Si vous ne spécifiez pas d’URL de configuration, vous ne pouvez pas traiter les achats de votre GitHub App.

Remarque : L’URL de configuration est indiquée comme facultative dans les paramètres d’GitHub App, mais c’est un champ obligatoire si vous voulez proposer votre application dans GitHub Marketplace. Pour plus d’informations, consultez « À propos de l’URL d’installation ».

Si votre application est une OAuth app, GitHub ne l’installe pas. À la place, GitHub redirige le client vers l’URL d’installation que vous avez spécifiée dans votre listing GitHub Marketplace.

Quand un client achète une OAuth app, GitHub redirige le client vers l’URL que vous choisissez (URL de configuration ou URL d’installation) et l’URL contient le plan tarifaire que le client a sélectionné comme paramètre de requête : marketplace_listing_plan_id.

Étape 3. Autorisation

Quand un client achète votre application, vous devez le diriger vers le flux d’autorisation OAuth :

Pour l’un ou l’autre des types d’application, la première étape est de rediriger le client vers https://github.com/login/oauth/authorize.

Dès que le client obtient l’autorisation, votre application reçoit un jeton d’accès OAuth pour le client. Vous l’utilisez dans l’étape suivante.

Remarque : Pour autoriser un client dans le cadre d’un essai gratuit, accordez-lui le même accès que pour le plan payant. Vous le migrez vers le plan payant une fois la période d’essai terminée.

Étape 4. Provisionnement de comptes client

Votre application doit provisionner un compte client pour tous les nouveaux achats. En utilisant le jeton d’accès que vous avez reçu pour le client à l’Étape 3. Autorisation, appelez le point de terminaison « GET /user/marketplace_purchases ». La réponse comprend les informations account du client et indique s’il s’agit d’un essai gratuit (on_free_trial). Utilisez ces informations pour effectuer la configuration et le provisionnement.

Remarque : Dans la version actuelle de GitHub Marketplace, un client peut acheter votre application à travers GitHub Marketplace même s’il a déjà un compte existant acheté sur le site web de votre application. Si vous constatez que vous avez déjà un compte configuré pour le client qui a acheté votre application, signalez l’achat en « double » à GitHub Support.

Si l’achat est effectué par une organisation et pour chaque utilisateur, vous pouvez inviter le client à choisir les membres de l’organisation qui doivent avoir accès à l’application achetée.

Vous pouvez personnaliser la façon dont les membres de l’organisation reçoivent l’accès à votre application. Voici quelques suggestions :

Prix forfaitaire : Si l’achat est effectué pour une organisation avec un prix forfaitaire, votre application peut obtenir tous les membres de l’organisation via l’API et inviter le propriétaire de l’organisation à choisir les membres avec des utilisateurs payants côté intégrateur.

Prix unitaire : La méthode de provisionnement de siège unitaire permet aux utilisateurs d’occuper un siège quand ils se connectent à l’application. Une fois le seuil de nombre de sièges atteint, votre application peut avertir l’utilisateur qu’il doit effectuer une mise à niveau dans GitHub Marketplace.