> ## Documentation Index
> Fetch the complete documentation index at: https://discord-platform-username.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# How Activities Work
> Understand the technical architecture and lifecycle of Discord Activities.
Activities are web applications that run in an iframe within Discord on desktop, mobile and web. In order to achieve this, we use the [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) protocol to enable secure communication between your application and Discord.
The [Embedded App SDK](https://github.com/discord/embedded-app-sdk) simplifies this process by managing the `postMessage` protocol on your behalf. For details on available commands and their usage, consult the [SDK Reference](/developers/developer-tools/embedded-app-sdk). Our [Sample Projects](/developers/activities/overview#sample-projects) provide practical examples of how to implement these features.
## Launching Activities
After you have Activities enabled in your Application's [Activity's settings](https://discord.com/developers/applications/select/embedded/settings), your app can launch Activities in two ways:
1. When a user invokes your app's Entry Point command in the App Launcher
2. By responding to an interaction with the `LAUNCH_ACTIVITY` callback type
Each of these are covered in more detail in the below sections.
### Entry Point Command
Activities are primarily opened when users invoke your app's [Entry Point command](/developers/interactions/application-commands#entry-point-commands) in the App Launcher.
When you enable Activities for your app, a [default Entry Point command](/developers/interactions/application-commands#default-entry-point-command) called "Launch" is created for you. By default, Discord automatically handles opening your Activity when your Entry Point command is run by a user.
Read more about setting up Entry Point commands in the [development guide](/developers/activities/development-guides/user-actions#setting-up-an-entry-point-command).
### Interaction Response
Activities can be launched in response to [command](/developers/interactions/overview#commands), [message component](/developers/interactions/overview#message-components), and [modal submission](/developers/interactions/overview#modals) interactions. To open an Activity, set the callback type to `LAUNCH_ACTIVITY` (type `12`) when [responding to the interaction](/developers/interactions/receiving-and-responding#responding-to-an-interaction).
***
## Designed for Single-Page Apps (SPAs)
This SDK is intended for use by a single-page application. We recognize developers may be using frameworks or approaches that are not an exact fit for single-page applications. We recommend nesting those frameworks inside your Activity's top-level single-page application and passing messages as you see fit. Please refer to the [Nested Messages App](/developers/activities/overview#sample-projects) sample project for guidance on this approach.
## Activity Lifecycle
1. **Initialization:** When your iframe is loaded within Discord, it will include unique query parameters in its URL. These parameters are identifiable by your application using the Discord SDK.
2. **Handshake Process:** Constructing the SDK instance begins a handshake process with the Discord client. Once the connection is established, the iframe receives a `[FRAME, {evt: 'READY', ...}]` message. The `ready()` method of the SDK instance resolves once a successful connection has been established.
3. **Authorization and Authentication:** After receiving the `READY` payload, your application should perform authorization and authentication to acquire necessary permissions (scopes). This step is crucial for utilizing specific features or scopes, such as `rpc.activities.write`.
4. **Interacting with Discord Client:** Post-authentication, your application can subscribe to events and send commands to the Discord client. Note that attempting to use commands or subscribe to events outside your granted scope will result in errors. Adding new scopes may prompt an OAuth modal for user permission re-confirmation.
5. **Disconnection and Errors:** Receiving a `[CLOSE, {message: string, code: number}]` message indicates an error or a need to restart the connection process.
6. **Sending Errors or Close Requests:** To communicate an error or request a close from the Discord client, send `[CLOSE, {message?: string, code: number}]`. A code other than CLOSE\_NORMAL will display the message to the user, while CLOSE\_NORMAL results in a silent closure.
## Sample Code and Activity Lifecycle Diagram
Below is a minimal example of setting up the SDK. Please see our [Sample Projects](/developers/activities/overview#sample-projects) for more complete sample applications.
```javascript theme={null}
import {DiscordSDK} from '@discord/embedded-app-sdk';
const discordSdk = new DiscordSDK(YOUR_OAUTH2_CLIENT_ID);
async function setup() {
// Wait for READY payload from the discord client
await discordSdk.ready();
// Pop open the OAuth permission modal and request for access to scopes listed in scope array below
const {code} = await discordSdk.commands.authorize({
client_id: YOUR_OAUTH2_CLIENT_ID,
response_type: 'code',
state: '',
prompt: 'none',
scope: ['identify'],
});
// Retrieve an access_token from your application's server
const response = await fetch('/.proxy/api/token', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
code,
}),
});
const {access_token} = await response.json();
// Authenticate with Discord client (using the access_token)
auth = await discordSdk.commands.authenticate({
access_token,
});
}
```
This diagram illustrates the communication flow between your application and Discord in the sample code above.
