Use "app" not "activity"

README.md

@@ -1,49 +1,44 @@
-# embedded-app-sdk
+# @discord/embedded-app-sdk
 
-This library enables communication between your Activity and Discord. Whether launched via Discord's web app, desktop app, iOS, or Android, the `embedded-app-sdk` provides a unified API that enables your activity to be a part of a real-time voice call inside of Discord.
+This library enables communication between your Application and Discord. Whether launched via Discord's web app, desktop app, iOS, or Android, `@discord/embedded-app-sdk` provides a unified API that enables your application to integrate a real-time application inside of Discord's UI via an embedded iframe.
 
 - [Quick Start](#quick-start)
 - [Common Patterns](#common-patterns)
-- [Developer Details](#developer-details)
 - [Production Readiness](#production-readiness)
-- [Example Activities](#example-activities)
-- [Installing this package](#installing-this-package)
-- [Usage](#usage)
+- [Examples](#examples)
 - [Security Notice](#security-notice)
 - [SDK development](#sdk-development)
 
 ## Quick Start
 
-At its core, a Discord Activity is a "Discord Application" which serves a website inside of a voice call. Learn how to set up your Discord application and launch your first activity [here](/docs/setting-up-your-discord-application.md).
+Learn how to set up your application to launch an iframe inside of Discord [here](/docs/setting-up-your-iframe.md).
 
 ## Common Patterns
 
-Learn about common patterns that your activity may want to use [here](/docs/common-patterns.md).
-
-## Developer Details
-
-The devil is in the details. Even though activities are "essentially" a website, we discuss some of the quirks and workarounds that may be necessary for your activity [here](/docs/developer-details.md).
+Learn about common patterns that your application may want to use [here](/docs/common-patterns.md).
 
 ## Production Readiness
 
-Making a beautiful activity takes time. Once your activity is ready for production, we have a list of best practices to consider [here](/docs/developer-details/production-readiness.md)
+Making a polished application takes time. Once your application is ready for production, we have a list of best practices to consider [here](/docs/common-patterns/production-readiness.md)
 
-## Example Activities
+## Examples
 
-- [discord-activity-starter](/examples/discord-activity-starter) is a minimal activity example
-- [iframe-playground](/examples/iframe-playground) is a playground for testing any SDK functionality
-- [react-colyseus](/examples/react-colyseus/) shows how to set up shared activity state with Colyseus and React
+- [discord-application-starter](/examples/discord-application-starter) is a minimal example
+- [iframe-playground](/examples/iframe-playground) is a playground for testing any @discord/embeddedd-app-sdk functionality
+- [react-colyseus](/examples/react-colyseus/) shows how to set up shared application state with Colyseus and React
 
 ## Installing this package
 
-This javascript package is hosted via this github packages and can be installed via npm/yarn/pnpm/etc.. Learn more about how to install it [here](/docs/developer-details/installation.md).
+```shell
+npm install @discord/embedded-app-sdk
+```
 
 ## Usage
 
 To use the SDK, import it into your project and construct a new instance of the DiscordSDK class.
 
 Below is a minimal example of setting up the SDK.
-Please see [/examples/discord-activity-starter](/examples/discord-activity-starter) for a complete example application. See more info on environment variables (`YOUR_OAUTH2_CLIENT_ID`, etc...) [here](/docs/setting-up-your-discord-application.md#oauth2).
+Please see [/examples/discord-application-starter](/examples/discord-application-starter) for a complete example application. See more info on environment variables (`YOUR_OAUTH2_CLIENT_ID`, etc...) [here](/docs/setting-up-your-discord-application.md#oauth2).
 
 ```typescript
 import {DiscordSDK} from '@discord/embedded-app-sdk';
@@ -62,7 +57,7 @@ async function setup() {
     scope: ['identify'],
   });
 
-  // Retrieve an access_token from your activity's server
+  // Retrieve an access_token from your application's server
   const response = await fetch('/api/token', {
     method: 'POST',
     headers: {
@@ -85,23 +80,23 @@ Here is a corresponding flow diagram to the code-snippet above:
 
 ```mermaid
 sequenceDiagram
-title embedded-app-sdk: Authentication, Command, and Event flows
+title @discord/embedded-app-sdk: Authentication, Command, and Event flows
 
 participant A as Discord-Client
-participant B as Activity-Iframe
+participant B as Application-Iframe
 participant C as Discord API
-participant D as Activity-Server
+participant D as Application-Server
 
 alt SDK setup
-A->>B: Mounts Activity iframe
+A->>B: Mounts Application iframe
 B->>A: Initiate Handshake<br/>(No nonce included)
 A->>B: Open Socket
 A->>C: Fetch application info
 C->>A: Return application info<br/>and set it on the socket object
 A->>B: Ready Payload<br/>(No nonce included)
 B->>A: Request to authorize scopes<br/>(This step opens the OAuth modal)
 A->>B: Reply with OAuth authorize code
-B->>D: Send OAuth code to activity server
+B->>D: Send OAuth code to application server
 D->>C: Use OAuth code and client secret<br/>to fetch access_token from developer portal
 C->>D: Reply with access_token
 D->>B: Reply with access_token
@@ -125,10 +120,10 @@ end
 
 ## SECURITY NOTICE
 
-This is simply the nature of client apps but it bears repeating. **Do not trust data coming from the Discord client as truth.** It's fine to use this data in your activity _locally,_ but assume any data coming from the Discord Client could be falsified. That includes data about the current user, their nitro status, their current channel, etc. If you need this information in a trusted manner, contact Discord API directly from your activity's server, with the user token you received from completing the OAuth2 flow.
+This is simply the nature of client apps but it bears repeating. **Do not trust data coming from the Discord client as truth.** It's fine to use this data in your application _locally,_ but assume any data coming from the Discord Client could be falsified. That includes data about the current user, their nitro status, their current channel, etc. If you need this information in a trusted manner, contact Discord API directly from your application's server, with the user token you received from completing the OAuth2 flow.
 
-Want to learn more about "what the heck is this library actually doing ™️"? Read more about how the underlying postMessage protocol is set up [here](/docs/developer-details/post-message-protocol.md).
+Want to learn more about "what the heck is this library actually doing ™️"? Read more about how the underlying postMessage protocol is set up [here](/docs/common-patterns/post-message-protocol.md).
 
 ## SDK development
 
-Developing a new feature or patching a bug on the SDK? Check out [this guide](/docs/developer-details/local-sdk-development.md) to learn how to set up your local dev environment.
+Developing a new feature or patching a bug on the SDK? Check out [this guide](/docs/common-patterns/local-sdk-development.md) to learn how to set up your local dev environment.

docs/common-patterns.md

@@ -4,13 +4,23 @@ This section explores features and user-flows that are common to activities. Rat
 
 - [Embedded Links](/docs/common-patterns/embedded-links.md)
 - [Encourage Hardware Acceleration](/docs/common-patterns/encourage-hardware-acceleration.md)
-- [In-Activity-Purchases (IAP)](/docs/common-patterns/in-activity-purchases.md)
-- [Activity Orientation](/docs/common-patterns/activity-orientation.md)
+- [In-App-Purchases (IAP)](/docs/common-patterns/in-app-purchases.md)
+- [Application Orientation](/docs/common-patterns/application-orientation.md)
 - [Mobile Safe Areas](/docs/common-patterns/mobile-safe-areas.md)
 - [Mobile Thermal States](/docs/common-patterns/mobile-thermal-states.md)
 - [Modifying Participants Audio](/docs/common-patterns/modifying-participants-audio.md)
 - [Open Invite Dialog](/docs/common-patterns/open-invite-dialog.md)
 - [Rendering Avatars and Names](/docs/common-patterns/rendering-avatars-and-names.md)
-- [Setting Up the Activity Shelf](/docs/common-patterns/setting-up-the-activity-shelf.md)
-- [Preventing unwanted activity sessions](/docs/common-patterns/preventing-unwanted-activity-sessions.md)
+- [Setting Up the Embedded App Shelf](/docs/common-patterns/setting-up-the-embedded-app-shelf.md)
+- [Preventing unwanted application sessions](/docs/common-patterns/preventing-unwanted-application-sessions.md)
 - [Instance Participants](/docs/common-patterns/instance-participants.md)
+- [Creating a full URL](/docs/common-patterns/creating-a-full-url.md)
+- [Instance Management](/docs/common-patterns/instance-management.md)
+- [Local SDK Development](/docs/common-patterns/local-sdk-development.md)
+- [Logging](/docs/common-patterns/logging.md)
+- [Network Shims](/docs/common-patterns/network-shims.md)
+- [postMessage Protocol](/docs/common-patterns/post-message-protocol.md)
+- [URL Mapping](/docs/common-patterns/url-mapping.md)
+- [Handling 429 Error Codes](/docs/common-patterns/handling-429-error-codes.md)
+- [Production Readiness](/docs/common-patterns/production-readiness.md)
+- [Migrating from v1 to v2](/docs/common-patterns/v2-migration.md)

docs/common-patterns/application-orientation.md

@@ -0,0 +1,48 @@
+# Application Orientation
+
+## Locking Application Orientation
+
+This SDK provides APIs for locking the application to specific orientations. The possible lock states are `UNLOCKED`, `PORTRAIT`, and `LANDSCAPE`. `lock_state` is the default lock state, and it affects the app orientation when the application is focused. `picture_in_picture_lock_state` determines the PIP aspect ratio, and `grid_lock_state` determines the grid tile aspect ratio for the application. When `picture_in_picture_lock_state` is not set, the application PIP falls back to `lock_state` to determine the aspect ratio. When `grid_lock_state` is not set, the application grid tile falls back to `picture_in_picture_lock_state` to determine its aspect ratio, and if `picture_in_picture_lock_state`is not set, it uses `lock_state`.
+
+Calling `setOrientationLockState` with an `undefined` or omitted value for `picture_in_picture_lock_state` or `grid_lock_state` will not change the corresponding lock states for the application. Calling `setOrientationLockState` with a null value for `picture_in_picture_lock_state` or `grid_lock_state` will clear the application's corresponding lock states such that those layout modes will use the fallback lock states.
+
+```javascript
+import {DiscordSDK, Common} from '@discord/embedded-app-sdk';
+const discordSdk = new DiscordSDK(clientId);
+await discordSdk.ready();
+
+// Set a default lock state
+discordSdk.commands.setOrientationLockState({lock_state: Common.OrientationLockStateTypeObject.LANDSCAPE});
+
+// or set both a default lock state and a picture-in-picture lock state
+discordSdk.commands.setOrientationLockState({
+  lock_state: Common.OrientationLockStateTypeObject.PORTRAIT,
+  picture_in_picture_lock_state: Common.OrientationLockStateTypeObject.LANDSCAPE,
+  grid_lock_state: Common.OrientationLockStateTypeObject.LANDSCAPE,
+});
+```
+
+### Configuring Default Orientation Lock State Through the Developer Portal
+
+It's also possible to configure an application with a default orientation lock state via the Developer Portal. Using this method, the Discord app will apply the orientation lock when launching the application before the SDK has been initialized. This can create a smoother application launch flow where the application starts in the correct orientation rather than switching to the correct orientation after some delay after the application requests an orientation lock via the SDK. The Developer Portal supports setting a different default orientation lock states for phones versus tablets.
+
+![default-orientation-lock-state](/docs/assets/default_orientation_lock_state.png)
+
+## Subscribing to Screen Orientation Updates
+
+To listen to the screen orientation (which is sometimes different from the physical device orientation), subscribe to the `ORIENTATION_UPDATE` event. Discord will publish the current orientation upon event subscription, and it'll also publish any orientation changes that happen afterward.
+
+```javascript
+const handleOrientationUpdate = (update: {screen_orientation: number}) => {
+  switch (update.screen_orientation) {
+      case Common.OrientationTypeObject.PORTRAIT:
+        ...
+      case Common.OrientationTypeObject.LANDSCAPE:
+        ...
+      default:
+        ...
+    }
+}
+
+discordSdk.subscribe('ORIENTATION_UPDATE', handleOrientationUpdate);
+```

docs/common-patterns/backward-compatibility.md

@@ -2,7 +2,7 @@
 
 ## New Commands
 
-When new commands become available in the embedded-app-sdk, those commands won't be supported by all Discord app versions. The new command will typically only be supported by newer Discord app versions. When an activity tries to use a new command with an old Discord app version that doesn't support the command, the Discord app will respond with error code `INVALID_COMMAND` which the activity can handle like this:
+When new commands become available in the embedded-app-sdk, those commands won't be supported by all Discord app versions. The new command will typically only be supported by newer Discord app versions. When an application tries to use a new command with an old Discord app version that doesn't support the command, the Discord app will respond with error code `INVALID_COMMAND` which the application can handle like this:
 
 ```javascript
 try {

docs/common-patterns/encourage-hardware-acceleration.md

@@ -1,6 +1,6 @@
 # Encourage Hardware Acceleration
 
-Activities that are compute intensive may benefit from encouraging users to enable hardware acceleration. When an activity invokes the `encourageHardwareAcceleration` command the current status of the setting will be returned and the user will be prompted to update the setting, if applicable.
+Activities that are compute intensive may benefit from encouraging users to enable hardware acceleration. When an application invokes the `encourageHardwareAcceleration` command the current status of the setting will be returned and the user will be prompted to update the setting, if applicable.
 
 ## Usage
 
@@ -14,7 +14,7 @@ console.log(`Hardware Acceleration is ${enabled === true ? 'enabled' : 'disabled
 
 ## Best Practices
 
-Switching Hardware Acceleration setting causes the Discord client to quit and re-launch, so it is best practice to invoke this command as soon as possible, so users do not begin the experience of an activity before restarting. Ideally, this is immediately after `await discordSdk.ready()`.
+Switching Hardware Acceleration setting causes the Discord client to quit and re-launch, so it is best practice to invoke this command as soon as possible, so users do not begin the experience of an application before restarting. Ideally, this is immediately after `await discordSdk.ready()`.
 
 ## User Experience
 

docs/developer-details/handling-429-error-codes.md → docs/common-patterns/handling-429-error-codes.md

@@ -4,4 +4,4 @@ One very common obstacle when interacting with Discord's APIs is rate-limiting.
 
 ## Common Pattern for handling 429 Error Codes
 
-Check out [this example](/examples/discord-activity-starter/packages/server/src/utils.ts) of how to respect the `retry_after` header when you receive a 429 error.
+Check out [this example](/examples/discord-application-starter/packages/server/src/utils.ts) of how to respect the `retry_after` header when you receive a 429 error.