The Visitor API of the yalst Live Support Tool

Overview

The Visitor API is a Javascript library which consists of methods for accessing and integrating the yalst live support system in web pages on the visitor side.

A visitor is a user of your web site who may ask for assistance or whose activity you want to observe.

The Visitor API is not intended for the communication between the visitor and the support operator - for that purpose there is for instance the Chat API - but to provide a program interface for all steps to prepare and initiate such a communication.

Changes in the hosting page

except for the startControlling function the api adds a single global Javascript variable LiveSupport
If the page uses RequireJS the Visitor API must load after RequireJS' data-main script file. (The API uses its own version of RequireJS under the namespace LiveSupport)

Page integration

In the first code snippet below you see how the API is defined and loaded (asynchronously i.e. without blocking DOM loading and rendering by the browser) in a website. See this article on CSS-Tricks.com

Integration code:

    ////// Definitions //////
    if (typeof LiveSupport == "undefined"){
        LiveSupport = {};
    }
    if (typeof LiveSupport.VisitorAPI == "undefined"){
        LiveSupport.VisitorAPI = {};
    }
    if (typeof LiveSupport.VisitorAPI._methodQueue == "undefined"){
        LiveSupport.VisitorAPI._methodQueue = [];
    }
    LiveSupport.VisitorAPI.invoke = function(method, parameterArray, callback){
        if (typeof method != "string"){
            if (typeof callback == "function"){
                callback(new Error("invalid argument: 1 must be string"));
            }
            return;
        }

        LiveSupport.VisitorAPI._methodQueue.push({
            method: method
            , parameters: parameterArray
            , callback: callback
        });
    };
    ////// Script Loading //////
    (function(){
        var YALST_INSTALLATION_URL = "//YourYalstDomain/YourYalstDirectory/";
        var anchorElement = document.getElementsByTagName('script')[0];
        var script = document.createElement("script");
        script.src = YALST_INSTALLATION_URL + "visitor_api/v2/built/LiveSupport.js";
        script.setAttribute("data-main", YALST_INSTALLATION_URL + "visitor_api/v2/built/LiveSupportMain");
        anchorElement.parentNode.insertBefore(script, anchorElement);
    })();

Api Hello world

In this example if a support operator of department "C" is available an initially deactivated "Assist Me" button is configured activated. You must insert the appropriate values for the location of your yalst server directory as well as your 'site id' and the 'department id'.

////// Example use of the API //////
// while the API is not yet loaded one must schedule method calls
// through the special method 'invoke'
// IMPORTANT: Always associate the API to a particular yalst Live Support product first,
// BEFORE calling any other method!
LiveSupport.VisitorAPI.invoke('associateWithLiveSupportProduct'
        , ["https:" + YALST_INSTALLATION_URL, "YourYalstSiteId"]
        , function(){
            // at this point the API is loaded by the browser and
            // calls do no longer need to go through 'invoke'
            LiveSupport.VisitorAPI.getOperatorAvailability(onAvailabilityDetected, "C");
        });

function onAvailabilityDetected(status){
    if (status instanceof Error){
        alert("An error has occurred:" + status.toString());
    }
    else if (status == LiveSupport.VisitorAPI.Availability.AVAILABLE){
        var startButton = document.getElementById('start_button');

        startButton.removeAttribute("disabled");

        registerListenerForGUIEventOnElement(function(){
            LiveSupport.VisitorAPI.startLiveChat();
        }, 'click', startButton);
    }
}

Here is the HTML markup for the "Assist Me" button:

<button id="start_button" disabled="disabled">Assist Me</button><br/>

History

Changes in Version 2.0

fixed co-existence with a client page's own RequireJS library
reduced size by minifying Javascript sources
added support for Internet Explorer 11
added boolean parameter direct for startLiveChat

Index