Gerenciar novas compras e testes grátis

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 Enterprise Cloud 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 expirar.

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 Enterprise Cloud irá solicitar ao cliente que selecione quais repositórios o aplicativo pode acessar quando comprá-lo. GitHub Enterprise Cloud 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 Enterprise Cloud 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.

Se seu aplicativo for um OAuth app, GitHub Enterprise Cloud não irá instalá-lo em qualquer lugar. Em vez disso, o GitHub Enterprise Cloud redireciona o cliente para a URL de Instalação especificada na listagem do GitHub Marketplace.

Quando um cliente compra um OAuth app, o GitHub Enterprise Cloud 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 Enterprise Cloud redirecionar o cliente para a URL de Configuração. Siga as etapas em 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 Enterprise Cloud redirecionar o cliente para a URL de Instalação. Siga as etapas em 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.

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.

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.