discordpp::Activity Class Reference

Detailed Description

An Activity represents one "thing" a user is doing on Discord and is part of their rich presence.

Additional information is located on the Discord Developer Portal:

• https://discord.com/developers/docs/rich-presence/overview
• https://discord.com/developers/docs/developer-tools/game-sdk#activities
• https://discord.com/developers/docs/rich-presence/best-practices

While RichPresence supports multiple types of activities, the only activity type that is really relevant for the SDK is ActivityTypes::Playing. Additionally, the SDK will only expose Activities that are associated with the current game (or application). So for example, a field like name below, will always be set to the current game's name from the view of the SDK.

Customization

When an activity shows up on Discord, it will look something like this:

1. Playing "game name"
2. Capture the flag | 2 - 1
3. In a group (2 of 3)

You can control how lines 2 and 3 are rendered in Discord, here's the breakdown:

• Line 1, Playing "game name" is powered by the name of your game (or application) on Discord.
• Line 2, Capture the flag | 2 - 1 is powered by the details field in the activity, and this should generally try to describe what the player is currently doing. You can even include dynamic data such as a match score here.
• Line 3, In a group (2 of 3) describes the party the player is in. "Party" is used to refer to a group of players in a shared context, such as a lobby, server, team, etc. The first half, In a group is powered by the state field in the activity, and the second half, (2 of 3) is powered by the party field in the activity and describes how many people are in the current party and how big the party can get.

This diagram visually shows the field mapping:

Rich presence field diagram

You can also specify up to two custom buttons to display on the rich presence. These buttons will open the URL in the user's default browser.

discordpp::ActivityButton button;
button.SetLabel("Button 1");
button.SetUrl("https://example.com");
activity.AddButton(button);

Invites / Joinable Activities

Other users can be invited to join the current player's activity (or request to join it too), but that does require certain fields to be set:

1. ActivityParty must be set and have a non-empty ActivityParty::Id field. All users in the party should set the same id field too!
2. ActivityParty must specify the size of the group, and there must be room in the group for another person to join.
3. ActivitySecrets::Join must be set to a non-empty string. The join secret is only shared with users who are accepted into the party by an existing member, so it is truly a secret. You can use this so that when the user is accepted your game knows how to join them to the party. For example it could be an internal game ID, or a Discord lobby ID/secret that the client could join.

There is additional information about game invites here: https://support.discord.com/hc/en-us/articles/115001557452-Game-Invites

Mobile Invites

Activity invites are handled via a deep link. To enable users to join your game via an invite in the Discord client, you must do two things:

1. Set your deep link URL in the Discord developer portal. This will be available on the General tab of your application once Social Layer integration is enabled for your app.
2. Set the desired supported platforms when reporting the activity info in your rich presence, e.g.:

activity.SetSupportedPlatforms(
    ActivityGamePlatforms.Desktop |
    ActivityGamePlatforms.IOS |
    ActivityGamePlatforms.Android);

When the user accepts the invite, the Discord client will open: [your url]/_discord/join?secret=[the join secret you set]

Example Invites Flow

If you are using Discord lobbies for your game, a neat flow would look like this:

• When a user starts playing the game, they create a lobby with a random secret string, using Client::CreateOrJoinLobby
• That user publishes their RichPresence with the join secret set to the lobby secret, along with party size information
• Another use can then see that RichPresence on Discord and join off of it
• Once accepted the new user receives the join secret and their client can call CreateOrJoinLobby(joinSecret) to join the lobby
• Finally the original user can notice that the lobby membership has changed and so they publish a new RichPresence update containing the updating party size information.

Invites Code Example

// User A
// 1. Create a lobby with secret
std::string lobbySecret = "foo";
client->CreateOrJoinLobby(lobbySecret, [=](discordpp::ClientResult result, uint64_t lobbyId) {
    // 2. Update rich presence with join secret
    discordpp::Activity activity{};
    // set name, state, party size ...
    discordpp::ActivitySecrets secrets{};
    secrets.SetJoin(lobbySecret);
    activity.SetSecrets(secrets);
    client->UpdateRichPresence(std::move(activity), [](discordpp::ClientResult result) {});
});
// 3. Some time later, send an invite
client->SendActivityInvite(USER_B_ID, "come play with me", [](auto result) {});
 
// User B
// 4. Monitor for new invites
client->SetActivityInviteCallback([client](auto invite) {
    // 5. When an invite is received, ask the user if they want to accept it.
    // If they choose to do so then go ahead and invoke AcceptActivityInvite
    client->AcceptActivityInvite(invite,
        [client](discordpp::ClientResult result, std::string secret) {
        if (result.Successful()) {
            // 5. Join the lobby using the joinSecret
            client->CreateOrJoinLobby(secret, [](discordpp::ClientResult result, uint64_t
            lobbyId) {
                // Successfully joined lobby!
            });
        }
    });
});

