Salesforce Overlay Integration Guide

Preface

This document provides a step-by-step guide to integrating the Newired Overlay into a Salesforce application using a snippet. The approach follows the same principles as described in this article, but with specific adjustments for Salesforce’s extension system.

Prerequisites

Content URL

Prepare the Newired Content URL, which provides access to Newired Content (typically the Newired Portal). You can find the Newired Content URL in:

Newired Portal → Site → Deployment → Snippet text area.

 

Static Resources

Due to Salesforce security policies, external JavaScript files must be uploaded as static resources. These resources are tied to the Overlay version, meaning that unless the Newired Portal is updated, there is no need to modify the static resources.

Steps to Prepare Static Resources:

1. Download the deployment file: newired-launcher-v<version>.zip from the Newired Portal.

2. Extract the required files from the ZIP archive for Salesforce static resources.

Deployment

Trusted URLs

To allow Newired Overlay to load from the content delivery network, you must add the Newired Content URL to Trusted URLs in Salesforce.

Steps:

1. Open Salesforce Application Setup.
   
   
   
   

2. Locate Trusted URLs and add a new URL.
   
    

   
   
   

3. Enter the Newired Content URL and save the changes.
   
    

   
   
   

Create nw-loader.js

Since Salesforce enforces strict security policies on external scripts, create a loader script to handle dynamic content loading.

Steps:

1. Create a JavaScript file named nw-loader.js.

2. Insert the following content:

(function (currentScript) {
    'use strict';
    const logContext = '[loader]';

    function resolveContentVersion(contentUrl, metadata) {
        return new Promise((resolve, reject) => {
            getPreviewVersion(contentUrl)
                .then(preview => {
                    resolve({
                        contentUrl: preview.contentDeliveryUrl + '/' + preview.siteId,
                        contentVersion: preview.versionId
                    });
                })
                .catch(error => {
                    if (metadata.liveVersion) {
                        resolve({
                            contentUrl: contentUrl,
                            contentVersion: metadata.liveVersion
                        });
                    } else {
                        reject(error);
                    }
                });
        });
    }

    window.loadContentVersion = function (options = {}, onReady) {
        const contentUrl = options.contentUrl;
        resolveContentVersion(contentUrl, {}).then(versionInfo => {
            options.contentUrl = versionInfo.contentUrl;
            options.contentVersion = versionInfo.contentVersion;
            options.overlayApiEnabled = typeof options.overlayApiEnabled === 'boolean' ? options.overlayApiEnabled : true;
            onReady(options);
        }).catch(reason => {
            console.warn('Unable to load Newired Overlay:', reason);
        });
    };
})(document.currentScript);

3. Save the file for later upload to Salesforce Static Resources.

Upload Static Resources

Extract the following files from the ZIP archive:

• storage.bundle.js

• launcher.app.js

• overlay.bundle.js

• init.js

Steps:

1. Open Salesforce Application Setup.

   
   
   
   

2. Navigate to Static Resources and create the following entries:

   • content/<version>/init.js → nw_init

   • content/<version>/storage.bundle.js → nw_storage_bundle

   • content/<version>/launcher.app.js → nw_launcher_app

   • content/<version>/overlay.bundle.js → nw_overlay_bundle

   • Salesforce loader (nw-loader.js) → nw_loader
     
       

Create a Lightning Component

Steps:

1. Open Development Console.
   
   
   
   

2. Create a new Lightning Component.
   
   
   
   

3. Update the component (<component-name>.cmp) with the following code:

<aura:component implements="flexipage:availableForAllPageTypes">
    <aura:handler name="init" value="{!this}" action="{!c.doInit}"/>
    <ltng:require
        scripts="{!join(',', $Resource.nw_init, $Resource.nw_storage_bundle, $Resource.nw_launcher_app, $Resource.nw_loader, $Resource.nw_overlay_bundle)}"
        afterScriptsLoaded="{!c.startOverlay}"/>
</aura:component>
    

4. Create the controller in Development Console (shortcut: Ctrl + Shift + 2).
   
   
   
   

5. Insert the following controller code:

({ 	doInit: function(component, event, helper) {
        window.targetWindow = window  
        window.targetDocument = document
        window.environment = "browser-webextension-isolated"
    },
             
    startOverlay : function(component, event, helper) {
       const options = {
             contentUrl: "<site delivery URL>" 			 
		} 
      window.loadContentVersion(options,(startingOptions)=>{              
          const options = {
  			 contentUrl: startingOptions.contentUrl,
 			 contentVersion: startingOptions.contentVersion, 
   		     backend: startingOptions.backend
		} 
          		window.nwinit.startOverlay(options)        
       })        
	}    
})

6. Update contentUrl with the actual site delivery URL from the Newired Portal (e.g., https://example.newired.com/content/10177).

7. Save all changes (File → Save All) and close the Developer Console.

Add the Lightning Component to a Lightning Application

Steps:

1. Locate the desired Lightning Application in App Manager and edit it.
   
   
   
   

2. Add NWOverlay as a new Utility Item.
   
   
   
   
   
   

3. Configure the new item and save the settings.
   
   
   
   

4. Verify within the Salesforce application that the Newired Overlay is visible.
   
    

Conclusion

By following these steps, you will successfully integrate the Newired Overlay into Salesforce. If any issues arise, ensure that:

• All required static resources are uploaded correctly.

• The Lightning Component and controller are properly configured.

• The Newired Content URL is set in Trusted URLs.

For further troubleshooting, refer to the Newired Support Portal.