Home/API
API2017-05-12T19:11:18+00:00

About the Lucep library

The Lucep library is designed to allow any form on a website, or any specific interaction, to send leads directly to sales people so that customers can be converted faster. This could be from anything to with an enquiry form being completed, to a new signup being completed prompting the team to welcome the new registrant, all the way through to a registered user abandoning a cart.

Whatever the circumstance is that you believe requires immediate personalised attention, the Lucep library facilitates that exercise by driving immediate engagement from your team.

Loading the library

The JavaScript library can be loaded in two ways, and which one you choose will depend on your site and expected user interaction.

Dynamic loading (load speed friendly / default)

The following snippet will load the library as a dynamic script on the page; this is typically used when the primary focus is related to the speed of the page loading and is usually considered best practice. The reason why this helps perceived page load speed is because it is downloaded in parallel with all other page content – and does not prevent other scripts or objects being loaded before it. Where the functionality of the page does not depend on the library being immediately available, this is usually a good option.

(function (l,u,c,e,p){ ... })(a,b,c,d,e);

The callback is fired immediately after the browser has finished downloading the script (not necessarily completely loaded it) and is an opportune place to either fire any other dependent scripts, or bind buttons with events.

Included in the header (easiest)

Including the Lucep JS library in the header guarantees its availability on the page to every script called after it, but has the downside of blocking page load until it is downloaded. The impact of this is usually only seen once, and it is cached by the browser for subsequent loads.

To include the script in the page header simply add this between the <head> </head> tags:

<script type='text/javascript' src='https://8d69a4badb4c0e3cd487-efd95a2de0a33cb5b6fcd4ec94d1740c.ssl.cf2.rackcdn.com/js/L.SalesGorilla.stable.latest.min.js'></script>

A note on build channels

Two channels are actively maintained, and they are referred to as follows: Stable The stable channel contains the most thoroughly tested and reliable version of the library. It is updated more slowly, but only updated when backward compatibility is assured and has been tested as a working library. The stable library is available from https://8d69a4badb4c0e3cd487-efd95a2de0a33cb5b6fcd4ec94d1740c.ssl.cf2.rackcdn.com/js/L.SalesGorilla.stable.latest.min.jsBleeding The bleeding channel contains builds that can be considered as being in the middle of development. Cool new features are added to this library on an ad hoc basis, but they may not completely work, may not even be documented, and almost always run the risk of breaking other functionality – some may never make it over to the stable channel. It is really only recommended for development purposes and to get a peek under the hood of what is coming next The bleeding library is available from: https://8d69a4badb4c0e3cd487-efd95a2de0a33cb5b6fcd4ec94d1740c.ssl.cf2.rackcdn.com/js/L.SalesGorilla.bleeding.latest.min.js

Checking if the library is loaded

Depending on how the library is included, it may be necessary for you to check if the library is available before performing any actions with it.

Listening for the library announcement

The Lucep library will announce it is available by firing the event lucep-library-ready on the document, so it is possible to create an event listener for this:

    document.addEventListener("lucep-library-ready", 
                              function(){
                                //the library is ready, do something here
                              }, false);

NOTE: This is not compatible with browsers IE9 and before Please check compatibility with your target browsers.

Checking for object existance

Checking if $lucep is available as an object is a simple and effective way to validate the library is available for use

    if ($lucep) {
      //the library is available, do something
    }

A combined approach to work with the library

A reliable way to work with the library is to combine these two ways of checking for the availability of the library:

    if ($lucep){
      //launch your custom event
    } else {
      document.addEventListener("lucep-library-ready", 
                                function(){
                                  //launch your custom event
                                }, false);
    }

Initialising the library

The Lucep library requires to be initialised before it can be used, and it can be initialised by providing only the account name with which it should be used.

$lucep.init( { domain: YOUR-DOMAIN-HERE } );

The init function can be called repeatedly without any adverse impact, as only the first call is processed.

Once the init method is fired, all of the other library methods can be used. It is recommended that the init function is fired as early as possible as this will prevent long waiting times for other functions to complete.

