Newired Salesforce Overlay Installation

Modified on Tue, 30 Jun at 10:01 AM

This guide explains how to install Newired Overlay into a Salesforce app from the deployment ZIP provided by Newired.

What Newired Provides

Newired provides a ready-to-deploy Salesforce metadata package, for example:

newired-salesforce-package-1.0.0-SNAPSHOT.zip

The package contains:

Newired Overlay Lightning Web Component
newiredOverlay Static Resource with the Overlay runtime assets

Prerequisites

Access to the target Salesforce org.
Permission to deploy Salesforce metadata.
Permission to update Salesforce Trusted URLs and Trusted URLs for Redirects.
The Newired Content URL for the published site.

Example Content URL:

https://newired.example.com/content/475

This URL comes from the Newired content delivery configuration. The Salesforce component uses it to resolve live published content.

1. Configure Salesforce Trusted URLs

Salesforce Lightning applies Content Security Policy rules to Lightning components. Add the Newired hosts used by the integration to Salesforce Trusted URLs before testing the component.

Open Setup.
Search for Trusted URLs.
Open Trusted URLs.
Add the host from the Newired Content URL.
Add the host from the Collector URL, if analytics collection is used.
Add any additional Newired runtime, API, object storage, image, media, font, or stylesheet hosts provided for your Newired deployment.

These additional hosts are not separate Lightning App Builder properties. They can be part of the Newired environment behind the configured Content URL or referenced by published Newired content. Newired should provide the exact host list for the customer environment.

Recommended CSP directives:

connect-src for the Newired Content URL, Collector URL, and any Newired service or storage endpoints used by the deployment.
frame-src for Newired frame content, including cross-domain storage or runtime frames if used.
img-src when Newired content loads images from Newired or object storage hosts.
media-src when Newired content loads video or audio assets.
font-src when Newired content loads fonts.
style-src when Newired content loads external stylesheets.

The Overlay JavaScript runtime is loaded from the Salesforce Static Resource, so the Newired content host is not used as a remote script source for the LWC startup.

2. Configure Trusted URLs for Redirects

If Newired journeys, launchers, or actions can redirect users to external URLs, add those target hosts to Salesforce Trusted URLs for Redirects.

Open Setup.
Search for Trusted URLs for Redirects.
Add the external hosts that Newired actions are allowed to open through Salesforce redirection flows.

This step is required only for URLs that Salesforce treats as external redirection targets. Direct links may not require this allowlist, but blocked redirections are reported by Salesforce as Trusted URL or browser policy violations.

3. Deploy the Package

Deploy the ZIP using the Salesforce deployment tool used by your organization, for example:

Salesforce CLI
Workbench Metadata Deploy
Gearset
Copado
another Metadata API deployment tool

Salesforce CLI example:

sf project deploy start --metadata-dir newired-salesforce-package-1.0.0-SNAPSHOT.zip --single-package --target-org customer-org

Run the Salesforce CLI command from a Salesforce DX project folder. If your organization uses another Metadata API deployment tool, use that tool's ZIP deployment flow instead.

4. Open Lightning App Builder

In Salesforce:

Open Setup.
Search for Lightning App Builder.
Open Lightning App Builder.
Open the target Home page.
Click Edit.

5. Add Newired Overlay to the Home Page

In the component list, find Newired Overlay.
Drag the component onto the Home page.
Configure the component properties.

Example configuration:

Content URL: https://newired.example.com/content/475
Collector URL: https://newired.example.com/collector/collector.js
User Identity Strategy: currentUserEmail
Launcher Visible: true
Overlay API Enabled: true
Additional Page Script Enabled: false
Loader Spinner Enabled: false
Loader Spinner Position: BOTTOM_RIGHT
Loader Spinner Primary Color:
Loader Spinner Secondary Color:
Loader Spinner Size:
Loader Spinner Delay:
Loader Spinner Tooltip:

Component Properties

Content URL

Newired content delivery URL for the published site.

Example:

https://newired.example.com/content/475

