embed UX image, referrer_id changes

Author: goatslacker

docs/activities/Development_Guides.mdx

@@ -896,11 +896,11 @@ This example is being done entirely on the client, however, a more common patter
 
 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.
+1. **Referral links.** Users can copy referral links inside your Activity, which include their Discord user ID (`https://discord.com/activities/<your Activity ID>?referrer_id=123456789`), 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.
+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=123456789&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.
+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>?custom_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.
@@ -926,7 +926,7 @@ try {
     const { success } = await discordSdk.commands.shareLink({
         message: 'Click this link to redeem 5 free coins!',
         custom_id: customId,
-        // referrer_id is optional - if omitted, the current user's ID is used
+        // referrer_id is optional - if omitted, the message's author user ID is used
     });
 
     if (success) {
@@ -983,6 +983,7 @@ async function handleReferral() {
 - Track and validate referrals to prevent abuse
 - Handle edge cases like expired promotions gracefully
 - Consider implementing cool-down periods between shares
+- Do not use or override `referrer_id` directly. When set, `referrer_id` will always be a Discord snowflake-type user ID, otherwise it will be set to the message's author id.
 
 ---
 
@@ -996,7 +997,7 @@ This guide covers creating a customizable [Incentivized Link](#DOCS_ACTIVITIES_D
 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.
+5. All other fields are optional but you are able to customize the primary button's label as well as acustom_id to the link. An explicit `custom_id` query parameter on the link itself will always override the set custom_id.
 6. Click Save.
 
 #### Editing a Link
@@ -1007,7 +1008,7 @@ This guide covers creating a customizable [Incentivized Link](#DOCS_ACTIVITIES_D
 
 #### 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.
+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 `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
 
@@ -1021,6 +1022,12 @@ Once you're satisfied with your changes you can click on the copy icon on the ro
 - 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.
 
+#### User Experience
+
+![custom-link-embed](activities/custom-link-embed.png)
+
+Users will see an embed with your information displayed. Clicking "Play" opens the activity and passes through the `custom_id` you've set. A `referrer_id` will be present for links shared on Discord.
+
 ---
 
 ### Preventing unwanted activity sessions