$lucep.init ( params )

This method can be invoked multiple times – however only the variables passed in the first call are considered. All other subsequent calls are ignored.

params should be a JavaScript object with the following properties:

Property NameRequiredDescriptionExample/Default
domainYesThe account to bind all subsequent actions tomydomain (no default)
idRecommendedThe kiosk identifier which contains all the settings that should be applied to this instance. This can also impact the widget UI if it is loaded, as the ID drives what menu is loaded, and associated visual config1
langRecommendedThe default language to load any UI components in, and request strings from the server ineng
no_uiNoInstructs the library to load the default UI when set to false, by default no UI is loaded as the parameter is set to truetrue
mobileNoInstructs the library to not load any of its own dependencies from the internet, and reference relative URLs only, by default this is not the casefalse
load_uiNoPath to a custom UI library to load. See CornerWidgetUI for an example of how such a library can be structuredfalse
callbackNoCallback function to receive updates on the various components that the library will load as it starts upnull

$lucep.raise_lead ( params )

Immediately raises a lead to the appropriate team based on the service_id supplied. Notifications are pushed directly to the relevant users as defined in the Lucep console.

params should be a JavaScript object with the following properties:

Property NameRequiredDescriptionExample/Default
phone_numberYesThe international dialling number that the customer should be called back on.+1 213 555 1234 (no default)
nameYesThe name of the customer to be asked for when calling backJohn Appleseed (no default)
service_idYesThe ID of the requested service by the customer. This ID determines which group of people in the organisation receive the lead/notification1 (no default)
service_nameYesThe user-friendly name of the service that the customer has requested forBill payment (no default)
additional_infoNoAny additional personal information about the user that would be useful for the company representative. To be sent in JSON name/value pairs.{"e-mail": "bob@bob.com","Home town": "London"}
callbackRecommendedA callback to receive confirmation of lead creation, and updates on the lead processing status as it progresses through the lifecycle of being created, retrieved by a representative, and then closed. If supplied, the callback is supplied in the format `{“ticket-status”: [new / processing / finished ], “server”: truefalse}-see$lucep.get_ticket_statusformore info : function (resp){ … }`

$lucep.send_intelligence ( params )

Sending intelligence instructs the server to maintain a record of a specific significant event with this particular customer. This event is communicated to the sales person when a lead is raised by user in question. This could be anything from a customer scrolling past a particular point on a page, to the customer viewing a specific image. The general guidance is to send events that will be relevant, and helpful, the person that is going to be reviewing the lead ahead of engaging with the customer.

NOTE: It is important to recognise that personally identifiable information should not be sent as data in this method

params should be a JavaScript object with the following properties:

Property NameRequiredDescriptionExample/Default
event_typeYesA user friendly headline description of what the event type isviewed image (no default)
payloadRecommendedA JSON formatted set of key/value pairs that describe the event{"your-property": "your information"} (no default)
callbackNoA callback to your function once the server has acknowledged receipt of the intelligencefunction (resp) { ... } (no default)

$lucep.put_data ( params )

This method stores data in the browser for retrieval between sessions. It allows for custom identifiers or references to be placed within browser storage using your custom key references. The library will detect if the browser supports WebStorage[1][2] and use that if available, else it will fall back to Cookies.

This method can be called any number of times, it does not return any data. If the method is called multiple times with the same key, it will overwrite the data stored by the previous call.

params should be a JavaScript object with the following properties:

Property NameRequiredDescriptionExample/Default
keyYesThe key to store the data withyour-key-here (no default)
valueYesThe value to store (text only){"your-property":"your property details"} (no default)

$lucep.get_data ( params )

This method retrieves data that has been stored using $lucep.put_data method. It returns the value associated with the key as a result of the function call.

params should be a JavaScript object with the following properties:

Property NameRequiredDescriptionExample/Default
keyYesThe key the data has been stored withyour-key-here (no default)

The method will then return the value string that was previously associated with the key (if any)

