Merge branch 'main' into patch-4

IgnisRBX · web-flow · commit 9ae12231b53a · 2025-05-15T06:16:00.000-10:00
diff --git a/content/common/navigation/monetize/experiences.yaml b/content/common/navigation/monetize/experiences.yaml
@@ -16,6 +16,8 @@ navigation:
     path: /production/monetization/game-passes
   - title: Developer products
     path: /production/monetization/developer-products
+  - title: Commerce products
+    path: /production/monetization/commerce-products
   - title: Paid access in Robux
     path: /production/monetization/paid-access-robux
   - title: Paid access in local currency
@@ -37,4 +39,4 @@ navigation:
   - title: Search ads
     path: /production/promotion/search-ads
   - title: Advertising standards
-    path: /production/promotion/comply-with-advertising-standards
+    path: /production/promotion/comply-with-advertising-standards
diff --git a/content/en-us/assets/monetization/commerce-products/Commerce-Product-ID.png b/content/en-us/assets/monetization/commerce-products/Commerce-Product-ID.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e6f00ce8275dbdce0958a540311072da9591f2e0b62afa94f06ffb4f7ae110fa
+size 26016
diff --git a/content/en-us/assets/monetization/commerce-products/Commerce-Product-Put-On-Sale.png b/content/en-us/assets/monetization/commerce-products/Commerce-Product-Put-On-Sale.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:16f2f547ee59850fc4702cc811d50f5f942db6c14489d2418d32b814d9b2f4ea
+size 12277
diff --git a/content/en-us/assets/monetization/commerce-products/Commerce-Product-Virtual-Benefits.png b/content/en-us/assets/monetization/commerce-products/Commerce-Product-Virtual-Benefits.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6291a17b051d34f3fcb5d64f3bead392b98717fe3a85abae2ac6a80e5ce71d29
+size 109315
diff --git a/content/en-us/production/monetization/commerce-products.md b/content/en-us/production/monetization/commerce-products.md
diff --git a/content/en-us/production/promotion/experience-events.md b/content/en-us/production/promotion/experience-events.md
@@ -76,6 +76,16 @@ All published events also appear in a dedicated **Events** section on the experi
 
 <img src="../../assets/promotion/experience-events/Experience-Page-Promotion.png" width="840" alt="Event promoted on experience's detail page" />
 
+### Roblox charts
+
+The **Trending Events in Experiences** sort in Roblox's [charts](https://www.roblox.com/charts), available globally and across all platforms, can help increase player discovery and participation in your events. This sort shows active events based on the experience's daily active users (DAU), filterable by location and platform.
+
+To be featured in **Trending Events in Experiences**, your event must meet the following criteria:
+
+- An active event that started within the last 7 days.
+- Minimum of 1,000 RSVPs.
+- Visible to all players (not private).
+
 ### Group page
 
 If you create events as an admin for a [group](../../projects/groups.md), the group's events will appear under the **Events** tab on the group page.
diff --git a/content/en-us/reference/engine/classes/CommerceService.yaml b/content/en-us/reference/engine/classes/CommerceService.yaml
@@ -1,8 +1,8 @@
 name: CommerceService
 type: class
 memory_category: Instances
-summary: ''
-description: ''
+summary: 'Supports real-world purchases that you can bundle with digital benefits.'
+description: '`Class.CommerceService` is a service that supports real-world purchases that you can bundle with virtual items. For information on eligibility and implementation, see [Commerce products](../../../production/monetization/commerce-products.md).'
 code_samples: []
 inherits:
   - Instance
@@ -13,8 +13,8 @@ deprecation_message: ''
 properties: []
 methods:
   - name: CommerceService:PromptCommerceProductPurchase
-    summary: ''
-    description: ''
+    summary: 'Prompts a user to purchase a commerce product using the provided `commerceProductId`. Opens a webview that guides the user through the purchasing flow.'
+    description: 'Prompts a user to purchase a commerce product using the provided `commerceProductId`. Opens a webview that guides the user through the purchasing flow.'
     code_samples: []
     parameters:
       - name: user
@@ -36,7 +36,7 @@ methods:
     writeCapabilities: []
   - name: CommerceService:PromptRealWorldCommerceBrowser
     summary: ''
-    description: ''
+    description: 'This is a legacy endpoint that is not meant for use. To open the webview to the purchasing flow for real world commerce, see `Class.CommerceService:PromptCommerceProductPurchase`. For more information, see [Commerce products](../../../production/monetization/commerce-products.md)'
     code_samples: []
     parameters:
       - name: player
@@ -57,8 +57,40 @@ methods:
     capabilities: []
     writeCapabilities: []
   - name: CommerceService:GetCommerceProductInfoAsync
