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.

Sign up for GitHub

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

Adds premium interaction docs #6875

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
ef23d7c
Adds premium interaction docs
goatslacker May 16, 2024
226dacb
Update docs/interactions/Message_Components.md
goatslacker May 16, 2024
2f89235
fix tables
goatslacker May 16, 2024
8588250
Revert rm whitespace
goatslacker May 16, 2024
be2df07
disallows customizable label for premium buttons
goatslacker May 28, 2024
9453add
Update docs/interactions/Message_Components.md
goatslacker May 29, 2024
d247d1d
add some button design guidelines
goatslacker Jun 8, 2024
2461165
Update docs/interactions/Message_Components.md
goatslacker Jun 13, 2024
7e243af
Update docs/interactions/Message_Components.md
goatslacker Jun 13, 2024
770e4c3
Update docs/Change_Log.md
colinloretz Jun 14, 2024
a0dbb41
Update docs/Change_Log.md
colinloretz Jun 14, 2024
769b87b
Update docs/interactions/Receiving_and_Responding.md
colinloretz Jun 14, 2024
bfbc69b
Update docs/interactions/Message_Components.md
colinloretz Jun 14, 2024
927251f
New button styles image
goatslacker Jun 14, 2024
5128103
Merge branch 'main' into joshperez/premium-interactions
goatslacker Jun 14, 2024
a84b4f4
fix tables
goatslacker Jun 14, 2024
1fcf20c
fix links
goatslacker Jun 14, 2024
43cfafa
fix tables (again)
goatslacker Jun 14, 2024
42254b5
update buttons img
goatslacker Jun 14, 2024
b282626
Updated changelog. Added deep link docs
colinloretz Jun 17, 2024
0b7c265
fix backlink
colinloretz Jun 17, 2024
cdc2b67
Updated button-styles.png
colinloretz Jun 17, 2024
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
16 changes: 16 additions & 0 deletions docs/Change_Log.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,21 @@
# Change Log

## Premium Interactions

#### May 16, 2024

**Premium Apps: New Premium Style for MessageComponentType.BUTTON**
colinloretz marked this conversation as resolved.
Show resolved Hide resolved

This button is to be used with `sku_id` which points to an active SKU. This allows developers to customize their premium experience.
colinloretz marked this conversation as resolved.
Show resolved Hide resolved

Learn more about using [Buttons](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/buttons).

**Deprecates Interaction Response Type 10**

The `PREMIUM_REQUIRED` 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 premium buttons.