$lucep.get_kiosk_details ( params )

Once initialisation has completed, the details of the kiosk can be passed to a callback so that necessary actions can be taken to render it or incorporate it into the page as needed. This function can be called as many times as needed, and as soon as the kiosk is available, all the callbacks will be fired sequentially.

params should be a JavaScript object with the following properties:

Property NameRequiredDescriptionExample/Default
callbackYesA custom function to handle the kiosk information when it is successfully loaded/retrieved from the Lucep serverfunction (resp){ ... }(no default)

When the callback is triggered, an object describing the kiosk properties will be supplied. Kiosk properties can be customised as needed on the Lucep console – this means that a kiosk can return as many, or as few, properties as needed for your implementation. An example of how this object can be structured is as follows:

Property NameDescriptionReference Example
default_langThe default language that the kiosk text should be displayed in, and the language pack guaranteed to have all necessary texteng
kiosk_idThe unique identifier for the kiosk that has been retrieved. Multiple different types of kiosks can be configured on the server, each with different properties as needed1
button_ctaThe text desired on the call to action buttonCall me!
colorThe desired colour properties of the widget in hexadecimal format. Different properties can be configured for each kiosk as needed.{"background": "#000"}
extra_fieldsAdditional fields to solicit information on from the user. This will be a structured object. Enforcement is up to your implementation and will not be validated by the server or the Lucep library.{ "dom-property-id": {"label": "User friendly label","type":"text/checkbox/dropdown", "help_txt": "Any applicable help text (optional)", "options": [{"option1-id":"Option 1 User Text"}] } }
closed_txtThe text to be displayed by the widget when it is minimised. This may not be applicable in all scenarios.Click here to get a callback!
open_txtThe text to be displayed by the widget when it is expanded. This may not be applicable in all scenarios.Tell us how to contact you!

The extra_fields property

Extra fields is a kiosk configuration property that is used to instruct the webpage that some additional data is required in order for the submission to be useful to the person processing the customer’s request. Enforcement and use of this is down to your implementation, and it is not validated by the Lucep library or servers. In most circumstances, the accompanying data is fired as additional_info when a lead is raised – but this must be implemented by you.

Property NameDescriptionReference Example
dom-property-idThis is the property-id that is expected to be submittedemail

Within the dom-property-id another object is nested that contains additional descriptors:

Property NameDescriptionReference Example
labelThe user-friendly label for this fieldYour email address
typeThe type of field that should be presented to the user. This can be customised by you on the Lucep console, but a few default options exist, e.g. text, checkbox, dropdowntext
help_txtSome additional help text to supply to the user (if any)An email address looks like "bob@bob.com"
optionsFor checkboxes or dropdowns, options need to be provided. By default, these are supplied as id/reference pairs in an object array.[{"my-option1": "A nice option 1"},{"awesome-option2" : "get me a number 2"}]

$lucep.get_ticket_status

Performs a check on the last known lead processing status. Returns synchronously with an object describing the state. The object looks as follows:

Property NameDescriptionReference Example
statusA descriptor of the lead state that can be any one of the following: new, processing, finished, no-ticketprocessing
serverAn indicator if this return is fresh from the server, or if it is a cached response based on the last action taken. Cached responses are the standard and are generally reliable indicators, and so expect a false in this fieldfalse

$lucep.create_profile ( params )

This method should not need to be called on a regular basis.

create_profile purges any record of the existing customer profile from the browser, and requests for the server to create an entirely one. This forces references to any previous intelligence or leads to be lost.

As customer behaviour profile identifiers are securely generated, and correlating them with leads is a one-way process this process can not be undone, and once executed, past customer information is only available in an anonymised aggregated format.

params should be a JavaScript object with the following properties:

Property NameRequiredDescriptionExample/Default
callbackRecommendedA custom function to receive notification when the old customer profile has been purged and a new one has been createdfunction (resp){ ...} (no default)

If you have any queries or suggestions or complaints, please reach out to us at this email address: support@lucep.com