-    summary: ''
-    description: ''
+    summary: 'Retrieves information about the commerce products you are selling in experience.'
+    description: |
+      Retrieves information about the products that you are selling and surface them within your experience. How you surface products to your users is entirely up to you.
+
+      <table><thead>
+        <tr>
+          <th>Name</th>
+          <th>string</th>
+          <th>Localized name of of the physical item</th>
+        </tr></thead>
+      <tbody>
+        <tr>
+          <td>Description</td>
+          <td>string</td>
+          <td>Localized description of the physical item</td>
+        </tr>
+        <tr>
+          <td>IconImageAssetId</td>
+          <td>number</td>
+          <td>The image asset id of main default image of the physical item</td>
+        </tr>
+        <tr>
+          <td>DisplayPrice</td>
+          <td>string</td>
+          <td>Localized price string with currency symbol of the physical item. e.g. “$4.99“</td>
+        </tr>
+        <tr>
+          <td>IsPurchasable</td>
+          <td>bool</td>
+          <td>If the item can be added to a merchant checkout session, i.e. item is in stock, or can be backordered</td>
+        </tr>
+      </tbody>
+      </table>
+
     code_samples: []
     parameters:
       - name: commerceProductId
@@ -77,7 +109,7 @@ methods:
     writeCapabilities: []
   - name: CommerceService:UserEligibleForRealWorldCommerceAsync
     summary: ''
-    description: ''
+    description: 'This is a legacy endpoint that is not meant for use. To check if a user is eligible for real world commerce, see `Class.PolicyService.IsEligibleToPurchaseCommerceProduct`. For more information, see [Commerce products](../../../production/monetization/commerce-products.md)'
     code_samples: []
     parameters: []
     returns:
@@ -92,8 +124,12 @@ methods:
     writeCapabilities: []
 events:
   - name: CommerceService.PromptCommerceProductPurchaseFinished
-    summary: ''
-    description: ''
+    summary: 'Fires when commerce purchase webview has closed - not an indicator that a purchase was successful.'
+    description: |
+      Use this signal to detect when a user has completed the purchasing flow and the webview has closed to resume gameplay within the experience. **This signal does not indicate a successful purchase**, so do not grant virtual items solely from this signal.
+
+      While optional, it is recommended to use this signal to reorient your users on Android, as the commerce purchasing flow will have forced them into portrait mode.
+
     code_samples: []
     parameters:
       - name: user
diff --git a/content/en-us/reference/engine/classes/PolicyService.yaml b/content/en-us/reference/engine/classes/PolicyService.yaml
@@ -101,6 +101,12 @@ methods:
       <td>When <code>true</code>, the player is allowed to share content using APIs which open external sharing flows such as <code>Class.CaptureService:PromptShareCapture()|PromptShareCapture()</code>.</td>
       </tr>
       <tr>
+      <td><code>IsEligibleToPurchaseCommerceProduct</code></td>
+      <td>Boolean</td>
+      <td>Any experience that wants to sell <a href="../../../production/monetization/commerce-products.md">commerce products</a>.</td>
+      <td>When <code>true</code>, the player is eligible to purchase commerce products within an experience.</td>
+      </tr>
+      <tr>
       <td><code>IsEligibleToPurchaseSubscription</code></td>
       <td>Boolean</td>
       <td>Any experience that wants to sell subscriptions.</td>
@@ -159,6 +165,7 @@ methods:
       client IP geolocation.
     code_samples:
       - getting-policy-information-for-a-player
+      - getting-policy-for-a-player-for-commerce-products
     parameters:
       - name: player
         type: Instance
diff --git a/tools/checks/main.ts b/tools/checks/main.ts
@@ -44,6 +44,7 @@ import {
   checkMdxEquality,
   isLocaleFile,
   outdatedTranslationFiles,
+  checkVoidTagsHaveNoChildren,
 } from './utils/localization.js';
 import { Emoji } from './utils/utils.js';
 import { deduplicate } from './utils/utils.js';
@@ -267,6 +268,7 @@ try {
       config.checkLocalizedContent &&
       !isLocaleFile(filePathFromRepoRoot, Locale.EN_US) // skip for English
     ) {
+      checkVoidTagsHaveNoChildren(filePathFromRepoRoot);
       checkEnglishVersionExists(filePathFromRepoRoot);
       await checkMdxEquality(filePathFromRepoRoot, fileContent);
       checkFileImportEquality(filePathFromRepoRoot, fileContent);
diff --git a/tools/checks/utils/localization.ts b/tools/checks/utils/localization.ts
@@ -1,11 +1,15 @@
 import * as fs from 'fs';
-import { addToSummaryOfRequirements } from './console.js';
+import {
+  addToSummaryOfRequirements,
+  addToSummaryOfSuggestions,
+} from './console.js';
 import { Emoji } from './utils.js';
 import {
   areEqualComponentDetails,
   getMdxComponents,
   isIComponentDetails,
   isVFileMessage,
+  validateVoidTagsAreEmpty,
 } from './unified.js';
 import { getNonEditableFilesList } from './files.js';
 import { areEqualFileImports, FileImports, getFileImports } from './imports.js';
@@ -85,6 +89,22 @@ export const checkEnglishVersionExists = (filePath: string) => {
   }
 };
 
