Getting Started

To get started with the SDK there are a few steps you need to do:

1. Create and configure a Discord application to use with the SDK
2. Setup some callbacks to get logs and monitor the status of the SDK
3. Periodically run those callbacks on your game or application's main loop
4. Authenticate with Discord
5. Start the SDK

Let's go through those steps

Step 1: Create a Discord application

1. Create a new application on the Discord Developer Portal: https://discord.com/developers/applications
2. Go through the "Getting Started" flow under the "Social SDK" section.
3. Add a redirect URL for your application in the developer portal on the OAuth2 tab. For desktop applications this should be http://127.0.0.1/callback, but you can change this later. See discordpp::Client::Authorize for more details on this redirect.

1. Enable the "Public Client" toggle in the developer portal on the OAuth2 tab. This will allow you to test the SDK without having a backend setup yet, but you should re-evaluate if you need this setting before shipping. See discordpp::Client::Authorize for more details on this.

Step 2: Logging

Next you'll want to do is to attach callbacks to discordpp::Client so you can view logs and check for the Status of it. Most functions on the SDK cannot be called until discordpp::Client is in the discordpp::Client::Status::Ready state, so calling discordpp::Client::SetStatusChangedCallback is important to know when the Client is ready to use.

client->AddLogCallback([](auto message, auto severity) {
  printf("[%s] %s", discordpp::LoggingSeverityToString(severity).c_str(), message.c_str());
}, discordpp::LoggingSeverity::Info);
 
client->SetStatusChangedCallback([client](auto status, auto error, auto details) {
  printf("Status has changed to %s\n", discordpp::Client::StatusToString(status).c_str());
  if (status == discordpp::Client::Status::Ready) {
    printf("Client is ready, you can now call SDK functions. For example:\n");
    printf("You have %d friends\n", static_cast<int>(client->GetRelationships().size()));
  } else if (error != discordpp::Client::Error::None) {
    printf("Error connecting: %s %d\n", discordpp::Client::ErrorToString(error).c_str(),
    details);
  }
});

Step 3: Callbacks

Once you've registered callbacks with the SDK, you'll need to periodically execute them in the main loop of your program. Add something like this to your game's main event loop or tick function. If you're using the Unity or Unreal plugins, this is already handled for you.

discordpp::RunCallbacks();

Step 4: Auth

Next you'll want to get an authentication token to use with the SDK. The discordpp::Client::Authorize and discordpp::Client::GetToken functions are the way to do this. Here's a code snippet that shows how you can initiate the OAuth2 flow and get an access token. You will likely also want to save the token to some secure and durable storage so you don't need to re-do the authorization flow each time.

auto codeVerifier = client->CreateAuthorizationCodeVerifier();
discordpp::AuthorizationArgs args{};
args.SetClientId(APPLICATION_ID);
args.SetScopes(discordpp::Client::GetDefaultPresenceScopes()); // or discordpp::Client::GetDefaultCommunicationScopes()
args.SetCodeChallenge(codeVerifier.Challenge());
 
client->Authorize(args, [client, codeVerifier](auto result, auto code, auto redirectUri) {
  if (!result.Successful()) {
    printf("Auth Error: %s\n", result.ToString().c_str());
  } else {
    printf("Received authorization code, exchanging for access token\n");
    client->GetToken(APPLICATION_ID, code, codeVerifier.Verifier(), redirectUri,
      [client](auato result, auto accessToken, auto refreshToken, auto, auto, auto) {
        printf("Received access token, connecting to Discord\n");
        client->UpdateToken(discordpp::AuthorizationTokenType::Bearer, accessToken, [client](auto result) {
          client->Connect();
        });
      });
  }
});

On consoles, you can use the following code snippet to get an access token

discordpp::DeviceAuthorizationArgs args{};
args.SetClientId(APPLICATION_ID);
args.SetScopes(discordpp::Client::GetDefaultPresenceScopes());
client->GetTokenFromDevice(args, [client](auto result, auto accessToken, auto refreshToken, auto, auto, auto)
{
  printf("Received access token, connecting to Discord\n");
  client->UpdateToken(discordpp::AuthorizationTokenType::Bearer, accessToken, [client](auto result) {
    client->Connect();
  });
});

Step 5: Start the SDK

Now that you have an auth token you can connect the SDK. The example above shows how to pass in the auth token to the SDK and connect, but if you already have a token (such as one read from local storage), you can use the following:

client->UpdateToken(discordpp::AuthorizationTokenType::Bearer, accessToken, [client](auto result) {
  client->Connect();
});

The SDK connects asynchronously, so you will need to wait for the status to change to discordpp::Client::Status::Ready before you can use most SDK functions. The discordpp::Client::SetStatusChangedCallback function is a good way to know when the SDK is ready to use.

Debugging

Debugging symbols are hosted at https://storage.googleapis.com/discord-public-symbols. If using Visual Studio, you can add this link to the pdb locations under Tools > Options > Debugging > Symbols.

NOTE: You won’t be able to browse files using that link, but that’s ok. Individual files are accessible under the domain and the URL will function properly as a symbol server, so it will work in Visual Studio.