Se você oferece um aplicativo GitHub em GitHub Marketplace, seu aplicativo deverá identificar usuários seguindo o fluxo de autorização do OAuth. Você não precisa configurar aplicativo OAuth separadamente para dar suporte a este fluxo. Consulte "Identificar e autorizar usuários para Aplicativos do GitHub" para obter mais informações.
Etapa 1. Compra inicial e evento de webhook
Antes de um cliente comprar o seu aplicativo no GitHub Marketplace, ele irá selecionar 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 começar a instalação.
GitHub depois envia o webhook de marketplace_purchase com a ação purchased para o seu aplicativo.
Leia o objeto effective_date e marketplace_purchase do webhook marketplace_purchase para determinar qual plano o cliente comprou, quando começa o ciclo de cobrança, e quando começa o próximo ciclo de cobrança.
Se o seu aplicativo oferecer um teste grátis, leia o atributo marketplace_purchase[on_free_trial] do webhook. Se o valor for verdadeiro, seu aplicativo deverá acompanhar a data de início de teste gratuito (effective_date) e a data em que o teste gratuito termina (free_trial_ends_on). Use a data free_trial_ends_on para exibir os dias restantes em um teste gratuito na interface de usuário do seu aplicativo. Você pode fazer isso em um banner ou na sua interface de usuário de cobrança. Para aprender como lidar com os cancelamentos antes de um teste grátis, consulte "Gerenciar cancelamentos de plano". Consulte "Gerenciamento das alterações de plano" para descobrir como fazer transição de um teste grátis para um plano pago quando um teste gratuito expira.
Consulte " eventos de webhook de GitHub Marketplacepara obter um exemplo da carga de evento marketplace_purchase.
Etapa 2. Instalação
Se seu aplicativo é aplicativo GitHub, 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ê especificou uma Configuração de URL nas suas configurações de aplicativo GitHub, GitHub irá redirecionar o cliente para essa URL. Se não especificar uma URL de configuração, você não conseguirá gerenciar as compras do seu aplicativo GitHub.
Observação: A URL de configuração é descrita como opcional nas configurações de aplicativo GitHub, mas é um campo obrigatório se desejar oferecer seu aplicativo em GitHub Marketplace.
Se seu aplicativo for um aplicativo OAuth, GitHub não irá instalá-lo em qualquer lugar. Em vez disso, GitHub irá redirecionar o cliente para a URL de Instalação que você especificou no seu anúncio de GitHub Marketplace.
Quando um cliente compra um aplicativo OAuth, GitHub irá redirecionar o cliente para a URL que você escolher (URL de configuração ou URL de instalação) e a URL irá incluir o plano de precificação 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 seu aplicativo for aplicativo GitHub, inicie o fluxo de autorização assim que GitHub redirecionar o cliente para a URL de configuração. Siga os passos em "Identificar e autorizar usuários para Aplicativos do GitHub".
-
Se seu aplicativo for um aplicativo OAuth, inicie o fluxo de autorização assim que GitHub redirecionar o cliente para a URL de instalação. Siga as etapas em "Autorizar Aplicativos OAuth".
Para qualquer tipo de aplicativo, o primeiro passo é 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.
Observação: Ao autorizar um cliente em um teste gratuito, conceda a ele o mesmo acesso que ele teria 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. Usar o token de acesso que você recebeu para o cliente na Etapa 3. Autorização, chame o ponto de extremidade "Lista de assinaturas para o usuário autenticado". A resposta incluirá a conta do cliente e mostrará se está em um teste grátis (on_free_trial). Use estas informações para concluir a configuração e o provisionamento.
Nota: Na versão atual do GitHub Marketplace, é possível para um cliente comprar seu aplicativo através GitHub Marketplace quando eles 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 "double” (duplas) ao GitHub Support.
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. Aqui estão algumas sugestões:
Preços fixos: Se a compra for feita para uma organização que usa preços fixos, seu aplicativo poderá obter todos os integrantes da organização através da API e solicitar ao administrador da organização que escolha quais integrantes terão usuários pagos no lado do integrador.
Preços por unidade: Um método de provisionamento de estações por unidade é permitir que os usuários ocupem uma estação enquanto iniciam a sessão do 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.