Collector URL

Optional Newired collector snippet URL used to enable analytics data collection.

Example:

https://newired.example.com/collector/collector.js

Leave empty when analytics collection is not required for the Salesforce integration.

User Identity Strategy

Defines which Salesforce user value is passed to Newired Overlay as the user identity.

Default:

currentUserEmail

Supported values:

currentUserEmail
currentUserName
currentUserUsername
currentUserId
none

Use none when users should identify themselves manually in Overlay or when Salesforce identity must not be sent to Newired.

Loader Spinner Enabled

Controls whether a temporary Newired loading spinner is shown while Overlay starts. Enable only when users need a visible loading indicator during Overlay startup.

Default:

false

Loader Spinner Position

Position of the temporary loading spinner on the page.

Default:

BOTTOM_RIGHT

Supported values:

BOTTOM_RIGHT
BOTTOM_LEFT
TOP_RIGHT
TOP_LEFT

Loader Spinner Primary Color

Optional CSS color used for the spinner primary circle.

Default:

#C8C8C8

Loader Spinner Secondary Color

Optional CSS color used for the spinner secondary circle.

Default:

#303030

Loader Spinner Size

Optional spinner size in pixels.

Default:

Loader Spinner Delay

Optional delay in milliseconds before the spinner is shown.

Default:

Loader Spinner Tooltip

Optional tooltip shown when hovering over the spinner.

Default:

Your help is loading...

6. Save and Activate

Click Save.
Click Activation.
Assign the Home page to the required app, org default, or profiles.
Finish activation.

7. Verify

Open the Salesforce app Home page.

Expected result:

Newired Overlay starts.
Newired launcher is visible when enabled.
Browser console does not show a fatal Newired startup error.
The scope iframe is loaded from Salesforce Static Resource, for example:

https://your-org.lightning.force.com/resource/.../newiredOverlay/overlay/scope.html

If startup is blocked, check:

Browser console CSP errors.
Salesforce Trusted URL and Browser Policy Violations.
Whether the Content URL and Collector URL hosts are added to Trusted URLs with the required directives.
Whether redirect targets are added to Trusted URLs for Redirects when Newired actions open external URLs.

Salesforce Startup Modes

Supported Salesforce startup:

LWC + Salesforce Static Resource
Chrome extension isolated mode may work because it does not inject remote loader.js into the Salesforce page, but the recommended Salesforce integration is the LWC/static-resource deployment.
Chrome extension snippet mode is not a supported Salesforce startup path because Salesforce CSP can block remote page-script loading.

Newired Limitations in Salesforce App

Additional Page Script Support

The Additional page script is custom JavaScript configured in Newired Portal under the Site Advanced Settings.

In the Salesforce LWC integration, this script is disabled by default. It is requested only when Overlay API Enabled and Additional Page Script Enabled are both enabled in the Lightning component configuration.

The script is downloaded from the Newired content delivery environment and executed within the target Salesforce page context. Salesforce Lightning Content Security Policy (CSP) restrictions may prevent this type of dynamically delivered JavaScript from being loaded or executed.

The Overlay runtime itself is loaded from the newiredOverlay Salesforce Static Resource included in the deployment package. The Additional page script is separate from the packaged Overlay runtime.

The script remains configurable in Newired Portal:

Open the target Site in the Newired Portal.
Open Advanced Settings.
Locate the Additional page script field.

If the script is required in Salesforce, enable it in the Lightning component and validate the behavior in the target Salesforce environment.

Plugin Support

Newired Plugins are delivered from the Newired content delivery environment and are requested by Overlay in the same way as in a standard deployment.

Depending on the Salesforce environment configuration and applicable Lightning Content Security Policy (CSP) restrictions, plugin JavaScript resources may be prevented from loading or executing within the Salesforce application.

As a result, plugin-based functionality may not be available in all Salesforce environments.

Customers using Overlay content that depends on Newired Plugins should validate plugin behavior in their Salesforce environment as part of deployment testing.