Managed incentivized links

Author: goatslacker

docs/activities/Building_An_Activity.mdx

@@ -88,7 +88,7 @@ npm install
 npm run dev
 ```
 
-If you visit http://localhost:5173/ you should see a vanilla JS frontend template running with [Vite](https://vitejs.dev/).
+If you visit http://localhost:3000/ you should see a vanilla JS frontend template running with [Vite](https://vitejs.dev/).
 
 While it's not much at the moment, in the following steps we'll connect it to the backend services, make it runnable in Discord, and power it up by populating it with data we pull from Discord APIs.
 
@@ -162,11 +162,11 @@ cp example.env .env
 > **Secure Your Secrets**<br /> Your `DISCORD_CLIENT_SECRET` and `DISCORD_BOT_TOKEN` are *highly* sensitive secrets. Never share either secrets or check them into any kind of version control.
 
 Back in your app's settings, click on **OAuth2** on the sidebar:
-1. **Client ID**: Copy the value for Client ID and add it to your `.env` file as **`VITE_DISCORD_CLIENT_ID`**. This is the public ID that Discord associates with your app, and is almost always the same as your App ID.
+1. **Client ID**: Copy the value for Client ID and add it to your `.env` file as **`VITE_CLIENT_ID`**. This is the public ID that Discord associates with your app, and is almost always the same as your App ID.
 2. **Client Secret**: Copy the value for Client Secret and add it to your `.env` as **`DISCORD_CLIENT_SECRET`**. This is a private, sensitive identifier that your app will use to grant an OAuth2 `access_token`, and should never be shared or checked into version control.
 
 > info
-> **Why is there a VITE_ prefix before our Client ID?**<br />Prefixing the `DISCORD_CLIENT_ID` environment variable with `VITE_` makes it accessible to our client-side code. This security measure ensures that only the variables you intend to be accessible in the browser are available, and all other environment variables remain private. You can read details in the [Vite documentation](https://vitejs.dev/guide/env-and-mode).
+> **Why is there a VITE_ prefix before our Client ID?**<br />Prefixing the `CLIENT_ID` environment variable with `VITE_` makes it accessible to our client-side code. This security measure ensures that only the variables you intend to be accessible in the browser are available, and all other environment variables remain private. You can read details in the [Vite documentation](https://vitejs.dev/guide/env-and-mode).
 
 <Collapsible title="Step 2 Checkpoint" icon="list" open>
 
@@ -265,7 +265,7 @@ Your app should start and you should see output similar to the following:
 ```
 VITE v5.0.12  ready in 100 ms
 
-➜  Local:   http://localhost:5173/
+➜  Local:   http://localhost:3000/
 ➜  Network: use --host to expose
 ➜  press h + enter to show help
 ```
@@ -276,10 +276,10 @@ We'll use the Local URL as our publicly-accessible URL in the next step.
 
 Next, we'll need to set up the public endpoint that serves the Activity's frontend. To do that, we'll create a tunnel with a reverse proxy. While we'll be using [`cloudflared`](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) in this guide, you can use [ngrok](https://ngrok.com/docs) or another reverse proxy solution if you prefer.
 
-While your app is still running, open another terminal window and start a network tunnel that listens to the port from the last step (in this case, port `5173`):
+While your app is still running, open another terminal window and start a network tunnel that listens to the port from the last step (in this case, port `3000`):
 
 ```
