Adds premium interaction docs (discord#6875)

* Adds premium interaction docs * Update docs/interactions/Message_Components.md Co-authored-by: MCausc78 <[email protected]> * fix tables * Revert rm whitespace * disallows customizable label for premium buttons * Update docs/interactions/Message_Components.md Co-authored-by: codershiba <[email protected]> * add some button design guidelines * Update docs/interactions/Message_Components.md Co-authored-by: advaith <[email protected]> * Update docs/interactions/Message_Components.md Co-authored-by: Adrian Paschkowski <[email protected]> * Update docs/Change_Log.md Co-authored-by: val.le <[email protected]> * Update docs/Change_Log.md Co-authored-by: val.le <[email protected]> * Update docs/interactions/Receiving_and_Responding.md Co-authored-by: val.le <[email protected]> * Update docs/interactions/Message_Components.md Co-authored-by: val.le <[email protected]> * New button styles image * fix tables * fix links * fix tables (again) * update buttons img * Updated changelog. Added deep link docs * fix backlink * Updated button-styles.png --------- Co-authored-by: MCausc78 <[email protected]> Co-authored-by: codershiba <[email protected]> Co-authored-by: advaith <[email protected]> Co-authored-by: Adrian Paschkowski <[email protected]> Co-authored-by: Colin Loretz <[email protected]> Co-authored-by: val.le <[email protected]>
advaith1 · Jun 17, 2024 · 4853fbc · 4853fbc
1 parent 6e0e832
commit 4853fbc
Show file tree

Hide file tree

Showing 12 changed files with 145 additions and 33 deletions.
diff --git a/docs/Change_Log.md b/docs/Change_Log.md
@@ -1,5 +1,29 @@
 # Change Log
 
+## Premium Apps: New Premium Button Style & Deep Linking URL Schemes
+
+#### June 17, 2024
+
+**New Premium Button Style**
+
+Introduces a new `premium` [button style](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/button-object-button-styles) to be used with a `sku_id` which points to an active [SKU](#DOCS_MONETIZATION_SKUS/sku-object). This allows developers to customize their premium experience by returning specific subscription or one-time purchase products.
+
+Learn more about using [button components with interactions](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/buttons).
+
+> warn
+> This change deprecates Interaction Response Type 10
+
+The `PREMIUM_REQUIRED (10)` interaction response type is now deprecated in favor of using custom premium buttons. This will continue to function but may be eventually unsupported. It is recommended to migrate your bots to use the more flexible [premium button component](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/button-object-button-styles).
+
+Learn more about [gating features with premium interactions](#DOCS_MONETIZATION_APP_SUBSCRIPTIONS/gating-premium-interactions).
+
+**Deep Linking URL Schemes for SKUs and Store**
+
+Introduces two new url schemes for linking directly to the Application Directory. When these links are used in chat, they are rendered as rich embeds that users can interact with to launch an app's store or open a SKU detail modal.
+
+- New [Store URL Scheme](#DOCS_MONETIZATION_MANAGING_YOUR_STORE/linking-to-your-store): `https://discord.com/application-directory/:appID/store`
+- New [SKU URL Scheme](#DOCS_MONETIZATION_SKUS/linking-to-your-skus): `https://discord.com/application-directory/:appID/store/:skuID`
+
 ## Auto Moderation Member Profile Rule
 
 #### May 31, 2024
@@ -30,7 +54,7 @@ To explore these features, eligibility details, and how to enable monetization f
 
 The following were added to our public Monetization documentation with this update:
 
-- New [SKU Object Types](#DOCS_MONETIZATION_SKUS/sku-object-sku-types) 
+- New [SKU Object Types](#DOCS_MONETIZATION_SKUS/sku-object-sku-types)
 - New [Entitlement Object Types](#DOCS_MONETIZATION_ENTITLEMENTS/entitlement-object-entitlement-types)
 - [Consume an Entitlement](#DOCS_MONETIZATION_ENTITLEMENTS/consume-an-entitlement) API endpoint
 - `consumed` field on the [Entitlement](#DOCS_MONETIZATION_ENTITLEMENTS) resource
@@ -44,7 +68,7 @@ Update permissions necessary to modify the `flags` field when calling the [Modif
 
 #### April 2, 2024
 
-For apps with [Monetization](#DOCS_MONETIZATION_OVERVIEW) enabled, we have released the ability to export your SKU analytics to CSV. These exports allow you to use your preferred data tools to report on your premium offerings. 
+For apps with [Monetization](#DOCS_MONETIZATION_OVERVIEW) enabled, we have released the ability to export your SKU analytics to CSV. These exports allow you to use your preferred data tools to report on your premium offerings.
 
 You can find the export at the bottom of the `Monetization → Analytics` tab of your app to export data points such as `sales_count`, `sales_amount`, `sales_currencies`, `cancellation_count`, `refund_amount`, and `refund_count`, aggregated by each of your offerings for the selected month.
 
@@ -67,7 +91,7 @@ This change introduces new concepts and fields across the API that apps will now
 - [Installation context](#DOCS_RESOURCES_APPLICATION/installation-context) defines how an app was installed: to a user, a guild (server), or both. Currently, apps will default to only support the guild installation context, but the default may change in the future.
 - Commands can also support one or both installation contexts, with the default being the same as the app's supported installation context(s) at the time of command creation.
 - [Interaction context](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/interaction-contexts) defines where a command can be used in Discord—within guilds, DM with your app's bot user, and/or within group DMs and DMs other than with your app's bot user.
-- The installation flow for apps have been updated so users can select whether they want to install an app to their account or to a server. 
+- The installation flow for apps have been updated so users can select whether they want to install an app to their account or to a server.
 
 **API Fields:**
 - New `integration_types_config` field for [Applications](#DOCS_RESOURCES_APPLICATION/application-object) include the default scopes and permissions for app's supported installation contexts
@@ -135,7 +159,7 @@ To support added controls for expressions and events, new [permissions](#DOCS_TO
 - `CREATE_GUILD_EXPRESSIONS`: `1 << 43`
 - `CREATE_EVENTS`: `1 << 44`
 
-These allow for creating new expressions and events, as well as editing and deleting those created by the current user.  
+These allow for creating new expressions and events, as well as editing and deleting those created by the current user.
 
 > warn
 > These were rolled out in July 2023 to users and roles and have been added to our developer documentation but **are not yet available to app developers**. We will share an update here when these new permissions are available in your apps.
@@ -145,17 +169,17 @@ These allow for creating new expressions and events, as well as editing and dele
 
 #### What’s Happening?
 
-As outlined in [a blog post earlier this year](https://discord.com/blog/encryption-for-voice-and-video-on-discord), we are experimenting with end-to-end encryption (e2ee) for voice and video channels. 
+As outlined in [a blog post earlier this year](https://discord.com/blog/encryption-for-voice-and-video-on-discord), we are experimenting with end-to-end encryption (e2ee) for voice and video channels.
 
 End-to-end encryption is designed to only allow the participants in a call to decipher its contents. One of the protocols we’re experimenting with is called Messaging Layer Security, which we believe would allow us to deliver end-to-end encryption at scale. Intermediaries, including platforms like Discord, are unable to access the content of communications encrypted with end-to-end encryption.
 
 #### How do I prepare for the changes?
 
-During this testing phase, there is nothing developers need to do to support end-to-end encryption. Voice channels will automatically downgrade to documented, non-e2ee protocols when a bot user joins the channel. This is transparent to the connecting client but may result in a slight delay between establishing a connection and receiving audio. 
+During this testing phase, there is nothing developers need to do to support end-to-end encryption. Voice channels will automatically downgrade to documented, non-e2ee protocols when a bot user joins the channel. This is transparent to the connecting client but may result in a slight delay between establishing a connection and receiving audio.
 
 #### What is planned for the future?
 
-We will be continuing our testing and will share updates along with developer documentation and sample code once it is available. 
+We will be continuing our testing and will share updates along with developer documentation and sample code once it is available.
 
 Once this information is published, we will provide developers with a substantial timeframe to implement end-to-end encryption when interacting with voice and video.
 
@@ -179,7 +203,7 @@ Previously, some message edit interaction response actions would use the default
 ## Premium App Subscriptions Now Available in the EU and UK
 #### Oct 19, 2023
 
-Starting today, eligible developers based in EU and UK can now monetize their verified apps with App Subscriptions. [App Subscriptions](#DOCS_MONETIZATION_OVERVIEW) let you to charge your users for premium functionality with a recurring, monthly subscription. 
+Starting today, eligible developers based in EU and UK can now monetize their verified apps with App Subscriptions. [App Subscriptions](#DOCS_MONETIZATION_OVERVIEW) let you to charge your users for premium functionality with a recurring, monthly subscription.
 
 > info
 > New features for Premium App Subscriptions are documented in the [App Subscriptions overview](#DOCS_MONETIZATION_OVERVIEW) and in [the changelog for the previous App Subscriptions release](#DOCS_CHANGE_LOG/premium-app-subscriptions-available-in-the-us).
@@ -189,7 +213,7 @@ To learn more about eligibility details and how to enable monetization for your
 ## Global Rate Limit added to discordapp.com/*
 #### Oct 17, 2023
 
-We have added a global rate limit for API requests made to `discordapp.com/*` and may further restrict requests in the future. 
+We have added a global rate limit for API requests made to `discordapp.com/*` and may further restrict requests in the future.
 
 To limit impact on your app, please make sure you are making calls to `discord.com/*`.
 
@@ -203,7 +227,7 @@ Refer to the [API Reference](https://discord.com/developers/docs/reference) for
 ## Premium App Subscriptions Available in the US
 #### Sep 26, 2023
 
-Starting today, eligible US-based developers can monetize their verified apps with App Subscriptions. [App Subscriptions](#DOCS_MONETIZATION_OVERVIEW) let you to charge your users for premium functionality with a recurring, monthly subscription. 
+Starting today, eligible US-based developers can monetize their verified apps with App Subscriptions. [App Subscriptions](#DOCS_MONETIZATION_OVERVIEW) let you to charge your users for premium functionality with a recurring, monthly subscription.
 
 - Manage subscription SKUs in the Developer Portal
 - View monetization analytics in the Developer Portal
@@ -213,7 +237,7 @@ Starting today, eligible US-based developers can monetize their verified apps wi
   - [List Entitlements](#DOCS_MONETIZATION_ENTITLEMENTS/list-entitlements) `GET /applications/<application.id>/entitlements`
   - [Create Test Entitlement](#DOCS_MONETIZATION_ENTITLEMENTS/create-test-entitlement) `POST /applications/<application.id>/entitlements`
   - [Delete Test Entitlement](#DOCS_MONETIZATION_ENTITLEMENTS/delete-test-entitlement)  `DELETE /applications/<application.id>/entitlements/<entitlement.id>`
-- [Gateway Events](#DOCS_MONETIZATION_ENTITLEMENTS/gateway-events) for working with entitlements: `ENTITLEMENT_CREATE`, `ENTITLEMENT_UPDATE`, `ENTITLEMENT_DELETE` 
+- [Gateway Events](#DOCS_MONETIZATION_ENTITLEMENTS/gateway-events) for working with entitlements: `ENTITLEMENT_CREATE`, `ENTITLEMENT_UPDATE`, `ENTITLEMENT_DELETE`
 - New [`PREMIUM_REQUIRED (10)` interaction response type](#DOCS_MONETIZATION_ENTITLEMENTS/premiumrequired-interaction-response) is available to prompt users to upgrade
 - New `entitlements` field, which is an array of [entitlement](#DOCS_MONETIZATION_ENTITLEMENTS/) objects, available in interaction data payloads when [receiving and responding to interactions](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object-interaction-structure)
 

diff --git a/docs/interactions/Message_Components.md b/docs/interactions/Message_Components.md
@@ -90,21 +90,24 @@ Buttons are interactive components that render in messages. They can be clicked
 
 ###### Button Structure
 
-| Field      | Type                                                | Description                                                                         |
-|------------|-----------------------------------------------------|-------------------------------------------------------------------------------------|
-| type       | integer                                             | `2` for a button                                                                    |
-| style      | integer                                             | A [button style](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/button-object-button-styles) |
-| label?     | string                                              | Text that appears on the button; max 80 characters                                  |
-| emoji?     | partial [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) | `name`, `id`, and `animated`                                                        |
-| custom_id? | string                                              | Developer-defined identifier for the button; max 100 characters                     |
-| url?       | string                                              | URL for link-style buttons                                                          |
-| disabled?  | boolean                                             | Whether the button is disabled (defaults to `false`)                                |
+| Field      | Type                                                | Description                                                                                                             |
+|------------|-----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
+| type       | integer                                             | `2` for a button                                                                                                        |
+| style      | integer                                             | A [button style](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/button-object-button-styles)                                     |
+| label?     | string                                              | Text that appears on the button; max 80 characters                                                                      |
+| emoji?     | partial [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) | `name`, `id`, and `animated`                                                                                            |
+| custom_id? | string                                              | Developer-defined identifier for the button; max 100 characters                                                         |
+| sku_id?    | snowflake                                           | Identifier for a purchasable [SKU](#DOCS_MONETIZATION_SKUS/sku-object), only available when using premium-style buttons |
+| url?       | string                                              | URL for link-style buttons                                                                                              |
+| disabled?  | boolean                                             | Whether the button is disabled (defaults to `false`)                                                                    |
 
 Buttons come in a variety of styles to convey different types of actions. These styles also define what fields are valid for a button.
 
-- Non-link buttons **must** have a `custom_id`, and cannot have a `url`
+- Non-link and Non-premium buttons **must** have a `custom_id`, and cannot have a `url` or a `sku_id`.
 - Link buttons **must** have a `url`, and cannot have a `custom_id`
 - Link buttons do not send an [interaction](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object) to your app when clicked
+- Premium buttons **must** contain a `sku_id`, and cannot have a `custom_id`, `label`, `url`, or `emoji`.
+- Premium buttons do not send an [interaction](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object) to your app when clicked
 
 ###### Button Styles
 
@@ -115,11 +118,46 @@ Buttons come in a variety of styles to convey different types of actions. These
 | Success   | 3     | green                    | `custom_id`    |
 | Danger    | 4     | red                      | `custom_id`    |
 | Link      | 5     | grey, navigates to a URL | `url`          |
+| Premium   | 6     | blurple                  | `sku_id`       |
 
 ![An image showing the different button styles](button-styles.png)
 
 When a user clicks on a button, your app will receive an [interaction](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object) including the message the button was on:
 
+### Button Design Guidelines
+
+###### General Button copy
+
+- 34 characters max with icon or emoji.
+- 38 characters max without icon or emoji.
+- Keep text concise and to the point.
+- Use clear and easily understandable language. Avoid jargon or overly technical terms.
+- Use verbs that indicate the outcome of the action.
+- Maintain consistency in language and tone across buttons.
+- Anticipate the need for translation, test for expansion or contraction in different languages.
+
+###### Multiple Buttons
+
+Use different button styles to create a hierarchy. Use only one `Primary` button per group.
+
+![Example showing one primary button per button group](multiple-buttons-example-1.png)
+
+If there are multiple buttons of equal significance, use the `Secondary` button style for all buttons
+
+![Example showing multiple buttons in a group with equal significance](multiple-buttons-example-2.png)
+
+###### Premium Buttons
+
+Premium buttons will automatically have:
+
+- Shop Icon
+- Blurple Background
+- SKU name
+- SKU price
+- 34 character max for this button. Longer titles will be truncated
+
+![A premium button](premium-button.png)
+
 ### Component Interaction Object
 
 ###### Sample Component Interaction