Join Requests Code Example

Users can also request to join each others parties. This code snippet shows how that flow might look:

// User A
// 1. Create a lobby with secret
std::string lobbySecret = "foo";
client->CreateOrJoinLobby(lobbySecret, [=](discordpp::ClientResult result, uint64_t lobbyId) {
    // 2. Update rich presence with join secret
    discordpp::Activity activity{};
    // set name, state, party size ...
    discordpp::ActivitySecrets secrets{};
    secrets.SetJoin(lobbySecret);
    activity.SetSecrets(secrets);
    client->UpdateRichPresence(std::move(activity), [](discordpp::ClientResult result) {});
});
 
// User B
// 3. Request to join User A's party
client->SendActivityJoinRequest(USER_A_ID, [](auto result) {});
 
// User A
// Monitor for new invites:
client->SetActivityInviteCreatedCallback([client](auto invite) {
    // 5. The game can now show that User A has received a request to join their party
    // If User A is ok with that, they can reply back:
    // Note: invite.type will be ActivityActionTypes::JoinRequest in this example
    client->SendActivityJoinRequestReply(invite, [](auto result) {});
});
 
// User B
// 6. Same as before, user B can monitor for invites
client->SetActivityInviteCreatedCallback([client](auto invite) {
    // 7. When an invite is received, ask the user if they want to accept it.
    // If they choose to do so then go ahead and invoke AcceptActivityInvite
    client->AcceptActivityInvite(invite,
        [client](discordpp::ClientResult result, std::string secret) {
        if (result.Successful()) {
            // 5. Join the lobby using the joinSecret
            client->CreateOrJoinLobby(secret, [](auto result, uint64_t lobbyId) {
                // Successfully joined lobby!
            });
        }
    });
});

Public Member Functions
	Activity (Activity &&other) noexcept
	Move constructor for Activity.
Activity &	operator= (Activity &&other) noexcept
	Move assignment operator for Activity.
	operator bool () const
	Returns true if the instance contains a valid object.
	Activity (const Activity &arg0)
	Copy constructor for Activity.
Activity &	operator= (const Activity &arg0)
	Copy assignment operator for Activity.
void	AddButton (discordpp::ActivityButton button)
	Adds a custom button to the rich presence.
bool	Equals (discordpp::Activity other) const
	Compares each field of the Activity struct for equality.
std::vector< discordpp::ActivityButton >	GetButtons () const
	Returns the custom buttons for the rich presence.
std::string	Name () const
	The name of the game or application that the activity is associated with.
void	SetName (std::string Name)
	Setter for Activity::Name.
discordpp::ActivityTypes	Type () const
	The type of activity this is.
void	SetType (discordpp::ActivityTypes Type)
	Setter for Activity::Type.
std::optional< std::string >	State () const
	The state of the party for this activity.
void	SetState (std::optional< std::string > State)
	Setter for Activity::State.
std::optional< std::string >	Details () const
	The state of the what the user is doing for this activity.
void	SetDetails (std::optional< std::string > Details)
	Setter for Activity::Details.
std::optional< uint64_t >	ApplicationId () const
	The application ID of the game that the activity is associated with.
void	SetApplicationId (std::optional< uint64_t > ApplicationId)
	Setter for Activity::ApplicationId.
std::optional< discordpp::ActivityAssets >	Assets () const
	Images used to customize how the Activity is displayed in the Discord client.
void	SetAssets (std::optional< discordpp::ActivityAssets > Assets)
	Setter for Activity::Assets.
std::optional< discordpp::ActivityTimestamps >	Timestamps () const
	The timestamps struct can be used to render either:
void	SetTimestamps (std::optional< discordpp::ActivityTimestamps > Timestamps)
	Setter for Activity::Timestamps.
std::optional< discordpp::ActivityParty >	Party () const
	The party struct is used to indicate the size and members of the people the current user is playing with.
void	SetParty (std::optional< discordpp::ActivityParty > Party)
	Setter for Activity::Party.
std::optional< discordpp::ActivitySecrets >	Secrets () const
	The secrets struct is used in combination with the party struct to make an Activity joinable.
void	SetSecrets (std::optional< discordpp::ActivitySecrets > Secrets)
	Setter for Activity::Secrets.
discordpp::ActivityGamePlatforms	SupportedPlatforms () const
	If an activity is joinable, but only on certain platforms, this field can be used to indicate which platforms the activity is joinable on. For example if a game is available on both PC and Mobile, but PC users cannot join Mobile users and vice versa, this field can be used so that an activity only shows as joinable on Discord if the user is on the appropriate platform.
void	SetSupportedPlatforms (discordpp::ActivityGamePlatforms SupportedPlatforms)
	Setter for Activity::SupportedPlatforms.

Static Public Attributes
static const Activity	nullobj
	Uninitialized instance of Activity.

