Locally SwitchLive Documentation

Overview

What is Locally SwitchLive?

SwitchLive is a client-side event-tracking library which is deployed to monitor end-user interactions with Locally’s public-facing user interfaces, such as the Store Locator, Product Locator and Locally Landing Pages tools.

As a brand’s end-users interact with Locally’s SL, PL or LLP interfaces, SwitchLive continuously emits events, which may be monitored or utilized by the brand’s own web application code. SwitchLive provides a straightforward interface and pattern for web application owners to execute their own business logic when interactions occur with Locally's interfaces. Using the instructions in this document, Locally’s brand partners may collect, track, or directly act upon the events emitted by SwitchLive.

SwitchLive is implemented in JavaScript and is environment, browser and device agnostic. SwitchLive is implemented using non-blocking asynchronous patterns.

Prerequisites

SwitchLive may be added to your existing Locally subscription as an additional service. Please contact your Locally account manager to have this enabled.

Enabling SwitchLive

Once SwitchLive has been added to your subscription, your Locally Support Manager will enable this feature for your tools and you can proceed to integrating this on your live site.

Integrating SwitchLive

JavaScript Library Initialization

NOTE: SwitchLive must be enabled from the Locally.com admin.

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 id="lcly-script-switchlive-events-0" async />
<script id="lcly-switchlive-config-0">
    var lcly_switchlive_events_endpoint_0 = 'https://www.{{ $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').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.

Values:
PL (Product Locator)
SL (Store Locator)
LLP (Locally Landing Pages)
type Event type.

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_stock_status If available, this indicates if a store has stock of the current upc.

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.

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.

  1. 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 */

} 
  1. 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);

SwitchLive Events

Scope Id Type Description
LLP 57 impression Modal - inline store locator loaded
LLP 60 click Modal - store detail view - user click on Store 'Browse Stock' button
LLP 62 impression Modal - browse inventory - product loaded / product impression
LLP 64 click Modal - browse inventory - user click on Product Thumb
LLP 67 impression Modal - Locally Product Detail Page opened
LLP 69 click Modal - Locally product detail page - user click on `Buy Now`
LLP 72 click Modal - Locally product detail page - user click on `ROPIS`
LLP 74 click Modal - Locally product detail page - user click on `Call Store Now`
LLP 76 impression Modal - store loaded / store impression
LLP 78 click Modal - user click on Store link (opens details panel)
PL 1 impression PDP - Locally widget loaded on PDP
PL 4 click PDP - user click on Store link
PL 5 click PDP - user click on location change
PL 6 click PDP - user click on 'show all local options'
PL 7 impression Modal - Product Locator modal loaded
PL 9 click Modal - user click on Store link (opens details panel)
PL 21 click Modal - store detail view - user click on Store 'Browse Stock' button
PL 38 click Modal - browse inventory - user click on Product Thumb
PL 41 click Modal - product detail view - user click on `Buy Now`
PL 46 click Modal - product overview view - user click on Call Store Now button
PL 47 click Modal - product overview view - user click on Buy Now button
PL 48 impression Modal - browse inventory - product loaded / product impression
PL 49 impression Modal - product overview view - store loaded / store impression
PL 65 impression Modal - Locally Product Detail Page opened
PL 70 click Modal - Locally product detail page - user click on `ROPIS`
PL 79 click Modal - product overview view - user click on ROPIS button
SL 56 impression Modal - inline store locator loaded
SL 59 click Modal - store detail view - user click on Store 'Browse Stock' button
SL 61 impression Modal - browse inventory - product loaded / product impression
SL 63 click Modal - browse inventory - user click on Product Thumb
SL 66 impression Modal - Locally Product Detail Page opened
SL 68 click Modal - Locally product detail page - user click on `Buy Now`
SL 71 click Modal - Locally product detail page - user click on `ROPIS`
SL 73 click Modal - Locally product detail page - user click on `Call Store Now`
SL 75 impression Modal - store loaded / store impression
SL 77 click Modal - user click on Store link (opens details panel)