Observação: este artigo se aplica somente à publicação de aplicativos do GitHub Marketplace. Para obter mais informações mais sobre como publicar o GitHub Actions no GitHub Marketplace, confira "Publicar ações no GitHub Marketplace".
Se você oferece um GitHub App em GitHub Marketplace, seu aplicativo deverá identificar usuários seguindo o fluxo de autorização do OAuth. Você não precisa configurar OAuth app separadamente para dar suporte a este fluxo. Confira "Autenticação com um aplicativo GitHub em nome de um usuário" para saber mais.
Etapa 1. Compra inicial e evento de webhook
Antes de um cliente comprar seu aplicativo no GitHub Marketplace, ele seleciona um plano de listagem. O cliente também escolhe se deseja comprar o aplicativo a partir da sua conta pessoal ou a partir da conta de uma organização.
O cliente efetua a compra clicando em Concluir pedido e iniciar a instalação.
Em seguida, o GitHub envia o webhook marketplace_purchase com a ação purchased ao seu aplicativo.
Leia o objeto effective_date e marketplace_purchase por meio do webhook marketplace_purchase para determinar o plano que o cliente comprou, o período em que o ciclo de cobrança é iniciado e o início do próximo ciclo de cobrança.
Se o aplicativo oferecer uma avaliação gratuita, leia o atributo marketplace_purchase[on_free_trial] por meio do webhook. Se o valor for true, seu aplicativo precisará acompanhar a data de início da avaliação gratuita (effective_date) e a data em que a avaliação gratuita termina (free_trial_ends_on). Use a data free_trial_ends_on para ver os dias restantes em uma avaliação gratuita na interface do usuário do aplicativo. Faça isso em uma barra de notificação ou na interface do usuário de cobrança. Para saber como lidar com cancelamentos antes do término de uma avaliação gratuita, confira "Gerenciar cancelamento de plano". Confira "Gerenciar mudanças de plano" para descobrir como fazer a transição de uma avaliação gratuita para um plano pago quando uma avaliação gratuita vencer.
Confira "Eventos do Webhook para a API do GitHub Marketplace" para obter um exemplo da carga do evento marketplace_purchase.
Etapa 2. Instalação
Se seu aplicativo é GitHub App, GitHub irá solicitar ao cliente que selecione quais repositórios o aplicativo pode acessar quando comprá-lo. GitHub em seguida, instala o aplicativo na conta selecionada pelo cliente e concede acesso aos repositórios selecionados.
Neste ponto, se você especificar uma URL de Configuração nas configurações do GitHub App, o GitHub redirecionará o cliente para essa URL. Se não especificar uma URL de configuração, você não conseguirá gerenciar as compras do seu GitHub App.
Note
A Setup URL é descrita como opcional nas configurações do GitHub App, mas é um campo obrigatório se você deseja oferecer seu aplicativo no GitHub Marketplace. Para obter mais informações, confira "Sobre a URL de instalação".
Se seu aplicativo for um OAuth app, GitHub não irá instalá-lo em qualquer lugar. Em vez disso, o GitHub redireciona o cliente para a URL de Instalação especificada na listagem do GitHub Marketplace.
Quando um cliente compra um OAuth app, o GitHub redireciona o cliente para a URL escolhida por você (URL de Configuração ou URL de Instalação) e a URL inclui o plano de preços selecionado pelo cliente como um parâmetro de consulta: marketplace_listing_plan_id.
Etapa 3. Autorização
Quando um cliente compra seu aplicativo, você deve enviar o cliente por meio do fluxo de autorização OAuth:
-
Se o seu aplicativo for um GitHub App, inicie o fluxo de autorização assim que o GitHub redirecionar o cliente para a URL de Configuração. Siga as etapas no "Autenticação com um aplicativo GitHub em nome de um usuário".
-
Se o seu aplicativo for um OAuth app, inicie o fluxo de autorização assim que o GitHub redirecionar o cliente para a URL de Instalação. Siga as etapas no "Autorizar aplicativos OAuth".
Para qualquer tipo de aplicativo, a primeira etapa é redirecionar o cliente para https://github.com/login/oauth/authorize.
Depois que o cliente concluir a autorização, seu aplicativo receberá um token de acesso do OAuth para o cliente. Você prrecisará desse token para a próxima etapa.
Note
Ao autorizar um cliente em uma avaliação gratuita, permita a ele o mesmo acesso que ele terá no plano pago. Você irá transferi-los para o plano pago após o término do período de teste.
Etapa 4. Provisionar as contas dos clientes
Seu aplicativo deve fornecer uma conta de cliente para todas as novas compras. Usando o token de acesso que você recebeu para o cliente na Etapa 3. Autorização, chame o ponto de extremidade "GET /user/marketplace_purchases". A resposta incluirá as informações de account do cliente e mostrará se ele está usando uma avaliação gratuita (on_free_trial). Use estas informações para concluir a configuração e o provisionamento.
Observação: na versão atual do GitHub Marketplace, é possível para um cliente comprar seu aplicativo por meio do GitHub Marketplace quando ele já tem uma conta comprada no site do seu aplicativo. Se você descobrir que já tem uma conta configurada para o cliente que comprou seu aplicativo, relate as compras "duplas" para o Suporte do GitHub.
Se a compra for para uma organização e por usuário, você poderá solicitar que o cliente escolha quais integrantes da organização terão acesso ao aplicativo comprado.
É possível personalizar a forma como os integrantes da organização recebem acesso ao seu aplicativo. Veja algumas sugestões:
Preço de taxa fixa: se a compra for feita para uma organização usando o preço de taxa fixa, seu aplicativo poderá obter todos os membros da organização por meio da API e solicitar ao administrador da organização que escolha os membros que terão usuários pagos no lado do integrador.
Preço por unidade: um método de provisionamento de estações por unidade é permitir que os usuários ocupem uma estação enquanto fazem logon no aplicativo. Quando o cliente atingir o limite de contagem da estação, seu aplicativo poderá alertar o usuário de que ele precisa fazer a atualização do plano de GitHub Marketplace.