Note
Dieser Artikel gilt nur für das Veröffentlichen von Apps im GitHub Marketplace. Weitere Informationen zum Veröffentlichen von GitHub Actions im GitHub Marketplace findest du unter Aktionen auf dem GitHub-Marktplatz veröffentlichen.
Warning
Wenn du eine GitHub App in GitHub Marketplace anbietest, muss deine App Benutzer anhand des OAuth-Autorisierungsflows identifizieren. Du musst keine separate OAuth app zur Unterstützung dieses Flows einrichten. Weitere Informationen findest du unter Authentifizieren mit einer GitHub-App im Namen von Benutzer*innen.
Schritt 1. Anfängliches Kauf- und Webhookereignis
Bevor ein Kunde deine GitHub Marketplace -App kauft, wählt er einen Angebotsplan aus. Er wählt außerdem aus, ob die App über das persönliche Konto oder ein Organisationskonto erworben werden soll.
Der Kunde schließt den Kauf ab, indem er auf Complete order and begin installation (Bestellung abschließen und Installation beginnen) klickt.
GitHub sendet dann den marketplace_purchase-Webhook mit der purchased-Aktion an deine App.
Lies das effective_date- und marketplace_purchase-Objekt aus dem marketplace_purchase-Webhook, um festzustellen, welchen Plan der Kunde gekauft hat, wann der Abrechnungszeitraum beginnt und wann der nächste Abrechnungszeitraum beginnt.
Wenn deine App eine kostenlose Testperiode bietet, lies das marketplace_purchase[on_free_trial]-Attribut aus dem Webhook. Lautet der Wert true, muss deine App das Startdatum der kostenlosen Testperiode (effective_date) und das Datum, an dem die kostenlose Testperiode endet (free_trial_ends_on), nachverfolgen. Verwende das free_trial_ends_on-Datum, um die verbleibenden Tage der kostenlosen Testperiode auf der Benutzeroberfläche deiner App anzuzeigen. Dies kann entweder in einem Banner oder auf der Benutzeroberfläche für die Abrechnung erfolgen. Weitere Informationen zum Bearbeiten von Kündigungen vor Ablauf einer kostenlosen Testversion findest du unter Behandeln von Plankündigungen. Weitere Informationen dazu zum Wechseln von einer kostenlosen Testversion nach deren Ablauf zu einem kostenpflichtigen Plan findest du unter Behandeln von Planänderungen.
Ein Beispiel für die Ereignisnutzdaten von marketplace_purchase findest du unter Webhook-Ereignisse für die GitHub Marketplace-API.
Schritt 2: Installation
Wenn es sich bei deiner App um eine GitHub App handelt, fordert GitHub den Kunden auf, beim Kauf auszuwählen, auf welche Repositorys die App zugreifen kann. GitHub installiert dann die App in dem vom Kunden ausgewählten Konto und gewährt Zugriff auf die ausgewählten Repositorys.
Wenn du eine Setup-URL in deinen GitHub App-Einstellungen angegeben hast, leitet GitHub den Kunden an diesem Punkt zu dieser URL um. Wenn du keine Setup-URL angibst, kannst du keine Käufe deiner GitHub App handhaben.
Note
Der Wert für Setup URL wird in den GitHub App-Einstellungen als optional beschrieben, ist jedoch ein Pflichtfeld, wenn du deine App in GitHub Marketplace anbieten möchtest. Weitere Informationen finden Sie unter Informationen zur Setup-URL.
Wenn es sich bei deiner App um eine OAuth app handelt, wird sie von GitHub nirgendwo installiert. Stattdessen leitet GitHub den Kunden an die Installations-URL um, die du in deinem GitHub Marketplace-Angebot angegeben hast.
Wenn ein Kunde eine OAuth app kauft, leitet GitHub den Kunden an die von Dir ausgewählte URL (Setup-URL oder Installations-URL) um, und die URL enthält den vom Kunden ausgewählten Preisplan als Abfrageparameter: marketplace_listing_plan_id.
Schritt 3: Authorization
Wenn ein Kunde deine App kauft, musst du ihn durch den OAuth-Autorisierungsflow leiten:
-
Falls es sich bei deiner App um eine GitHub App handelt, beginnst du den Autorisierungsflow, sobald GitHub den Kunden an die Setup-URL umleitet. Führe die Schritte unter Authentifizieren mit einer GitHub-App im Namen von Benutzer*innen aus.
-
Falls es sich bei deiner App um eine OAuth app handelt, beginnst du den Autorisierungsflow, sobald GitHub den Kunden an die Installations-URL umleitet. Führe die Schritte unter Autorisieren von OAuth-Apps aus.
Bei beiden App-Typen besteht der erste Schritt darin, den Kunden an https://github.com/login/oauth/authorize umzuleiten.
Nachdem der Kunde die Autorisierung abgeschlossen hat, erhält deine App ein OAuth-Zugriffstoken für den Kunden. Du brauchst dieses Token im nächsten Schritt.
Note
Wenn du einen Kunden für eine kostenlose Testversion autorisierst, gewähre ihm denselben Zugriff, den er auch im kostenpflichtigen Plan haben würde. Nach Ablauf des Testzeitraums wird die Version in den kostenpflichtigen Plan umgewandelt.
Schritt 4. Bereitstellen von Kundenkonten
Deine App muss ein Kundenkonto für alle neuen Käufe bereitstellen. Mit dem Zugriffstokens, das du für den Kunden in Schritt 3: Autorisierung erhalten hast, rufe den Endpunkt von GET /user/marketplace_purchases auf. Die Antwort enthält die account-Informationen des Kunden und gibt an, ob er sich in einer kostenlosen Testperiode befindet (on_free_trial). Verwende diese Informationen, um die Einrichtung und Bereitstellung abzuschließen.
Note
In der aktuellen Version von GitHub Marketplace kann ein Kunde deine App über GitHub Marketplace erwerben, wenn er bereits über ein Konto verfügt, das von deiner App-Website erworben wurde. Wenn du feststellst, dass bereits ein Konto für den Kunden eingerichtet ist, der deine App erworben hat, melde die „doppelten“ Käufe an den GitHub-Support.
Wenn der Kauf für eine Organisation und pro Benutzer erfolgt, kannst du den Kunden auffordern auszuwählen, welche Organisationsmitglieder Zugriff auf die erworbene App haben.
Du kannst anpassen, auf welche Weise Organisationsmitglieder Zugriff auf deine App erhalten. Hier sind einige Vorschläge angegeben:
Pauschalpreise: Wenn der Kauf für eine Organisation mit Pauschalpreisen erfolgt, kann deine App alle Mitglieder der Organisation über die API abrufen und den Organisationsbesitzer auffordern auszuwählen, welche Mitglieder über bezahlte Benutzer auf Integratorseite verfügen.
Preise pro Einheit: Eine Methode zur Bereitstellung von Arbeitsplätzen pro Einheit besteht darin, den Benutzern die Möglichkeit zu geben, beim Anmelden bei der App einen Arbeitsplatz zu belegen. Sobald der Kunde den Schwellenwert für die Anzahl von Arbeitsplätzen erreicht, kann deine App den Benutzer darüber benachrichtigen, dass ein Upgrade über GitHub Marketplace erfolgen muss.