Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adds premium interaction docs #6875

Merged
merged 22 commits into from
Jun 17, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 35 additions & 11 deletions docs/Change_Log.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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.

Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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.

Expand All @@ -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.
goatslacker marked this conversation as resolved.
Show resolved Hide resolved

> 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).
Expand All @@ -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/*`.

Expand All @@ -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
Expand All @@ -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)

Expand Down
58 changes: 48 additions & 10 deletions docs/interactions/Message_Components.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down
Loading