Constructor & Destructor Documentation

Activity() [1/2]

discordpp::Activity::Activity ( Activity && other )

noexcept

Move constructor for Activity.

Activity() [2/2]

discordpp::Activity::Activity

(

const Activity &

arg0

)

Copy constructor for Activity.

Member Function Documentation

AddButton()

void discordpp::Activity::AddButton

(

discordpp::ActivityButton

button

)

Adds a custom button to the rich presence.

ApplicationId()

std::optional< uint64_t > discordpp::Activity::ApplicationId

(

)

const

The application ID of the game that the activity is associated with.

This field cannot be set by the SDK, and will always be the application ID of the current game.

Assets()

std::optional< discordpp::ActivityAssets > discordpp::Activity::Assets

(

)

const

Images used to customize how the Activity is displayed in the Discord client.

Details()

std::optional< std::string > discordpp::Activity::Details

(

)

const

The state of the what the user is doing for this activity.

See the docs on the Activity struct for more info. If specified, must be a string between 2 and 128 characters.

Equals()

bool discordpp::Activity::Equals

(

discordpp::Activity

other

)

const

Compares each field of the Activity struct for equality.

GetButtons()

std::vector< discordpp::ActivityButton > discordpp::Activity::GetButtons

(

)

const

Returns the custom buttons for the rich presence.

Name()

std::string discordpp::Activity::Name

(

)

const

The name of the game or application that the activity is associated with.

This field cannot be set by the SDK, and will always be the name of the current game.

operator bool()

discordpp::Activity::operator bool ( ) const

inline

Returns true if the instance contains a valid object.

operator=() [1/2]

Activity & discordpp::Activity::operator= ( Activity && other )

noexcept

Move assignment operator for Activity.

operator=() [2/2]

Activity & discordpp::Activity::operator=

(

const Activity &

arg0

)

Copy assignment operator for Activity.

Party()

std::optional< discordpp::ActivityParty > discordpp::Activity::Party

(

)

const

The party struct is used to indicate the size and members of the people the current user is playing with.

Secrets()

std::optional< discordpp::ActivitySecrets > discordpp::Activity::Secrets

(

)

const

The secrets struct is used in combination with the party struct to make an Activity joinable.

SetApplicationId()

void discordpp::Activity::SetApplicationId

(

std::optional< uint64_t >

ApplicationId

)

Setter for Activity::ApplicationId.

SetAssets()

void discordpp::Activity::SetAssets

(

std::optional< discordpp::ActivityAssets >

Assets

)

Setter for Activity::Assets.

SetDetails()

void discordpp::Activity::SetDetails

(

std::optional< std::string >

Details

)

Setter for Activity::Details.

SetName()

void discordpp::Activity::SetName

(

std::string

Name

)

Setter for Activity::Name.

SetParty()

void discordpp::Activity::SetParty

(

std::optional< discordpp::ActivityParty >

Party

)

Setter for Activity::Party.

SetSecrets()

void discordpp::Activity::SetSecrets

(

std::optional< discordpp::ActivitySecrets >

Secrets

)

Setter for Activity::Secrets.

SetState()

void discordpp::Activity::SetState

(

std::optional< std::string >

State

)

Setter for Activity::State.

SetSupportedPlatforms()

void discordpp::Activity::SetSupportedPlatforms

(

discordpp::ActivityGamePlatforms

SupportedPlatforms

)

Setter for Activity::SupportedPlatforms.

SetTimestamps()

void discordpp::Activity::SetTimestamps

(

std::optional< discordpp::ActivityTimestamps >

Timestamps

)

Setter for Activity::Timestamps.

SetType()

void discordpp::Activity::SetType

(

discordpp::ActivityTypes

Type

)

Setter for Activity::Type.

State()

std::optional< std::string > discordpp::Activity::State

(

)

const

The state of the party for this activity.

See the docs on the Activity struct for more info. If specified, must be a string between 2 and 128 characters.

SupportedPlatforms()

discordpp::ActivityGamePlatforms discordpp::Activity::SupportedPlatforms

(

)

const

If an activity is joinable, but only on certain platforms, this field can be used to indicate which platforms the activity is joinable on. For example if a game is available on both PC and Mobile, but PC users cannot join Mobile users and vice versa, this field can be used so that an activity only shows as joinable on Discord if the user is on the appropriate platform.

Timestamps()

std::optional< discordpp::ActivityTimestamps > discordpp::Activity::Timestamps

(

)

const

The timestamps struct can be used to render either:

• a "time remaining" countdown timer (by specifying the end value)
• a "time elapsed" countup timer (by specifying the start value)

Type()

discordpp::ActivityTypes discordpp::Activity::Type

(

)

const

The type of activity this is.

This should almost always be set to Playing

Member Data Documentation

nullobj

const Activity discordpp::Activity::nullobj

static

Uninitialized instance of Activity.