Getting Started with Salesforce Experience Cloud

Optimizing the integration between Salesforce Experience Cloud and Median.co requires a deep understanding of how Salesforce’s proprietary security layers interact with a native mobile WebView. This guide provides an expanded technical framework for developers to navigate these complexities.

Detecting App usage and Median Architecture

The Median.co platform functions as a native application shell (using WKWebView on iOS and WebView on Android) that renders your Salesforce Experience Cloud site. Unlike Salesforce’s native Mobile Publisher, this approach allows for greater CSS flexibility and rapid deployment cycles, but it requires the Salesforce site to be "mobile-aware" from the first byte.

• Runtime Selection: When building your site, prioritize the LWR (Lightning Web Runtime) over the older Aura framework. LWR is built on web standards, offering significantly faster page load times and better performance within a mobile WebView.
• User Agent Masking: Salesforce detects the browser type to determine which resources to serve. If the Median app uses a generic user agent string, Salesforce may serve the desktop layout.
  • Best Practice: Within the Median App Studio, append a custom string to your User Agent (e.g., Median). In Salesforce, you can then use this string in Apex or Global CSS to apply mobile-specific overrides.

Platform-Specific Challenges

CSP (Content Security Policy) & Trusted Sites

Salesforce employs a strict Content Security Policy to prevent Cross-Site Scripting (XSS). Because Median injects a JavaScript bridge (median.js) to facilitate communication between the web code and native hardware, Salesforce's security layers will naturally block these calls by default.

• The Technical Friction: If the CSP is set to "Strict," the window.median object will be stripped or blocked, rendering native features like biometrics or push notifications non-functional.

Implementation:

1. Navigate to Experience Builder > Settings > Security & Privacy.
2. Set the Security Level to Relaxed CSP.
3. In the Trusted Sites for Scripts section, add the Median distribution URLs. This explicitly tells the Salesforce framework that the Median bridge is a verified actor.

Lightning Web Components (LWC) & Median JavaScript Bridge

Lightning Web Components (LWC) operate within a sandboxed environment known as Lightning Locker (or the more modern Lightning Web Security - LWS). This sandbox prevents a component from accessing global variables outside its immediate namespace.

The Problem: Your LWC might attempt to call median.deviceInfo(), but because of the sandbox, median appears as undefined.

The Technical Solution: * Enable LWS: If your Org allows it, enable Lightning Web Security (Setup > Session Settings), as it provides better support for standard cross-window communication than the legacy Locker Service.

Global Access: Always reference the bridge via window.parent or window.top to ensure the call escapes the component's virtual DOM and reaches the WebView's primary execution context.

Deep Linking via Apple Site Association (AASA) & Asset Links

For Deep Linking (ensuring links to your site open the app rather than the mobile browser), you must prove ownership of the domain by hosting a specific JSON file at /.well-known/apple-app-site-association (AASA).

The Challenge: Salesforce Experience Cloud is a closed file system. You cannot simply FTP a file into the root directory.

The Solution:

1. Visualforce Hosting: Create a public Visualforce page with contentType="application/json".
2. Apex Controller: Use an Apex controller to return the raw JSON string required by Apple or Google.
3. URL Rewriting: Use the Site URL Rewriter Class or Custom URL Redirects in Salesforce Setup to map the system path (/.well-known/apple-app-site-association) to your Visualforce page.