Learn more about [Premium Interactions](#DOCS_MONETIZATION_APP_SUBSCRIPTIONS/gating-premium-interactions).

## Premium Apps: One-Time Purchases and Store

#### April 24, 2024
Expand Down
20 changes: 11 additions & 9 deletions docs/interactions/Message_Components.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,15 +90,16 @@ 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, only available when using [ButtonStyle.Premium](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/button-object-button-styles) |
colinloretz marked this conversation as resolved.
Show resolved Hide resolved
| 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.

Expand All @@ -115,6 +116,7 @@ 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 | gradient | `sku_id` |
goatslacker marked this conversation as resolved.
Show resolved Hide resolved

![An image showing the different button styles](button-styles.png)

Expand Down
22 changes: 11 additions & 11 deletions docs/interactions/Receiving_and_Responding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -209,22 +209,22 @@ There are a number of ways you can respond to an interaction:

###### Interaction Callback Type

| Name | Value | Description |
|-----------------------------------------|-------|---------------------------------------------------------------------------------------------------------------|
| PONG | 1 | ACK a `Ping` |
| CHANNEL_MESSAGE_WITH_SOURCE | 4 | respond to an interaction with a message |
| DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE | 5 | ACK an interaction and edit a response later, the user sees a loading state |
| DEFERRED_UPDATE_MESSAGE\* | 6 | for components, ACK an interaction and edit the original message later; the user does not see a loading state |
| UPDATE_MESSAGE\* | 7 | for components, edit the message the component was attached to |
| APPLICATION_COMMAND_AUTOCOMPLETE_RESULT | 8 | respond to an autocomplete interaction with suggested choices |
| MODAL\*\* | 9 | respond to an interaction with a popup modal |
| PREMIUM_REQUIRED\*\*\* | 10 | respond to an interaction with an upgrade button, only available for apps with monetization enabled |
| Name | Value | Description |
|-----------------------------------------|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
| PONG | 1 | ACK a `Ping` |
| CHANNEL_MESSAGE_WITH_SOURCE | 4 | respond to an interaction with a message |
| DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE | 5 | ACK an interaction and edit a response later, the user sees a loading state |
| DEFERRED_UPDATE_MESSAGE\* | 6 | for components, ACK an interaction and edit the original message later; the user does not see a loading state |
| UPDATE_MESSAGE\* | 7 | for components, edit the message the component was attached to |
| APPLICATION_COMMAND_AUTOCOMPLETE_RESULT | 8 | respond to an autocomplete interaction with suggested choices |
| MODAL\*\* | 9 | respond to an interaction with a popup modal |
| PREMIUM_REQUIRED\*\*\* | 10 | [Deprecated](#DOCS_CHANGE_LOG/premium-interactions). respond to an interaction with an upgrade button, only available for apps with monetization enabled |
colinloretz marked this conversation as resolved.
Show resolved Hide resolved

\* Only valid for [component-based](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/) interactions

\*\* Not available for `MODAL_SUBMIT` and `PING` interactions.

\*\*\* Not available for `APPLICATION_COMMAND_AUTOCOMPLETE` and `PING` interactions.
\*\*\* This response type is deprecated. Learn more about [migrating to premium buttons](#DOCS_MONETIZATION_APP_SUBSCRIPTIONS/gating-premium-interactions). Not available for `APPLICATION_COMMAND_AUTOCOMPLETE` and `PING` interactions.
colinloretz marked this conversation as resolved.
Show resolved Hide resolved

###### Interaction Callback Data Structure

Expand Down
29 changes: 28 additions & 1 deletion docs/monetization/App_Subscriptions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,33 @@ When a user subscribes to your app, there are a few things you will need to impl

### Gating Premium Interactions

Each interaction payload includes an `entitlements` field containing an array of full [entitlement objects](#DOCS_MONETIZATION_ENTITLEMENTS/entitlement-object). You can use this field to determine if the user or guild is subscribed to your app. If the user or guild is not subscribed and you wish to present them with a means to do so you can use a [button](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/buttons) with a [premium style](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/button-object-button-styles) and a `sku_id` attached. You may also use these buttons to present users with options to make a [One-Time Purchase](#DOCS_MONETIZATION_ONE-TIME_PURCHASES).
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This gets restated below, under Type 10 Interaction Response:

discord-api-docs/docs/monetization/App_Subscriptions.md

Lines 77 to 81 in 8588250

If someone is already subscribed, this command will show the upgrade prompt with a disabled upgrade button. In order to avoid this, your interaction handler should check to see if the user or guild has an active entitlement for your SKU.
Each interaction payload includes an `entitlements` field containing an array of full [entitlement objects](#DOCS_MONETIZATION_ENTITLEMENTS/entitlement-object).
You can use this field to determine if the user or guild is subscribed to your app.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah it's relevant in both cases.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah it's relevant in both cases.

it just seems redundant, since it's already started once here and then again under the sub header on the same page


```javascript
return new JsonResponse({
type: 4, // InteractionResponseType.CHANNEL_MESSAGE_WITH_SOURCE
data: {
content: "This command requires Nelly Premium! Upgrade now to get access to these features!",
components: [{
type: MessageComponentTypes.ACTION_ROW,
components: [
{
type: MessageComponentTypes.BUTTON,
style: 6, // ButtonStyleTypes.PREMIUM
skuId: '1234965026943668316',
label: 'Upgrade',
},
],
}]
},
});
```

#### Type 10 Interaction Response

> warn
> `PREMIUM_REQUIRED` type 10 interaction response is deprecated. Please use `ButtonStyle.PREMIUM` to handle purchases.

Interactions like [commands](#DOCS_INTERACTIONS_APPLICATION_COMMANDS) commonly respond to users with a message or modal response. If you'd like to make a command only available to users with a subscription, you can reply with a `PREMIUM_REQUIRED` interaction response `type: 10`. Users without a subscription will be prompted to upgrade when they attempt to use these commands.

```javascript
Expand Down Expand Up @@ -94,4 +121,4 @@ After checkout, you will have a live subscription that includes a `starts_at` an

Once an app has made its first $100 it will become eligible for payout. A review will be conducted and if everything looks good, your team will begin to receive payouts.

For more information, read the [Premium Apps Payouts](https://support-dev.discord.com/hc/articles/17299902720919) Help Center article.
For more information, read the [Premium Apps Payouts](https://support-dev.discord.com/hc/articles/17299902720919) Help Center article.