diff --git a/docs/change-log/2025-07-10-clickable-links-and-customizable-statuses-in-activities.md b/docs/change-log/2025-07-10-clickable-links-and-customizable-statuses-in-activities.md new file mode 100644 index 0000000000..4f24f84efd --- /dev/null +++ b/docs/change-log/2025-07-10-clickable-links-and-customizable-statuses-in-activities.md @@ -0,0 +1,14 @@ +--- +title: "Clickable Links and Customizable Statuses in Activities" +date: "2025-07-10" +topics: +- "Activities" +- "Discord Social SDK" +- "Embedded App SDK" +--- + +We've added new functionality to Rich Presences to give users of your application a more interactive and flexible experience. There are two big changes as part of this: +- You can now add clickable links to the state text, details text, large image & small image +- You can now choose which field (name, state, or details) is used in users' status text (e.x. instead of "Listening to MyMusic" you can now have your status text show "Listening to Rick Astley") + +All of these new fields are documented on the [Activity Object](/docs/events/gateway-events#activity-object) section of Gateway Events. \ No newline at end of file diff --git a/docs/developer-tools/embedded-app-sdk.mdx b/docs/developer-tools/embedded-app-sdk.mdx index c127d99903..2798ef9cd8 100644 --- a/docs/developer-tools/embedded-app-sdk.mdx +++ b/docs/developer-tools/embedded-app-sdk.mdx @@ -1143,7 +1143,9 @@ Coming soon! Not available during Developer Preview | timestamps? | [Timestamp](/docs/developer-tools/embedded-app-sdk#timestamp) \| null | | application_id? | string \| null | | details? | string \| null | +| details_url? | string \| null | | state? | string \| null | +| state_url? | string \| null | | emoji? | [Emoji](/docs/developer-tools/embedded-app-sdk#emoji) \| null | | party? | [Party](/docs/developer-tools/embedded-app-sdk#party) \| null | | assets? | [Assets](/docs/developer-tools/embedded-app-sdk#assets) \| null | @@ -1157,8 +1159,10 @@ Coming soon! Not available during Developer Preview |--------------|----------------| | large_image? | string \| null | | large_text? | string \| null | +| large_url? | string \| null | | small_image? | string \| null | | small_text? | string \| null | +| small_url? | string \| null | #### Application diff --git a/docs/discord-social-sdk/development-guides/setting-rich-presence.mdx b/docs/discord-social-sdk/development-guides/setting-rich-presence.mdx index 53e1c05e6a..c61ff8247b 100644 --- a/docs/discord-social-sdk/development-guides/setting-rich-presence.mdx +++ b/docs/discord-social-sdk/development-guides/setting-rich-presence.mdx @@ -200,6 +200,46 @@ See the `ActivityGamePlatforms` enum for all supported platforms. --- +## Setting Field URLs + +You can set URLs for `details`, `state`, `assets.large_image` and `assets.small_image` in Rich Presence. When present, these URLs will make the corresponding image/text into clickable links. + +```cpp +activity.SetState("Playing on Mainframe"); +activity.SetStateUrl("https://example.com/maps/mainframe"); +activity.SetDetails("Rank #1337 in global leaderboard"); +activity.SetDetailsUrl("https://example.com/leaderboard/global"); + +discordpp::ActivityAssets assets; +assets.SetLargeImage("map-mainframe"); +assets.SetLargeText("Mainframe"); +assets.SetLargeUrl("https://example.com/maps/mainframe"); +assets.SetSmallImage("tank-avatar"); +assets.SetSmallText("Tank"); +assets.SetSmallUrl("https://example.com/classes/tank"); + +activity.SetAssets(assets); +``` + +--- + +## Configuring Status Text + +By default, Rich Presence will display the game's name in the user's status text. You can override this behavior by setting a status display type. + +```cpp +// uses the game's name in the status text (default) +activity.SetStatusDisplayType(discordpp::StatusDisplayTypes::Name); + +// uses the activity's state field in the status text +activity.SetStatusDisplayType(discordpp::StatusDisplayTypes::State); + +// uses the activity's details field in the status text +activity.SetStatusDisplayType(discordpp::StatusDisplayTypes::Details); +``` + +--- + ## Next Steps Now that you've set up Rich Presence, you might want to explore: diff --git a/docs/events/gateway-events.mdx b/docs/events/gateway-events.mdx index d46320ede7..8ca64dd26e 100644 --- a/docs/events/gateway-events.mdx +++ b/docs/events/gateway-events.mdx @@ -1133,23 +1133,26 @@ Active sessions are indicated with an "online", "idle", or "dnd" string per plat ###### Activity Structure -| Field | Type | Description | -|-----------------|--------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------| -| name | string | Activity's name | -| type | integer | [Activity type](/docs/events/gateway-events#activity-object-activity-types) | -| url? | ?string | Stream URL, is validated when type is 1 | -| created_at | integer | Unix timestamp (in milliseconds) of when the activity was added to the user's session | -| timestamps? | [timestamps](/docs/events/gateway-events#activity-object-activity-timestamps) object | Unix timestamps for start and/or end of the game | -| application_id? | snowflake | Application ID for the game | -| details? | ?string | What the player is currently doing | -| state? | ?string | User's current party status, or text used for a custom status | -| emoji? | ?[emoji](/docs/events/gateway-events#activity-object-activity-emoji) object | Emoji used for a custom status | -| party? | [party](/docs/events/gateway-events#activity-object-activity-party) object | Information for the current party of the player | -| assets? | [assets](/docs/events/gateway-events#activity-object-activity-assets) object | Images for the presence and their hover texts | -| secrets? | [secrets](/docs/events/gateway-events#activity-object-activity-secrets) object | Secrets for Rich Presence joining and spectating | -| instance? | boolean | Whether or not the activity is an instanced game session | -| flags? | integer | [Activity flags](/docs/events/gateway-events#activity-object-activity-flags) `OR`d together, describes what the payload includes | -| buttons? | array of [buttons](/docs/events/gateway-events#activity-object-activity-buttons) | Custom buttons shown in the Rich Presence (max 2) | +| Field | Type | Description | +|----------------------|--------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| +| name | string | Activity's name | +| type | integer | [Activity type](/docs/events/gateway-events#activity-object-activity-types) | +| url? | ?string | Stream URL, is validated when type is 1 | +| created_at | integer | Unix timestamp (in milliseconds) of when the activity was added to the user's session | +| timestamps? | [timestamps](/docs/events/gateway-events#activity-object-activity-timestamps) object | Unix timestamps for start and/or end of the game | +| application_id? | snowflake | Application ID for the game | +| status_display_type? | ?integer | [Status display type](/docs/events/gateway-events#activity-object-status-display-types); controls which field is displayed in the user's status text | +| details? | ?string | What the player is currently doing | +| details_url? | ?string | URL that is linked when clicking on the details text | +| state? | ?string | User's current party status, or text used for a custom status | +| state_url? | ?string | URL that is linked when clicking on the state text | +| emoji? | ?[emoji](/docs/events/gateway-events#activity-object-activity-emoji) object | Emoji used for a custom status | +| party? | [party](/docs/events/gateway-events#activity-object-activity-party) object | Information for the current party of the player | +| assets? | [assets](/docs/events/gateway-events#activity-object-activity-assets) object | Images for the presence and their hover texts | +| secrets? | [secrets](/docs/events/gateway-events#activity-object-activity-secrets) object | Secrets for Rich Presence joining and spectating | +| instance? | boolean | Whether or not the activity is an instanced game session | +| flags? | integer | [Activity flags](/docs/events/gateway-events#activity-object-activity-flags) `OR`d together, describes what the payload includes | +| buttons? | array of [buttons](/docs/events/gateway-events#activity-object-activity-buttons) | Custom buttons shown in the Rich Presence (max 2) | :::info Bot users are only able to set `name`, `state`, `type`, and `url`. @@ -1166,8 +1169,16 @@ Bot users are only able to set `name`, `state`, `type`, and `url`. | 4 | Custom | `{emoji}` `{state}` | ":smiley: I am cool" | | 5 | Competing | Competing in `{name}` | "Competing in Arena World Champions" | +###### Status Display Types + +| ID | Name | Example | +|----|---------|----------------------------------------| +| 0 | Name | "Listening to Spotify" | +| 1 | State | "Listening to Rick Astley" | +| 2 | Details | "Listening to Never Gonna Give You Up" | + :::info -The streaming type currently only supports Twitch and YouTube. Only `https://twitch.tv/` and `https://youtube.com/` urls will work. +This applies to all activity types. "Listening" was used to serve as a consistent example of what the different fields might be used for. ::: ###### Activity Timestamps @@ -1202,8 +1213,10 @@ For Listening and Watching activities, you can include both start and end timest |--------------|--------|----------------------------------------------------------------------------------------------| | large_image? | string | See [Activity Asset Image](/docs/events/gateway-events#activity-object-activity-asset-image) | | large_text? | string | Text displayed when hovering over the large image of the activity | +| large_url? | string | URL that is linked when clicking on the large image | | small_image? | string | See [Activity Asset Image](/docs/events/gateway-events#activity-object-activity-asset-image) | | small_text? | string | Text displayed when hovering over the small image of the activity | +| small_url? | string | URL that is linked when clicking on the small image | ###### Activity Asset Image diff --git a/docs/topics/rpc.md b/docs/topics/rpc.md index 64b0608eee..bd9f3cb4ae 100644 --- a/docs/topics/rpc.md +++ b/docs/topics/rpc.md @@ -1004,7 +1004,9 @@ When using `SET_ACTIVITY`, the `activity` object is limited to a `type` of Playi "pid": 9999, "activity": { "state": "In a Group", + "state_url": "https://example.com/groups/50335231-9d9d-4ebd-873b-984787ee4d1d", "details": "Competitive | In a Match", + "details_url": "https://example.com/matches/42340203-2f25-4534-8ff6-2a6509e81207", "timestamps": { "start": time(nullptr), "end": time(nullptr) + (60 * 5 + 23) @@ -1012,8 +1014,10 @@ When using `SET_ACTIVITY`, the `activity` object is limited to a `type` of Playi "assets": { "large_image": "numbani_map", "large_text": "Numbani", + "large_url": "https://example.wiki/maps/Numbani", "small_image": "pharah_profile", - "small_text": "Pharah" + "small_text": "Pharah", + "small_url": "https://example.wiki/characters/Pharah" }, "party": { "id": GameEngine.GetPartyId(),