+/**
+ * Check that all void tags have no children
+ * Avoids React runtime errors like "Error: img is a self-closing tag and must neither have `children` nor use `dangerouslySetInnerHTML`."
+ * @param filePath - The path to the file to check
+ */
+export const checkVoidTagsHaveNoChildren = (filePath: string) => {
+  const fileContent = getCachedContentForFilePath(filePath);
+  const result = validateVoidTagsAreEmpty(fileContent);
+  if (result) {
+    console.log(result);
+    const message = `${Emoji.NoEntry} Requirement: In ${filePath}, ${result.message}`;
+    console.log(message);
+    addToSummaryOfRequirements(message);
+  }
+};
+
 const getCachedContentForFilePath = (filePath: string): string => {
   if (!filePathToRawContentMap.has(filePath)) {
     filePathToRawContentMap.set(filePath, fs.readFileSync(filePath, 'utf8'));
@@ -173,10 +193,10 @@ export const checkMdxEquality = async (
         `${Emoji.WhiteCheckMark} MDX components match ${comparisonMessage}`
       );
     } else {
-      const errorMessage = `${Emoji.NoEntry} MDX components do not match ${comparisonMessage}`;
+      const errorMessage = `${Emoji.Warning}  Warning: MDX components do not match ${comparisonMessage}`;
       console.log(errorMessage);
       outdatedTranslationFiles.push(filePath);
-      addToSummaryOfRequirements(errorMessage);
+      addToSummaryOfSuggestions(errorMessage);
     }
   }
 };
diff --git a/tools/checks/utils/unified.test.ts b/tools/checks/utils/unified.test.ts
@@ -1,3 +1,4 @@
+// npm run jest -- tools/checks/utils/unified.test.ts
 import { VFileMessage } from 'vfile-message';
 import {
   RETEXT_INAPPROPRIATE,
@@ -9,6 +10,7 @@ import {
   replaceProfanityPatterns,
   isIComponentDetails,
   isVFileMessage,
+  validateVoidTagsAreEmpty,
 } from './unified.js';
 import {
   RETEXT_EQUALITY_ALLOW_LIST,
@@ -686,3 +688,91 @@ describe('isVFileMessage', () => {
     expect(isVFileMessage(details)).toBe(false);
   });
 });
+
+describe('validateVoidTagsAreEmpty', () => {
+  it('should throw an error if an <img> tag has children', () => {
+    const text =
+      'Hello <img src="https://example.com/image.jpg" width="100" alt="Image">Invalid content</img> World';
+    const result = validateVoidTagsAreEmpty(text);
+    expect(result).toBeDefined();
+    expect(result?.message).toBe(
+      'line 1, column 7, <img> tag must not have children'
+    );
+  });
+  it('should not throw an error if an <img> opening and closing tag has no children', () => {
+    const text =
+      'Hello <img src="https://example.com/image.jpg" width="100" alt="Image"></img> World';
+    const result = validateVoidTagsAreEmpty(text);
+    expect(result).toBeUndefined();
+  });
+  it('should not throw an error if an <img> opening and closing tag has whitespace children', () => {
+    const text =
+      'Hello <img src="https://example.com/image.jpg" width="100" alt="Image"> </img> World';
+    const result = validateVoidTagsAreEmpty(text);
+    expect(result).toBeUndefined();
+  });
+  it('should not throw an error if an <img> opening and closing tag are on new lines', () => {
+    const text = `Hello 
+
+<img src="https://example.com/image.jpg" width="100" alt="Image">
+</img>
+
+World`;
+    const result = validateVoidTagsAreEmpty(text);
+    expect(result).toBeUndefined();
+  });
+
+  it('should throw an error if an <img> tag has invalid content', () => {
+    const text = `Paragraph 1
+
+<img src="../../assets/path/to/image.png">
+  \>
+</img>
+
+Paragraph 2`;
+    const result = validateVoidTagsAreEmpty(text);
+    expect(result).toBeDefined();
+    expect(result?.message).toBe(
+      'line 3, column 1, <img> tag must not have children'
+    );
+  });
+
+  it('should not throw an error if an <img> opening and closing tag have multiple new lines between them', () => {
+    const text = `Hello 
+
+<img src="https://example.com/image.jpg" width="100" alt="Image">
+
+
+
+</img>
+
+World`;
+    const result = validateVoidTagsAreEmpty(text);
+    expect(result).toBeUndefined();
+  });
+  it('should not throw an error if an <img> self-closing tag has no children', () => {
+    const text =
+      'Hello <img src="https://example.com/image.jpg" width="100" alt="Image" /> World';
+    const result = validateVoidTagsAreEmpty(text);
+    expect(result).toBeUndefined();
+  });
+  it('should throw an error if a <br> tag has children', () => {
+    const text = `Hello 
+
+<br>
+  Invalid content
+</br> 
+
+World`;
+    const result = validateVoidTagsAreEmpty(text);
+    expect(result).toBeDefined();
+    expect(result?.message).toBe(
+      'line 3, column 1, <br> tag must not have children'
+    );
+  });
+  it('should not throw an error if a <br> tag has no children', () => {
+    const text = 'Hello <br /> World';
+    const result = validateVoidTagsAreEmpty(text);
+    expect(result).toBeUndefined();
+  });
+});
diff --git a/tools/checks/utils/unified.ts b/tools/checks/utils/unified.ts
diff --git a/tools/checks/utils/utils.ts b/tools/checks/utils/utils.ts
