Browser

Use the browser library to take advantage of features such as Session Recordings, Live Chat, Announcements and Surveys.

Installation

Lucky Orange can currently be used in a browser environment through the use of an HTML snippet, but with an npm package coming soon.

HTML Snippet

You can place the following snippet wherever you'd like, but we generally recommend placing in before the closing </head> tag in your document. The snippet will append a new <script> tag to the document that will load with the async attribute in order to prevent blocking the rest of the page from being evaluated while the script is being loaded.

You will need to replace YOUR-SITE-ID with the unique ID of the site you wish to connect to.

<script async defer src="https://tools.luckyorange.com/core/lo.js?site-id=YOUR-SITE-ID"></script>

NPM Package

Coming soon.

Usage

Out of the box, Lucky Orange will automatically be set up for all features available in the app itself. Sessions and visitor profiles will be created for any new visitors to your website. All features can be controlled from the app without having to make changes to the code implementation.

That being said, a robust developer API exists on the page to support more advanced use cases.

After you have installed Lucky Orange, you will now have access to the LO object. If you installed using the HTML snippet, LO will exist on the top level window in the page once the script has loaded.

Ensure Lucky Orange is ready

Before you can use the LO object, you need to make sure it has loaded. You can use the ready callback to trigger any code that relies on LO existing. You will also need to make sure that you await the module on LO that you are trying to use.

window.LOQ = window.LOQ || []
window.LOQ.push(['ready', async LO => {
    // Track an event
    await LO.$internal.ready('events')
    LO.events.track('My Event')
    
    // Or, identify a visitor
    await LO.$internal.ready('visitor')
    LO.visitor.identify({ email: '[e-mail]' })
}])

If you are using GTM to place the code you will need use ES5 syntax instead of the ES6 syntax above.

window.LOQ = window.LOQ || []
window.LOQ.push(['ready', function (LO) {
    // Track an event
    LO.$internal.ready('events').then(function() {
        LO.events.track('My Event')
    })

    // Or, identify a visitor
    LO.$internal.ready('visitor').then(function() {
        LO.visitor.identify({ email: '[e-mail]' })
    })
}])

If you do not use the ready callback or $internal.ready() functions, you are likely to see errors such as "LO is not defined" or "Cannot ready property of undefined."

Link your users to visitor profiles in Lucky Orange

For each new visitor to your website, a visitor profile is created within Lucky Orange. By default, session information such as browser, device, and geolocation data will be associated with the profile and an anonymous name will be given (Ex. Blue Apple). To better align these anonymous profiles with your own user information, use the identify() API. You can pass in a custom user ID and any arbitrary profile data. This data can then be used as filters throughout the app.

Certain keywords are already associated with each Lucky Orange visitor profile by default. These include name, email, and phone and can optionally be included in the meta object. Passing in any of these will update the corresponding field in the visitor profile. Including the name will update the visitor row in the visitors table to help better identify the visitor. The name passed in must be a string, as seen below.

LO.visitor.identify('test-user-123', { email: '[e-mail]', name: 'Test Name' })

Track events

Out of the box, Lucky Orange will automatically track various behaviors throughout a visitor's session. Viewing surveys, clicking buttons, etc. are just a few examples of these behaviors. To track specific business metrics, you can use the track() API. Events tracked using this API are automatically associated to the active visitor's profile, can be used as Announcement triggers, and act as filters throughout the app.

Events require a name and, optionally, can take in any arbitrary metadata that can help give context to an event.

LO.events.track('Account Created', { acceptedTerms: true })

Debugging

If you feel like the browser library is behaving in a way that you do not expect, you can turn on debug logging by setting a debug key in localStorage.

window.localStorage.setItem('debug', '*')

Setting this will begin logging [LO] prefixed messages to your browser's console. There can potentially be a lot of information, but it will give you a clear picture into what Lucky Orange is currently doing.