updating content files
This commit is contained in:
Grace Park
@@ -11,13 +11,13 @@ redirect_from:
|
||||
---
|
||||
If you follow these best practices it will help you to provide a good customer experience.
|
||||
|
||||
### Customer communication
|
||||
## Customer communication
|
||||
|
||||
- Marketing materials for the app should accurately represent the app's behavior.
|
||||
- Apps should include links to user-facing documentation that describe how to set up and use the app.
|
||||
- Customers should be able to see what type of plan they have in the billing, profile, or account settings section of the app.
|
||||
- Customers should be able to install and use your app on both a personal account and an organization account. They should be able to view and manage the app on those accounts separately.
|
||||
|
||||
### Plan management
|
||||
## Plan management
|
||||
|
||||
{% data reusables.marketplace.marketplace-billing-ui-requirements %}
|
||||
|
||||
@@ -18,11 +18,11 @@ topics:
|
||||
|
||||
The requirements for listing an app on {% data variables.product.prodname_marketplace %} vary according to whether you want to offer a free or a paid app.
|
||||
|
||||
### Requirements for all {% data variables.product.prodname_marketplace %} listings
|
||||
## Requirements for all {% data variables.product.prodname_marketplace %} listings
|
||||
|
||||
All listings on {% data variables.product.prodname_marketplace %} should be for tools that provide value to the {% data variables.product.product_name %} community. When you submit your listing for publication, you must read and accept the terms of the "[{% data variables.product.prodname_marketplace %} Developer Agreement](/articles/github-marketplace-developer-agreement/)."
|
||||
|
||||
#### User experience requirements for all apps
|
||||
### User experience requirements for all apps
|
||||
|
||||
All listings should meet the following requirements, regardless of whether they are for a free or paid app.
|
||||
|
||||
@@ -36,7 +36,7 @@ All listings should meet the following requirements, regardless of whether they
|
||||
|
||||
For more information on providing a good customer experience, see "[Customer experience best practices for apps](/developers/github-marketplace/customer-experience-best-practices-for-apps)."
|
||||
|
||||
#### Brand and listing requirements for all apps
|
||||
### Brand and listing requirements for all apps
|
||||
|
||||
- Apps that use GitHub logos must follow the {% data variables.product.company_short %} guidelines. For more information, see "[{% data variables.product.company_short %} Logos and Usage](https://github.com/logos)."
|
||||
- Apps must have a logo, feature card, and screenshots images that meet the recommendations provided in "[Writing {% data variables.product.prodname_marketplace %} listing descriptions](/marketplace/listing-on-github-marketplace/writing-github-marketplace-listing-descriptions/)."
|
||||
@@ -44,11 +44,11 @@ For more information on providing a good customer experience, see "[Customer exp
|
||||
|
||||
To protect your customers, we recommend that you also follow security best practices. For more information, see "[Security best practices for apps](/developers/github-marketplace/security-best-practices-for-apps)."
|
||||
|
||||
### Considerations for free apps
|
||||
## Considerations for free apps
|
||||
|
||||
{% data reusables.marketplace.free-apps-encouraged %}
|
||||
|
||||
### Requirements for paid apps
|
||||
## Requirements for paid apps
|
||||
|
||||
To publish a paid plan for your app on {% data variables.product.prodname_marketplace %}, your app must be owned by an organization that is a verified publisher. For more information about the verification process or transferring ownership of your app, see "[Applying for publisher verification for your organization](/developers/github-marketplace/applying-for-publisher-verification-for-your-organization)."
|
||||
|
||||
@@ -68,7 +68,7 @@ When you are ready to publish the app on {% data variables.product.prodname_mark
|
||||
|
||||
{% endnote %}
|
||||
|
||||
### Billing requirements for paid apps
|
||||
## Billing requirements for paid apps
|
||||
|
||||
Your app does not need to handle payments but does need to use {% data variables.product.prodname_marketplace %} purchase events to manage new purchases, upgrades, downgrades, cancellations, and free trials. For information about how integrate these events into your app, see "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)."
|
||||
|
||||
|
||||
@@ -14,7 +14,7 @@ topics:
|
||||
---
|
||||
If you follow these best practices it will help you to provide a secure user experience.
|
||||
|
||||
### Authorization, authentication, and access control
|
||||
## Authorization, authentication, and access control
|
||||
|
||||
We recommend creating a GitHub App rather than an OAuth App. {% data reusables.marketplace.github_apps_preferred %}. See "[Differences between GitHub Apps and OAuth Apps](/apps/differences-between-apps/)" for more details.
|
||||
- Apps should use the principle of least privilege and should only request the OAuth scopes and GitHub App permissions that the app needs to perform its intended functionality. For more information, see [Principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) in Wikipedia.
|
||||
@@ -28,7 +28,7 @@ We recommend creating a GitHub App rather than an OAuth App. {% data reusables.m
|
||||
- OAuth Apps should authenticate using an [OAuth token](/apps/building-oauth-apps/authorizing-oauth-apps/).
|
||||
- GitHub Apps should authenticate using either a [JSON Web Token (JWT)](/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app), [OAuth token](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/), or [installation access token](/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-an-installation).
|
||||
|
||||
### Data protection
|
||||
## Data protection
|
||||
|
||||
- Apps should encrypt data transferred over the public internet using HTTPS, with a valid TLS certificate, or SSH for Git.
|
||||
- Apps should store client ID and client secret keys securely. We recommend storing them as [environmental variables](http://en.wikipedia.org/wiki/Environment_variable#Getting_and_setting_environment_variables).
|
||||
@@ -36,7 +36,7 @@ We recommend creating a GitHub App rather than an OAuth App. {% data reusables.m
|
||||
- Apps should not require the user to provide their GitHub password.
|
||||
- Apps should encrypt tokens, client IDs, and client secrets.
|
||||
|
||||
### Logging and monitoring
|
||||
## Logging and monitoring
|
||||
|
||||
Apps should have logging and monitoring capabilities. App logs should be retained for at least 30 days and archived for at least one year.
|
||||
A security log should include:
|
||||
@@ -49,13 +49,13 @@ A security log should include:
|
||||
- Consistent timestamping for each event
|
||||
- Source users, IP addresses, and/or hostnames for all logged actions
|
||||
|
||||
### Incident response workflow
|
||||
## Incident response workflow
|
||||
|
||||
To provide a secure experience for users, you should have a clear incident response plan in place before listing your app. We recommend having a security and operations incident response team in your company rather than using a third-party vendor. You should have the capability to notify {% data variables.product.product_name %} within 24 hours of a confirmed incident.
|
||||
|
||||
For an example of an incident response workflow, see the "Data Breach Response Policy" on the [SANS Institute website](https://www.sans.org/information-security-policy/). A short document with clear steps to take in the event of an incident is more valuable than a lengthy policy template.
|
||||
|
||||
### Vulnerability management and patching workflow
|
||||
## Vulnerability management and patching workflow
|
||||
|
||||
You should conduct regular vulnerability scans of production infrastructure. You should triage the results of vulnerability scans and define a period of time in which you agree to remediate the vulnerability.
|
||||
|
||||
|
||||
@@ -20,7 +20,7 @@ You can view metrics for the past day (24 hours), week, month, or for the entire
|
||||
|
||||
{% endnote %}
|
||||
|
||||
### Performance metrics
|
||||
## Performance metrics
|
||||
|
||||
The Insights page displays these performance metrics, for the selected time period:
|
||||
|
||||
@@ -34,7 +34,7 @@ The Insights page displays these performance metrics, for the selected time peri
|
||||
|
||||
{% endnote %}
|
||||
|
||||
#### Conversion performance
|
||||
### Conversion performance
|
||||
|
||||
* **Unique visitors to landing page:** Number of people who viewed your GitHub App's landing page.
|
||||
* **Unique visitors to checkout page:** Number of people who viewed one of your GitHub App's checkout pages.
|
||||
|
||||
@@ -18,7 +18,7 @@ topics:
|
||||
|
||||
You can view or download the transaction data to keep track of your subscription activity. Click the **Export CSV** button to download a `.csv` file. You can also select a period of time to view and search within the transaction page.
|
||||
|
||||
### Transaction data fields
|
||||
## Transaction data fields
|
||||
|
||||
* **date:** The date of the transaction in `yyyy-mm-dd` format.
|
||||
* **app_name:** The app name.
|
||||
@@ -32,7 +32,7 @@ You can view or download the transaction data to keep track of your subscription
|
||||
|
||||
|
||||
|
||||
### Accessing {% data variables.product.prodname_marketplace %} transactions
|
||||
## Accessing {% data variables.product.prodname_marketplace %} transactions
|
||||
|
||||
To access {% data variables.product.prodname_marketplace %} transactions:
|
||||
|
||||
|
||||
@@ -12,13 +12,13 @@ topics:
|
||||
---
|
||||
[{% data variables.product.prodname_marketplace %}](https://github.com/marketplace) connects you to developers who want to extend and improve their {% data variables.product.prodname_dotcom %} workflows. You can list free and paid tools for developers to use in {% data variables.product.prodname_marketplace %}. {% data variables.product.prodname_marketplace %} offers developers two types of tools: {% data variables.product.prodname_actions %} and Apps, and each tool requires different steps for adding it to {% data variables.product.prodname_marketplace %}.
|
||||
|
||||
### GitHub Actions
|
||||
## GitHub Actions
|
||||
|
||||
{% data reusables.actions.actions-not-verified %}
|
||||
|
||||
To learn about publishing {% data variables.product.prodname_actions %} in {% data variables.product.prodname_marketplace %}, see "[Publishing actions in GitHub Marketplace](/actions/creating-actions/publishing-actions-in-github-marketplace)."
|
||||
|
||||
### Apps
|
||||
## Apps
|
||||
|
||||
Anyone can share their apps with other users for free on {% data variables.product.prodname_marketplace %} but only apps owned by organizations can sell their app.
|
||||
|
||||
@@ -28,15 +28,15 @@ Once the organization meets the requirements, someone with owner permissions in
|
||||
|
||||
To publish apps with free plans, you only need to meet the general requirements for listing any app. For more information, see "[Requirements for all GitHub Marketplace listings](/developers/github-marketplace/requirements-for-listing-an-app#requirements-for-all-github-marketplace-listings)."
|
||||
|
||||
#### New to apps?
|
||||
### New to apps?
|
||||
|
||||
If you're interested in creating an app for {% data variables.product.prodname_marketplace %}, but you're new to {% data variables.product.prodname_github_apps %} or {% data variables.product.prodname_oauth_app %}s, see "[Building {% data variables.product.prodname_github_apps %}](/developers/apps/building-github-apps)" or "[Building {% data variables.product.prodname_oauth_app %}s](/developers/apps/building-oauth-apps)."
|
||||
|
||||
#### GitHub Apps vs. OAuth Apps
|
||||
### GitHub Apps vs. OAuth Apps
|
||||
|
||||
{% data reusables.marketplace.github_apps_preferred %}, although you can list both OAuth and {% data variables.product.prodname_github_app %}s in {% data variables.product.prodname_marketplace %}. For more information, see "[Differences between {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_app %}s](/apps/differences-between-apps/)" and "[Migrating {% data variables.product.prodname_oauth_app %}s to {% data variables.product.prodname_github_apps %}](/apps/migrating-oauth-apps-to-github-apps/)."
|
||||
|
||||
### Publishing an app to {% data variables.product.prodname_marketplace %} overview
|
||||
## Publishing an app to {% data variables.product.prodname_marketplace %} overview
|
||||
|
||||
When you have finished creating your app, you can share it with other users by publishing it to {% data variables.product.prodname_marketplace %}. In summary, the process is:
|
||||
|
||||
@@ -52,13 +52,13 @@ When you have finished creating your app, you can share it with other users by p
|
||||
|
||||
1. Submit your listing for publication in {% data variables.product.prodname_marketplace %}. For more information, see "[Submitting your listing for publication](/developers/github-marketplace/submitting-your-listing-for-publication)."
|
||||
|
||||
### Seeing how your app is performing
|
||||
## Seeing how your app is performing
|
||||
|
||||
You can access metrics and transactions for your listing. For more information, see:
|
||||
|
||||
- "[Viewing metrics for your listing](/developers/github-marketplace/viewing-metrics-for-your-listing)"
|
||||
- "[Viewing transactions for your listing](/developers/github-marketplace/viewing-transactions-for-your-listing)"
|
||||
|
||||
### Contacting Support
|
||||
## Contacting Support
|
||||
|
||||
If you have questions about {% data variables.product.prodname_marketplace %}, please contact {% data variables.contact.contact_support %} directly.
|
||||
|
||||
@@ -7,7 +7,7 @@ redirect_from:
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
---
|
||||
### For GitHub Apps
|
||||
## For GitHub Apps
|
||||
|
||||
Certain apps on the {% data variables.product.prodname_marketplace %} have the {% octicon "verified" aria-label="The verified badge" %} badge and a tooltip that says "Publisher domain and email verified". This means that the app is owned by an organization that has:
|
||||
|
||||
@@ -31,7 +31,7 @@ For more information about the requirements for listing an app on {% data variab
|
||||
|
||||
For information on finding apps to use, see "[Searching {% data variables.product.prodname_marketplace %}](/github/searching-for-information-on-github/searching-github-marketplace)."
|
||||
|
||||
### For GitHub actions
|
||||
## For GitHub actions
|
||||
|
||||
Actions with the {% octicon "verified" aria-label="The verified badge" %}, or verified creator badge, indicate that {% data variables.product.prodname_dotcom %} has verified the creator of the action as a partner organization.
|
||||
|
||||
|
||||
@@ -14,7 +14,7 @@ Once your organization has been verified, you can publish paid plans for your ap
|
||||
|
||||
To offer paid plans for your app, the app must be owned by an organization and you must have owner permissions in the organization. If your app is currently owned by a user account, you'll need to transfer the ownership of the app to an organization. For more information, see "[Transferring ownership of a GitHub App](/developers/apps/transferring-ownership-of-a-github-app)" or "[Transferring ownership of an OAuth App](/developers/apps/transferring-ownership-of-an-oauth-app)."
|
||||
|
||||
### Requesting publisher verification
|
||||
## Requesting publisher verification
|
||||
|
||||
|
||||
{% data reusables.profile.access_org %}
|
||||
@@ -32,6 +32,6 @@ To offer paid plans for your app, the app must be owned by an organization and y
|
||||
|
||||
2. Click **Request Verification**. {% data variables.product.company_short %} will review your details and let you know once your publisher verification is complete.
|
||||
|
||||
### Further reading
|
||||
## Further reading
|
||||
|
||||
For information about the process of publishing apps, see "[About GitHub Marketplace](/developers/github-marketplace/about-github-marketplace)."
|
||||
|
||||
@@ -15,27 +15,27 @@ topics:
|
||||
---
|
||||
The {% data variables.product.prodname_marketplace %} event webhook can only be set up from your application's {% data variables.product.prodname_marketplace %} listing page. You can configure all other events from your [application's developer settings page](https://github.com/settings/developers). If you haven't created a {% data variables.product.prodname_marketplace %} listing, read "[Creating a draft {% data variables.product.prodname_marketplace %} listing](/marketplace/listing-on-github-marketplace/creating-a-draft-github-marketplace-listing/)" to learn how.
|
||||
|
||||
### Creating a webhook
|
||||
## Creating a webhook
|
||||
|
||||
To create a webhook for your {% data variables.product.prodname_marketplace %} listing, click **Webhook** in the left sidebar of your [{% data variables.product.prodname_marketplace %} listing page](https://github.com/marketplace/manage). You'll see the following webhook configuration options needed to configure your webhook:
|
||||
|
||||
#### Payload URL
|
||||
### Payload URL
|
||||
|
||||
{% data reusables.webhooks.payload_url %}
|
||||
|
||||
#### Content type
|
||||
### Content type
|
||||
|
||||
{% data reusables.webhooks.content_type %} GitHub recommends using the `application/json` content type.
|
||||
|
||||
#### Secret
|
||||
### Secret
|
||||
|
||||
{% data reusables.webhooks.secret %}
|
||||
|
||||
#### Active
|
||||
### Active
|
||||
|
||||
By default, webhook deliveries are "Active." You can choose to disable the delivery of webhook payloads during development by deselecting "Active." If you've disabled webhook deliveries, you will need to select "Active" before you submit your app for review.
|
||||
|
||||
### Viewing webhook deliveries
|
||||
## Viewing webhook deliveries
|
||||
|
||||
Once you've configured your {% data variables.product.prodname_marketplace %} webhook, you'll be able to inspect `POST` request payloads from the **Webhook** page of your application's [{% data variables.product.prodname_marketplace %} listing](https://github.com/marketplace/manage). GitHub doesn't resend failed delivery attempts. Ensure your app can receive all webhook payloads sent by GitHub.
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@ versions:
|
||||
topics:
|
||||
- Marketplace
|
||||
---
|
||||
### Create a new draft {% data variables.product.prodname_marketplace %} listing
|
||||
## Create a new draft {% data variables.product.prodname_marketplace %} listing
|
||||
|
||||
You can only create draft listings for apps that are public. Before creating your draft listing, you can read the following guidelines for writing and configuring settings in your {% data variables.product.prodname_marketplace %} listing:
|
||||
|
||||
@@ -53,14 +53,14 @@ To create a {% data variables.product.prodname_marketplace %} listing:
|
||||
|
||||
{% endnote %}
|
||||
|
||||
### Editing your listing
|
||||
## Editing your listing
|
||||
|
||||
Once you've created a {% data variables.product.prodname_marketplace %} draft listing, you can come back to modify information in your listing anytime. If your app is already approved and in {% data variables.product.prodname_marketplace %}, you can edit the information and images in your listing, but you will not be able to change existing published pricing plans. See "[Setting a {% data variables.product.prodname_marketplace %} listing's pricing plan](/marketplace/listing-on-github-marketplace/setting-a-github-marketplace-listing-s-pricing-plan/)."
|
||||
|
||||
### Submitting your app
|
||||
## Submitting your app
|
||||
|
||||
Once you've completed your {% data variables.product.prodname_marketplace %} listing, you can submit your listing for review from the **Overview** page. You'll need to read and accept the "[{% data variables.product.prodname_marketplace %} Developer Agreement](/articles/github-marketplace-developer-agreement/)," and then you can click **Submit for review**. After you submit your app for review, an onboarding expert will contact you with additional information about the onboarding process.
|
||||
|
||||
### Removing a {% data variables.product.prodname_marketplace %} listing
|
||||
## Removing a {% data variables.product.prodname_marketplace %} listing
|
||||
|
||||
If you no longer want to list your app in {% data variables.product.prodname_marketplace %}, contact {% data variables.contact.contact_support %} to remove your listing.
|
||||
|
||||
@@ -19,7 +19,7 @@ versions:
|
||||
topics:
|
||||
- Marketplace
|
||||
---
|
||||
### About setting pricing plans
|
||||
## About setting pricing plans
|
||||
|
||||
{% data variables.product.prodname_marketplace %} offers several different types of pricing plans. For detailed information, see "[Pricing plans for {% data variables.product.prodname_marketplace %}](/developers/github-marketplace/pricing-plans-for-github-marketplace-apps)."
|
||||
|
||||
@@ -31,13 +31,13 @@ If your app is already published with a paid plan and you're a verified publishe
|
||||
|
||||
If your app is already published with a paid plan and but you are not a verified publisher, then you can cannot publish a new paid plan until you are a verified publisher. For more information about becoming a verified publisher, see "[Applying for publisher verification for your organization](/developers/github-marketplace/applying-for-publisher-verification-for-your-organization)."
|
||||
|
||||
### About saving pricing plans
|
||||
## About saving pricing plans
|
||||
|
||||
You can save pricing plans in a draft or published state. If you haven't submitted your {% data variables.product.prodname_marketplace %} listing for approval, a published plan will function in the same way as a draft plan until your listing is approved and shown on {% data variables.product.prodname_marketplace %}. Draft plans allow you to create and save new pricing plans without making them available on your {% data variables.product.prodname_marketplace %} listing page. Once you publish a pricing plan on a published listing, it's available for customers to purchase immediately. You can publish up to 10 pricing plans.
|
||||
|
||||
For guidelines on billing customers, see "[Billing customers](/developers/github-marketplace/billing-customers)."
|
||||
|
||||
### Creating pricing plans
|
||||
## Creating pricing plans
|
||||
|
||||
To create a pricing plan for your {% data variables.product.prodname_marketplace %} listing, click **Plans and pricing** in the left sidebar of your [{% data variables.product.prodname_marketplace %} listing page](https://github.com/marketplace/manage). For more information, see "[Creating a draft {% data variables.product.prodname_marketplace %} listing](/marketplace/listing-on-github-marketplace/creating-a-draft-github-marketplace-listing/)."
|
||||
|
||||
@@ -62,7 +62,7 @@ When you click **New draft plan**, you'll see a form that allows you to customiz
|
||||
|
||||
{% data reusables.marketplace.free-plan-note %}
|
||||
|
||||
### Changing a {% data variables.product.prodname_marketplace %} listing's pricing plan
|
||||
## Changing a {% data variables.product.prodname_marketplace %} listing's pricing plan
|
||||
|
||||
If a pricing plan for your {% data variables.product.prodname_marketplace %} listing is no longer needed, or if you need to adjust pricing details, you can remove it.
|
||||
|
||||
|
||||
@@ -18,23 +18,23 @@ topics:
|
||||
---
|
||||
Here are guidelines about the fields you'll need to fill out in the **Listing description** section of your draft listing.
|
||||
|
||||
### Naming and links
|
||||
## Naming and links
|
||||
|
||||
#### Listing name
|
||||
### Listing name
|
||||
|
||||
Your listing's name will appear on the [{% data variables.product.prodname_marketplace %} homepage](https://github.com/marketplace). The name is limited to 255 characters and can be different from your app's name. Your listing cannot have the same name as an existing {% data variables.product.product_name %} account, unless the name is your own user or organization name.
|
||||
|
||||
#### Very short description
|
||||
### Very short description
|
||||
|
||||
The community will see the "very short" description under your app's name on the [{% data variables.product.prodname_marketplace %} homepage](https://github.com/marketplace).
|
||||
|
||||
|
||||
|
||||
##### Length
|
||||
#### Length
|
||||
|
||||
We recommend keeping short descriptions to 40-80 characters. Although you are allowed to use more characters, concise descriptions are easier for customers to read and understand quickly.
|
||||
|
||||
##### Content
|
||||
#### Content
|
||||
|
||||
- Describe the app’s functionality. Don't use this space for a call to action. For example:
|
||||
|
||||
@@ -50,7 +50,7 @@ We recommend keeping short descriptions to 40-80 characters. Although you are al
|
||||
|
||||
**DON'T:** Skycap is a container-native continuous integration tool
|
||||
|
||||
##### Formatting
|
||||
#### Formatting
|
||||
|
||||
- Always use sentence-case capitalization. Only capitalize the first letter and proper nouns.
|
||||
|
||||
@@ -76,15 +76,15 @@ We recommend keeping short descriptions to 40-80 characters. Although you are al
|
||||
|
||||
**DON'T:** Agile task boards, estimates, and reports without leaving GitHub’s UI
|
||||
|
||||
#### Categories
|
||||
### Categories
|
||||
|
||||
Apps in {% data variables.product.prodname_marketplace %} can be displayed by category. Select the category that best describes the main functionality of your app in the **Primary category** dropdown, and optionally select a **Secondary category** that fits your app.
|
||||
|
||||
#### Supported languages
|
||||
### Supported languages
|
||||
|
||||
If your app only works with specific languages, select up to 10 programming languages that your app supports. These languages are displayed on your app's {% data variables.product.prodname_marketplace %} listing page. This field is optional.
|
||||
|
||||
#### Listing URLs
|
||||
### Listing URLs
|
||||
|
||||
**Required URLs**
|
||||
* **Customer support URL:** The URL of a web page that your customers will go to when they have technical support, product, or account inquiries.
|
||||
@@ -96,7 +96,7 @@ If your app only works with specific languages, select up to 10 programming lang
|
||||
* **Status URL:** A link to a web page that displays the status of your app. Status pages can include current and historical incident reports, web application uptime status, and scheduled maintenance.
|
||||
* **Documentation URL:** A link to documentation that teaches customers how to use your app.
|
||||
|
||||
### Logo and feature card
|
||||
## Logo and feature card
|
||||
|
||||
{% data variables.product.prodname_marketplace %} displays all listings with a square logo image inside a circular badge to visually distinguish apps.
|
||||
|
||||
@@ -108,7 +108,7 @@ A feature card consists of your app's logo, name, and a custom background image
|
||||
|
||||
As you upload images and select colors, your {% data variables.product.prodname_marketplace %} draft listing will display a preview of your logo and feature card.
|
||||
|
||||
##### Guidelines for logos
|
||||
#### Guidelines for logos
|
||||
|
||||
You must upload a custom image for the logo. For the badge, choose a background color.
|
||||
|
||||
@@ -118,7 +118,7 @@ You must upload a custom image for the logo. For the badge, choose a background
|
||||
- To give the appearance of a seamless badge, choose a badge background color that matches the background color (or transparency) of your logo image.
|
||||
- Avoid using logo images with words or text in them. Logos with text do not scale well on small screens.
|
||||
|
||||
##### Guidelines for feature cards
|
||||
#### Guidelines for feature cards
|
||||
|
||||
You must upload a custom background image for the feature card. For the app's name, choose a text color.
|
||||
|
||||
@@ -126,7 +126,7 @@ You must upload a custom background image for the feature card. For the app's na
|
||||
- Background image measures 965 pixels x 482 pixels (width x height).
|
||||
- Choose a text color for your app's name that shows up clearly over the background image.
|
||||
|
||||
### Listing details
|
||||
## Listing details
|
||||
|
||||
To get to your app's landing page, click your app's name from the {% data variables.product.prodname_marketplace %} homepage or category page. The landing page displays a longer description of the app, which includes two parts: an "Introductory description" and a "Detailed description."
|
||||
|
||||
@@ -140,19 +140,19 @@ Clicking **Read more...**, displays the "Detailed description."
|
||||
|
||||
Follow these guidelines for writing these descriptions.
|
||||
|
||||
#### Length
|
||||
### Length
|
||||
|
||||
We recommend writing a 1-2 sentence high-level summary between 150-250 characters in the required "Introductory description" field when [listing your app](/marketplace/listing-on-github-marketplace/). Although you are allowed to use more characters, concise summaries are easier for customers to read and understand quickly.
|
||||
|
||||
You can add more information in the optional "Detailed description" field. You see this description when you click **Read more...** below the introductory description on your app's landing page. A detailed description consists of 3-5 [value propositions](https://en.wikipedia.org/wiki/Value_proposition), with 1-2 sentences describing each one. You can use up to 1,000 characters for this description.
|
||||
|
||||
#### Content
|
||||
### Content
|
||||
|
||||
- Always begin introductory descriptions with your app's name.
|
||||
|
||||
- Always write descriptions and value propositions using the active voice.
|
||||
|
||||
#### Formatting
|
||||
### Formatting
|
||||
|
||||
- Always use sentence-case capitalization in value proposition titles. Only capitalize the first letter and proper nouns.
|
||||
|
||||
@@ -178,11 +178,11 @@ You can add more information in the optional "Detailed description" field. You s
|
||||
|
||||
- Avoid acronyms unless they’re well established (such as API).
|
||||
|
||||
### Product screenshots
|
||||
## Product screenshots
|
||||
|
||||
You can upload up to five screenshot images of your app to display on your app's landing page. Add an optional caption to each screenshot to provide context. After you upload your screenshots, you can drag them into the order you want them to be displayed on the landing page.
|
||||
|
||||
#### Guidelines for screenshots
|
||||
### Guidelines for screenshots
|
||||
|
||||
- Images must be of high resolution (at least 1200px wide).
|
||||
- All images must be the same height and width (aspect ratio) to avoid page jumps when people click from one image to the next.
|
||||
|
||||
@@ -11,23 +11,23 @@ versions:
|
||||
topics:
|
||||
- Marketplace
|
||||
---
|
||||
### Understanding the billing cycle
|
||||
## Understanding the billing cycle
|
||||
|
||||
Customers can choose a monthly or yearly billing cycle when they purchase your app. All changes customers make to the billing cycle and plan selection will trigger a `marketplace_purchase` event. You can refer to the `marketplace_purchase` webhook payload to see which billing cycle a customer selects and when the next billing date begins (`effective_date`). For more information about webhook payloads, see "[Webhook events for the {% data variables.product.prodname_marketplace %} API](/developers/github-marketplace/webhook-events-for-the-github-marketplace-api)."
|
||||
|
||||
### Providing billing services in your app's UI
|
||||
## Providing billing services in your app's UI
|
||||
|
||||
Customers should be able to perform the following actions from your app's website:
|
||||
- Customers should be able to modify or cancel their {% data variables.product.prodname_marketplace %} plans for personal and organizational accounts separately.
|
||||
{% data reusables.marketplace.marketplace-billing-ui-requirements %}
|
||||
|
||||
### Billing services for upgrades, downgrades, and cancellations
|
||||
## Billing services for upgrades, downgrades, and cancellations
|
||||
|
||||
Follow these guidelines for upgrades, downgrades, and cancellations to maintain a clear and consistent billing process. For more detailed instructions about the {% data variables.product.prodname_marketplace %} purchase events, see "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)."
|
||||
|
||||
You can use the `marketplace_purchase` webhook's `effective_date` key to determine when a plan change will occur and periodically synchronize the [List accounts for a plan](/rest/reference/apps#list-accounts-for-a-plan).
|
||||
|
||||
#### Upgrades
|
||||
### Upgrades
|
||||
|
||||
When a customer upgrades their pricing plan or changes their billing cycle from monthly to yearly, you should make the change effective for them immediately. You need to apply a pro-rated discount to the new plan and change the billing cycle.
|
||||
|
||||
@@ -35,7 +35,7 @@ When a customer upgrades their pricing plan or changes their billing cycle from
|
||||
|
||||
For information about building upgrade and downgrade workflows into your app, see "[Handling plan changes](/developers/github-marketplace/handling-plan-changes)."
|
||||
|
||||
#### Downgrades and cancellations
|
||||
### Downgrades and cancellations
|
||||
|
||||
Downgrades occur when a customer moves to a free plan from a paid plan, selects a plan with a lower cost than their current plan, or changes their billing cycle from yearly to monthly. When downgrades or cancellations occur, you don't need to provide a refund. Instead, the current plan will remain active until the last day of the current billing cycle. The `marketplace_purchase` event will be sent when the new plan takes effect at the beginning of the customer's next billing cycle.
|
||||
|
||||
|
||||
@@ -20,9 +20,9 @@ For more information on how to create a pricing plan, see "[Setting a {% data va
|
||||
|
||||
{% data reusables.marketplace.free-plan-note %}
|
||||
|
||||
### Types of pricing plans
|
||||
## Types of pricing plans
|
||||
|
||||
#### Free pricing plans
|
||||
### Free pricing plans
|
||||
|
||||
{% data reusables.marketplace.free-apps-encouraged %}
|
||||
|
||||
@@ -32,7 +32,7 @@ All apps need to handle events for new purchases and cancellations. Apps that on
|
||||
|
||||
If you add a paid plan to an app that you've already listed in {% data variables.product.prodname_marketplace %} as a free service, you'll need to request verification for the app and go through financial onboarding.
|
||||
|
||||
#### Paid pricing plans
|
||||
### Paid pricing plans
|
||||
|
||||
There are two types of paid pricing plan:
|
||||
|
||||
@@ -42,7 +42,7 @@ There are two types of paid pricing plan:
|
||||
|
||||
You may also want to offer free trials. These provide free, 14-day trials of OAuth or GitHub Apps to customers. When you set up a Marketplace pricing plan, you can select the option to provide a free trial for flat-rate or per-unit pricing plans.
|
||||
|
||||
### Free trials
|
||||
## Free trials
|
||||
|
||||
Customers can start a free trial for any paid plan on a Marketplace listing that includes free trials. However, customers cannot create more than one free trial per marketplace product.
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@ If you offer a {% data variables.product.prodname_github_app %} in {% data varia
|
||||
|
||||
{% endwarning %}
|
||||
|
||||
### Step 1. Initial purchase and webhook event
|
||||
## Step 1. Initial purchase and webhook event
|
||||
|
||||
Before a customer purchases your {% data variables.product.prodname_marketplace %} app, they select a [listing plan](/marketplace/selling-your-app/github-marketplace-pricing-plans/). They also choose whether to purchase the app from their personal account or an organization account.
|
||||
|
||||
@@ -32,7 +32,7 @@ If your app offers a free trial, read the `marketplace_purchase[on_free_trial]`
|
||||
|
||||
See "[{% data variables.product.prodname_marketplace %} webhook events](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/)" for an example of the `marketplace_purchase` event payload.
|
||||
|
||||
### Step 2. Installation
|
||||
## Step 2. Installation
|
||||
|
||||
If your app is a {% data variables.product.prodname_github_app %}, {% data variables.product.product_name %} prompts the customer to select which repositories the app can access when they purchase it. {% data variables.product.product_name %} then installs the app on the account the customer selected and grants access to the selected repositories.
|
||||
|
||||
@@ -48,7 +48,7 @@ If your app is an {% data variables.product.prodname_oauth_app %}, {% data varia
|
||||
|
||||
When a customer purchases an {% data variables.product.prodname_oauth_app %}, {% data variables.product.product_name %} redirects the customer to the URL you choose (either Setup URL or Installation URL) and the URL includes the customer's selected pricing plan as a query parameter: `marketplace_listing_plan_id`.
|
||||
|
||||
### Step 3. Authorization
|
||||
## Step 3. Authorization
|
||||
|
||||
When a customer purchases your app, you must send the customer through the OAuth authorization flow:
|
||||
|
||||
@@ -66,7 +66,7 @@ After the customer completes the authorization, your app receives an OAuth acces
|
||||
|
||||
{% endnote %}
|
||||
|
||||
### Step 4. Provisioning customer accounts
|
||||
## Step 4. Provisioning customer accounts
|
||||
|
||||
Your app must provision a customer account for all new purchases. Using the access token you received for the customer in [Step 3. Authorization](#step-3-authorization), call the "[List subscriptions for the authenticated user](/rest/reference/apps#list-subscriptions-for-the-authenticated-user)" endpoint. The response will include the customer's `account` information and show whether they are on a free trial (`on_free_trial`). Use this information to complete setup and provisioning.
|
||||
|
||||
|
||||
@@ -13,11 +13,11 @@ topics:
|
||||
---
|
||||
For more information about cancelling as it relates to billing, see "[Billing customers in {% data variables.product.prodname_marketplace %}](/apps//marketplace/administering-listing-plans-and-user-accounts/billing-customers-in-github-marketplace)."
|
||||
|
||||
### Step 1. Cancellation event
|
||||
## Step 1. Cancellation event
|
||||
|
||||
If a customer chooses to cancel a {% data variables.product.prodname_marketplace %} order, GitHub sends a [`marketplace_purchase`](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/) webhook with the action `cancelled` to your app when the cancellation takes effect. If the customer cancels during a free trial, your app will receive the event immediately. When a customer cancels a paid plan, the cancellation will occur at the end of the customer's billing cycle.
|
||||
|
||||
### Step 2. Deactivating customer accounts
|
||||
## Step 2. Deactivating customer accounts
|
||||
|
||||
When a customer cancels a free or paid plan, your app must perform these steps to complete cancellation:
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@ topics:
|
||||
---
|
||||
For more information about upgrading and downgrading as it relates to billing, see "[Integrating with the {% data variables.product.prodname_marketplace %} API](/marketplace/integrating-with-the-github-marketplace-api/)."
|
||||
|
||||
### Step 1. Pricing plan change event
|
||||
## Step 1. Pricing plan change event
|
||||
|
||||
GitHub send the `marketplace_purchase` webhook with the `changed` action to your app, when a customer makes any of these changes to their {% data variables.product.prodname_marketplace %} order:
|
||||
* Upgrades to a more expensive pricing plan or downgrades to a lower priced plan.
|
||||
@@ -26,7 +26,7 @@ Read the `effective_date`, `marketplace_purchase`, and `previous_marketplace_pur
|
||||
|
||||
If your app offers free trials, you'll receive the `marketplace_purchase` webhook with the `changed` action when the free trial expires. If the customer's free trial expires, upgrade the customer to the paid version of the free-trial plan.
|
||||
|
||||
### Step 2. Updating customer accounts
|
||||
## Step 2. Updating customer accounts
|
||||
|
||||
You'll need to update the customer's account information to reflect the billing cycle and pricing plan changes the customer made to their {% data variables.product.prodname_marketplace %} order. Display upgrades to the pricing plan, `seat_count` (for per-unit pricing plans), and billing cycle on your Marketplace app's website or your app's UI when you receive the `changed` action webhook.
|
||||
|
||||
@@ -40,11 +40,11 @@ To encourage people to upgrade you can display an upgrade URL in your app's UI.
|
||||
|
||||
{% endnote %}
|
||||
|
||||
### Failed upgrade payments
|
||||
## Failed upgrade payments
|
||||
|
||||
{% data reusables.marketplace.marketplace-failed-purchase-event %}
|
||||
|
||||
### About upgrade URLs
|
||||
## About upgrade URLs
|
||||
|
||||
You can redirect users from your app's UI to upgrade on GitHub using an upgrade URL:
|
||||
|
||||
|
||||
@@ -11,11 +11,11 @@ versions:
|
||||
topics:
|
||||
- Marketplace
|
||||
---
|
||||
### Testing apps
|
||||
## Testing apps
|
||||
|
||||
You can use a draft {% data variables.product.prodname_marketplace %} listing to simulate each of the billing flows. A listing in the draft state means that it has not been submitted for approval. Any purchases you make using a draft {% data variables.product.prodname_marketplace %} listing will _not_ create real transactions, and GitHub will not charge your credit card. Note that you can only simulate purchases for plans published in the draft listing and not for draft plans. For more information, see "[Drafting a listing for your app](/developers/github-marketplace/drafting-a-listing-for-your-app)" and "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)."
|
||||
|
||||
#### Using a development app with a draft listing to test changes
|
||||
### Using a development app with a draft listing to test changes
|
||||
|
||||
A {% data variables.product.prodname_marketplace %} listing can only be associated with a single app registration, and each app can only access its own {% data variables.product.prodname_marketplace %} listing. For these reasons, we recommend configuring a separate development app, with the same configuration as your production app, and creating a _draft_ {% data variables.product.prodname_marketplace %} listing that you can use for testing. The draft {% data variables.product.prodname_marketplace %} listing allows you to test changes without affecting the active users of your production app. You will never have to submit your development {% data variables.product.prodname_marketplace %} listing, since you will only use it for testing.
|
||||
|
||||
@@ -29,16 +29,16 @@ Do not make test purchases with an app that is live in {% data variables.product
|
||||
|
||||
{% endwarning %}
|
||||
|
||||
#### Simulating Marketplace purchase events
|
||||
### Simulating Marketplace purchase events
|
||||
|
||||
Your testing scenarios may require setting up listing plans that offer free trials and switching between free and paid subscriptions. Because downgrades and cancellations don't take effect until the next billing cycle, GitHub provides a developer-only feature to "Apply Pending Change" to force `changed` and `cancelled` plan actions to take effect immediately. You can access **Apply Pending Change** for apps with _draft_ Marketplace listings in https://github.com/settings/billing#pending-cycle:
|
||||
|
||||
|
||||
|
||||
### Testing APIs
|
||||
## Testing APIs
|
||||
|
||||
For most {% data variables.product.prodname_marketplace %} API endpoints, we also provide stubbed API endpoints that return hard-coded, fake data you can use for testing. To receive stubbed data, you must specify stubbed URLs, which include `/stubbed` in the route (for example, `/user/marketplace_purchases/stubbed`). For a list of endpoints that support this stubbed-data approach, see [{% data variables.product.prodname_marketplace %} endpoints](/rest/reference/apps#github-marketplace).
|
||||
|
||||
### Testing webhooks
|
||||
## Testing webhooks
|
||||
|
||||
GitHub provides tools for testing your deployed payloads. For more information, see "[Testing webhooks](/webhooks/testing/)."
|
||||
|
||||
@@ -11,7 +11,7 @@ versions:
|
||||
topics:
|
||||
- Marketplace
|
||||
---
|
||||
### {% data variables.product.prodname_marketplace %} purchase webhook payload
|
||||
## {% data variables.product.prodname_marketplace %} purchase webhook payload
|
||||
|
||||
Webhooks `POST` requests have special headers. See "[Webhook delivery headers](/webhooks/event-payloads/#delivery-headers)" for more details. GitHub doesn't resend failed delivery attempts. Ensure your app can receive all webhook payloads sent by GitHub.
|
||||
|
||||
@@ -57,17 +57,17 @@ Key | Type | Description
|
||||
|
||||
<br/>
|
||||
|
||||
#### Example webhook payload for a `purchased` event
|
||||
### Example webhook payload for a `purchased` event
|
||||
This example provides the `purchased` event payload.
|
||||
|
||||
{{ webhookPayloadsForCurrentVersion.marketplace_purchase.purchased }}
|
||||
|
||||
#### Example webhook payload for a `changed` event
|
||||
### Example webhook payload for a `changed` event
|
||||
|
||||
Changes in a plan include upgrades and downgrades. This example represents the `changed`,`pending_change`, and `pending_change_cancelled` event payloads. The action identifies which of these three events has occurred.
|
||||
|
||||
{{ webhookPayloadsForCurrentVersion.marketplace_purchase.changed }}
|
||||
|
||||
#### Example webhook payload for a `cancelled` event
|
||||
### Example webhook payload for a `cancelled` event
|
||||
|
||||
{{ webhookPayloadsForCurrentVersion.marketplace_purchase.cancelled }}
|
||||
|
||||
Reference in New Issue
Block a user