새 구매 및 평가판 처리

고객이 GitHub Marketplace 앱의 유료 플랜, 무료 평가판 또는 무료 버전을 구매하면 구매 흐름을 시작하는 purchased 작업으로 marketplace_purchase 이벤트 웹후크를 받게 됩니다.

이 문서의 내용

Note

이 문서는 GitHub Marketplace의 앱 게시에만 적용됩니다. GitHub Actions의 GitHub Actions 배포에 대한 자세한 내용은 "GitHub Marketplace에서 작업 게시"을(를) 참조하세요.

Warning

GitHub Marketplace에서 GitHub App을 제공하는 경우 귀하의 앱은 OAuth 권한 부여 흐름을 따르는 사용자를 식별해야 합니다. 이 흐름을 지원하기 위해 별도의 OAuth app을 설정할 필요가 없습니다. 자세한 내용은 사용자를 대신하여 GitHub 앱으로 인증을(를) 참조하세요.

1단계. 초기 구매 및 웹후크 이벤트

고객이 귀하의 GitHub Marketplace 앱을 구매하기 전에 목록 플랜을 선택합니다. 또한 고객은 개인 계정 또는 조직 계정에서 앱을 구매할지 여부를 선택합니다.

고객이 주문 완료 및 설치 시작을 클릭하여 구매를 완료합니다.

GitHub Enterprise Cloud는 purchased 작업과 함께 marketplace_purchase 웹후크를 앱에 보냅니다.

marketplace_purchase 웹후크에서 effective_date 및 marketplace_purchase 개체를 읽고 고객이 구매한 플랜, 청구 기간이 시작되는 시점 및 다음 청구 기간이 시작되는 시점을 결정합니다.

앱이 평가판을 제공하는 경우 웹후크에서 marketplace_purchase[on_free_trial] 특성을 읽습니다. 값이 true인 경우 앱은 평가판 시작 날짜(effective_date)와 평가판 종료 날짜(free_trial_ends_on)를 추적해야 합니다. free_trial_ends_on 날짜를 사용하여 앱의 UI에 남은 평가판 사용 일 수를 표시합니다. 배너 또는 청구 UI에서 이 정보를 표시할 수 있습니다. 평가판이 끝나기 전에 취소를 처리하는 방법을 알아보려면 플랜 취소 처리을(를) 참조하세요. 평가판 만료 시 평가판을 유료 플랜으로 전환하는 방법을 알아보려면 플랜 변경 처리을(를) 참조하세요.

marketplace_purchase 이벤트 페이로드의 예시는 GitHub Marketplace API에 대한 웹후크 이벤트을(를) 참조하세요.

2단계. 설치

귀하의 앱이 GitHub App인 경우 GitHub Enterprise Cloud에서는 구매 시 앱에서 액세스할 수 있는 리포지토리를 선택하라는 메시지를 고객에게 표시합니다. GitHub Enterprise Cloud는 고객이 선택한 계정에 앱을 설치하고 선택한 리포지토리에 대한 액세스 권한을 부여합니다.

이 때, GitHub App 설정에서 설정 URL을 지정한 경우 GitHub Enterprise Cloud는 고객을 해당 URL로 리디렉션합니다. 설정 URL을 지정하지 않으면 GitHub App의 구매를 처리할 수 없습니다.

Note

설정 URL은 GitHub App 설정에서 선택 사항으로 표시되지만 GitHub Marketplace에서 앱을 제공하려는 경우에는 필수 필드입니다. 자세한 내용은 설치 URL 정보을(를) 참조하세요.

앱이 OAuth app인 경우 GitHub Enterprise Cloud는 아무 곳에도 앱을 설치하지 않습니다. 대신 GitHub Enterprise Cloud는 GitHub Marketplace 목록에서 지정한 설치 URL로 고객을 리디렉션합니다.

고객이 OAuth app을 구매하면 GitHub Enterprise Cloud가 귀하가 선택한 URL(설정 URL 또는 설치 URL)로 고객을 리디렉션하고 해당 URL에는 고객이 선택한 가격 책정 플랜이 쿼리 매개 변수 marketplace_listing_plan_id로 포함됩니다.

3단계 Authorization

고객이 귀하의 앱을 구매할 때 OAuth 권한 부여 흐름을 통해 고객을 보내야 합니다.

  • 앱이 GitHub App인 경우 GitHub Enterprise Cloud가 고객을 설정 URL로 리디렉션하는 즉시 권한 부여 흐름을 시작합니다. 사용자를 대신하여 GitHub 앱으로 인증의 단계를 따릅니다.

  • 앱이 OAuth app인 경우 GitHub Enterprise Cloud가 고객을 설치 URL로 리디렉션하는 즉시 권한 부여 흐름을 시작합니다. OAuth 앱 권한 부여의 단계를 따릅니다.

두 유형의 앱에 대해 첫 번째 단계는 고객을 https://github.com/login/oauth/authorize로 리디렉션하는 것입니다.

고객이 권한 부여를 완료하면 앱은 고객에 대한 OAuth 액세스 토큰을 받습니다. 이 토큰은 다음 단계에서 필요합니다.

Note

평가판에서 고객에게 권한을 부여하는 경우 유료 플랜에서 고객에게 부여할 수 있는 것과 동일한 액세스 권한을 부여합니다. 평가 기간이 종료된 후 해당 고객을 유료 플랜으로 이동합니다.

4단계 고객 계정 프로비저닝

앱은 모든 새 구매에 대한 고객 계정을 프로비저닝해야 합니다. 3단계에서 고객에 대해 받은 액세스 토큰을 사용합니다. 권한 부여, GET /user/marketplace_purchases 엔드포인트를 호출합니다. 응답에는 고객의 account 정보가 포함되며 해당 고객이 평가판(on_free_trial)을 사용 중인지 여부가 표시됩니다. 이 정보를 사용하여 설정 및 프로비저닝을 완료합니다.

Note

현재 버전의 GitHub Marketplace에서는 고객이 앱의 웹 사이트에서 기존 계정을 이미 구매한 경우GitHub Marketplace를 통해 앱을 구매할 수 있습니다. 앱을 구매한 고객에 대한 계정이 이미 설정되어 있는 경우 GitHub 지원 팀에 “이중” 구매를 보고하세요.

조직 및 사용자별 구매인 경우 고객에게 구매한 앱에 액세스할 수 있는 조직 구성원을 선택하라는 메시지를 표시할 수 있습니다.

조직 구성원이 앱에 대한 액세스 권한을 받는 방법을 사용자 지정할 수 있습니다. 다음은 몇 가지 제안입니다.

정액제 가격 책정: 고정 요금 가격을 사용하여 조직에 대해 구매가 이루어진 경우 앱은 API를 통해 조직의 모든 구성원을 얻고 조직 소유자에게 통합자 측에서 유료 사용자가 있는 구성원을 선택하라는 메시지를 표시할 수 있습니다.

단위당 가격 책정: 단위당 사용자를 프로비저닝하는 한 가지 방법은 사용자가 앱에 로그인할 때 실제 사용수를 더하는 것입니다. 고객이 실제 사용자 수 임계값에 도달하면 앱에서는 GitHub Marketplace를 통해 업그레이드해야 한다는 메시지를 사용자에게 표시할 수 있습니다.