-cloudflared tunnel --url http://localhost:5173
+cloudflared tunnel --url http://localhost:3000
 ```
 
 When you run `cloudflared`, the tunnel will generate a public URL and you'll see output similar to the following:
@@ -680,7 +680,7 @@ At this point, you should have your Activity up and running. For Step 7, you sho
 
 Congrats on building your first Activity! 🎉
 
-This is an intentionally simple example to get you started with the communication between your Activity and Discord using the Embedded App SDK and APIs. From here, you can explore the [Activities documentation](#DOCS_ACTIVITIES_OVERVIEW) and other resources. 
+This is an intentionally simple example to get you started with the communication between your Activity and Discord using the Embedded App SDK and APIs. From here, you can explore the [Activities documentation](#DOCS_ACTIVITIES_OVERVIEW) and other resources.
 
 <Container>
   <Card title="Development Guides" link="#DOCS_DEVELOPER_TOOLS_COMMUNITY_RESOURCES" icon="WrenchIcon">

docs/activities/Development_Guides.mdx

@@ -103,6 +103,12 @@ These guides include suggested development practices, SDK commands, and user flo
   </Card>
 </Container>
 
+<Container>
+  <Card title="Creating and Managing Custom Incentivized Links" link="#DOCS_ACTIVITIES_DEVELOPMENT_GUIDES/creating-and-managing-custom-incentivized-links">
+    For off-platform sharing of rewards, promotions, or limited time experiences.
+  </Card>
+</Container>
+
 ## Assets & Metadata
 <Container>
   <Card title="Setting Up Activity Metadata" link="#DOCS_ACTIVITIES_DEVELOPMENT_GUIDES/setting-up-activity-metadata">
@@ -888,9 +894,19 @@ This example is being done entirely on the client, however, a more common patter
 
 ### Prompting Users to Share Incentivized Links
 
-Incentivized sharing can help grow your Activity through network effects. This guide covers implementing a reward system for users who share links and those who click them.
+Incentivized sharing can help grow your Activity through network effects. You can use links in several different ways such as:
+
+1. **Referral links.** Users can copy referral links inside your Activity, which include their referrer ID (`https://discord.com/activities/<your Activity ID>?referrer_id=123`), and they can send to their friends. If their friend accepts and starts playing your game, then you gift the referrer something inside your game.
+2. **Promotions.** You can run a temporary promotion on social media, where you offer a reward if they start playing now. Share a custom link on your social media (`https://discord.com/activities/<your Activity ID>?custom_id=social012025` ). Anyone who clicks that specific link receives something inside your game.
+3. **Social deep-links.** Currently, when users launch an Activity, they all land in the same place. Instead, you can start deep-linking to contextually relevant points in your game. For example, user A can copy a link inside your Activity for engaging other users (`https://discord.com/activities/<your Activity ID>?referrer=123&custom_id=visit-location`), and sends the link to their friends in a DM or channel. Then, user B who clicks the link gets taken directly to user A’s location.
+4. **Turn-based deep-links.** When you send an “it’s your turn” DM to a user, you can include a link which takes them directly to the right game instance and the turn they need to take.
+5. **Affiliate marketing.** You can work with affiliates (influencers, companies, etc) to advertise your game to their followings, and reward them via a custom link (`https://discord.com/activities/<your Activity ID>?referrer_id=influencer1`). Then, for every user that starts playing because of said influencer, you can then pay out to the influencer.
+6. **Source attribution.** You can use the `custom_id` parameter to figure out how much traffic you’re getting from different marketing sources.
+
+This guide covers implementing a referral link which will feature a reward system for users who share links and those who click them.
 
 #### Implementation Overview
+
 1. Create and track an incentivized link for a promotional campaign, then prompt users to share the link
 2. Handle incoming referrals and grant valid rewards
 
@@ -924,6 +940,7 @@ try {
 ```
 
 #### Handling Incoming Referrals
+
 When a user clicks a shared link, your activity will launch with referral data available through the SDK:
 
 ```javascript
@@ -961,13 +978,51 @@ async function handleReferral() {
 ```
 
 #### Link Sharing Best Practices
+
 - Generate unique, non-guessable `customId`s
 - Track and validate referrals to prevent abuse
 - Handle edge cases like expired promotions gracefully
 - Consider implementing cool-down periods between shares
 
 ---
 
+### Creating and Managing Custom Incentivized Links
+
+This guide covers creating a customizable [Incentivized Link](#DOCS_ACTIVITIES_DEVELOPMENT_GUIDES/prompting-users-to-share-incentivized-links) through the dev portal, and then retrieving the link to be able to share it off-platform.
+
+#### Creating a Link
+
+1. In your Application's portal, visit the Custom Links page under the Activities heading in the navigation pane.
+2. On the Custom Links page, click `Create New` to create a new link.
+3. You will need to upload an image with an aspect ratio of 43:24.
+4. Title, and description is also required.
+5. All other fields are optional but you are able to customize the primary button's label as well as add a referrer_id and custom_id to the link. Explicit referrer_id and custom_id on the link itself will always override the set referrer_id and custom_id.
+6. Click Save.
+
+#### Editing a Link
+
+1. Click on a row opens up the modal with all of the data loaded in ready for your edits.
+2. Let's change the description to something else.
+3. Click Update.
+
+#### Copying a Link
+
+Once you're satisfied with your changes you can click on the copy icon on the row, it'll change colors to green indicating that it copied to your clipboard. You are now able to share this link anywhere. The link will look like: `https://discord.com/activities/<your Activity ID>?link_id=0-123456789`. Even if you've set a `referrer_id` and/or a `custom_id`, it won't be explicitly included in the link but will be loaded once a user clicks on the link. You can then further shorten this URL if you'd like.
+
+#### Deleting a Link
+
+1. Click on the trash icon on the row of the link you're trying to delete.
+2. You'll have a confirm dialog pop up.
+3. Deleting is irreversible and immediate. Ensure that your link isn't in active use before deleting and/or that your activity gracefully handles any click-throughs from the link.
+
+#### Best Practices
+
+- Generate unique, non-guessable `customId`s
+- Track and validate referrals to prevent abuse
+- Gracefully handle expirations in your activity for any custom links that are limited time but still live off-platform.
+
+---
+
 ### Preventing unwanted activity sessions
 
 Activities are surfaced through iframes in the Discord app. The activity website itself is publicly reachable at `<application_id>.discordsays.com`. Activities will expect to be able to communicate with Discord's web or mobile client via the Discord SDK's RPC protocol. If a user loads the activity's website in a normal browser, the Discord RPC server will not be present, and the activity will likely fail in some way.