Integrating SwitchLive

JavaScript Library Initialization

Adding SwitchLive to new Locally installations

If you are setting up a brand new Locally integration with SwitchLive included, your Locally rep can assist you with creating widget embed code that will properly load the required SwitchLive Javascript assets.

Adding SwitchLive to existing Locally installations

Updating your embed code to load SwitchLive JS Assets

If you have an existing Locally Product Locator or Store Locator installation and already have widget embed code, your widget embed code must be updated to include the following script tag which will load switchlive.js and switchlive-events.js

<script id="lcly-script-switchlive-0" async></script>
<script id="lcly-script-switchlive-events-0" async></script>

<script id="lcly-switchlive-config-0">
    var lcly_switchlive_events_endpoint_0 = 'https://{{ $base_address }}/switchlive/switchlive-events.js?company_id={{ $company_id }}';
    var lcly_switchlive_endpoint_0 = 'https://{{ $base_address }}/js/switchlive.js?company_id={{ $company_id }}';

    document.getElementById('lcly-script-switchlive-0').src = lcly_switchlive_endpoint_0;
    document.getElementById('lcly-script-switchlive-events-0').src = lcly_switchlive_events_endpoint_0;
</script>

{{ $company_id }} should be replaced with your unique Locally company id, which is an integer.

{{ $base_address }} should be replaced with the same base URL used in your existing widget embed code.

NOTE: If SwitchLive has not yet been enabled in the Locally admin, these JS assets will load without error, but SwitchLive event tracking will not initialize and begin tracking and emitting events.

Updating your existing Product Locator to emit impressions when loaded

If you would like to receive a SwitchLive event when the PL is loaded onto your page, the element lcly-submit-0 in your existing widget embed code must have the following data attributes added to it:

<... data-switchlive="true"  
data-switchlive-impression="true"  
data-switchlive-impression-id-PL="1">

If needed, please contact your Locally rep for assistance with updates to your widget embed code to get SwitchLive loading.

SwitchLive Event Model

Each event emitted by SwitchLive will have the following properties:

Property	Description
`id`	Event identifier. A comprehensive list of event codes is included at the end of this page in the SwitchLive Events section.
`scope`	Event scope. This indicates the Locally interface which generated the event. Possible values: `PL` (Product Locator) `SL` (Store Locator) `LLP` (Locally Landing Pages / Hosted Domain)
`type`	Event type. Possible values: `impression` `browser` `click` `change` `submit`
`description`	Locally’s verbose description of the Event.
`timestamp`	JavaScript Date string produced using `Date.now();` The `Date.now();` method returns the number of milliseconds elapsed since `January 1, 1970 00:00:00 UTC`. Example: `1622055133089`
`url`	Current URL, collected via JavaScript. `const url = window.location.href;` Important note: This URL will contain the full URL including all query parameters. You are responsible for the usage of this data and should exercise caution when transmitting data to external systems if your query parameters contain sensitive information such as personal-identifying-information (PII).
`locale_code`	User's locale code, as inferred by Locally's widgets / interfaces. Will be of the form `en_us`
`product_id`	If available, the product identifier that was passed to Locally and is available in the Locally JavaScript context.
`style`	If available, the style number that was passed to Locally and is available in the Locally JavaScript context.
`upc`	If available, the UPC code that was passed to Locally and is available in the Locally JavaScript context.
`store_id`	If available, the store identifier that was passed to Locally and is available in the Locally JavaScript context.
`store_address`	If available, the address of the store that was passed to Locally and is available in the Locally JavaScript context
`store_name`	If available, the name of the store that was passed to Locally and is available in the Locally JavaScript context
`vendor_id`	If available, the unique 'vendor_id' assigned to the store by the brand that was passed to Locally and is available in the Locally JavaScript context
`store_stock_status`	If available, this indicates if a store has stock of the current upc. Possible values: `true` `false`
`store_stock_count`	If available, integer quantity of upc available at current store.
`company_id`	If available, the company identifier that was passed to Locally and is available in the Locally JavaScript context.
`utm`	If available, any UTM tracking code that Locally detects is present during the user session. Includes any of the following parameters if available: `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, and `utm_term`

SwitchLive Event Example

{
    'id': '1234',
    'scope': 'PL',
    'type': 'click',
    'description': 'Modal - user click on a specific element',
    'timestamp': '1622662506828',
    'url': 'https://www.example-url.com?includes=query_params',
    'product_id': '12345',
    'style': '654321',
    'upc': '9876543210',
    'store_id': '987654',
    'store_stock_status': 'true',
    'store_stock_count': '25',
    'company_id': '1234'        
}

Sample Code

Once enabled, SwitchLive is continually emitting events. To execute your own custom code when SwitchLive events are emitted, there are two approaches that we recommend.

You may define a JavaScript function called switchLiveEventCallback() which accepts a parameter of switchLiveEvent. SwitchLive will call your function whenever a SwitchLive event is emitted.

var switchLiveEventCallback = function( switchLiveEvent ){

    /* PSEUDO-CODE ONLY - your custom code will go here */

        // trigger events in your webapp based on user interactions with Locally's interfaces!
        if ( switchLiveEvent.id == '123' ){
            alert('Thanks for using the map.  Here's a promo code.');
        }

        // deconstruct the switchLiveEvent and log data to your analytics tracking service! 
        // (example syntax only.  please reference your analytics provider's docs for the JS syntax you need.)
        heapTrackAPI.send( switchLiveEvent.type, switchLiveEvent.product_id);
        googleAnalyticsAPI.send( “pdpFunnel”, switchLiveEvent.type, switchLiveEvent.upc );

    /* PSEUDO-CODE ONLY - your custom code will go here */

}

Alternatively, you may opt to write a JavaScript event listener that listens for events of type message. Events emitted from SwitchLive will have data.message_type=switchlive.

if (typeof window.receiveSwitchLiveEvent != 'function'){
    window.receiveSwitchLiveEvent = function( eventMessage ){
        if (typeof eventMessage.data.message_type != 'undefined' && eventMessage.data.message_type == 'switchlive'){
            var switchLiveEvent = eventMessage.data;

            // do custom work here!

        }
    }
}
window.addEventListener("message", window.receiveSwitchLiveEvent, false);