Web - JavaScript

📷

UserLeap is now Sprig

We might have changed our name, but you don't have to change a thing!
All of your studies, integrations, and code will continue to function properly with no action required.

Install

Add the following code snippet to your webpage to complete a Sprig JavaScript SDK installation. Add the snippet to every page on your website where you want Sprig to track your users. You can paste the snippet anywhere on the page, but preferably at the bottom of the document, before the </body> tag.

📘

Info

Depending on your current Environment, replace ENVIRONMENT_ID with the Production ID or Development ID by clicking Get Code on Connect > JavaScript.

<script>
   (function(l,e,a,p) {
     if (window.Sprig) return;
     window.Sprig = function(){S._queue.push(arguments)}
     var S = window.Sprig;S.appId = a;S._queue = [];window.UserLeap=S;
     a=l.createElement('script');
     a.async=1;a.src=e+'?id='+S.appId;
     p=l.getElementsByTagName('script')[0];
     p.parentNode.insertBefore(a, p);
   })(document, 'https://cdn.sprig.com/shim.js', 'ENVIRONMENT_ID');
 </script>

Sprig provides two Environments (with corresponding ENVIRONMENT_IDs). As the Development environment is not constrained by the recontact waiting period policy, it is recommended to test your studies; then, you can use the Production environment to deploy your studies to receive user feedback. Make sure to use the correct ENVIRONMENT_ID corresponding to the environment (Development or Production) you have selected.

📘

Info

The Development environment behaves differently than Production. It does not adhere to the recontact waiting period policy. This allows you to verify installation more quickly as every user event always triggers a study.

Verify Installation

There are two primary ways to verify the installation. Either by viewing People in the Sprig app or by opening the browser's JavaScript console for the page in question and running a command.

People page

Navigate to People to verify that your site sends events to Sprig. When a user visits your site, they will appear in this view. Their study eligibility or Study Status will also be shown. If you have set the EMAIL_ADDRESS attribute, it will also be displayed.

Browser Console

In Sprig, only users who match a running study's specific targeting will ever see a study due to the JavaScript. This can make it challenging to test out how to study will look for users on your site.

In addition to the Live Preview rendered during the Design and Launch of a given study in the Dashboard, you can also manually view and test a study from your site by running the following command in the browser JavaScript console.

1. In the Sprig app go to Settings > Configure.
2. Select Allow Manual Study Display.
3. In your browser, open the JavaScript console.
4. Run the command: Sprig('displaySurvey', SURVEY_ID);
   To find the SURVEY_ID, go to Studies and then click on a study. The SURVEY_ID is the integer at the end of the PATH of the URL in your browser.
   https://app.sprig.com/surveys/SURVEY_ID
5. If the Sprig snippet is already installed on that page, your browser will display the study.

Testing a study in this manner will record responses, and your production environment will honor the recontact waiting period before tracked events for the same user will trigger another study.

After you have finished your testing, consider returning to Settings > Configure and select Disable Manual Study Display. This will prevent any other visitor from using displaySurvey in your environment.

Identify Users

Sprig allows you to differentiate users by setting a USER_ID. While setting USER_IDs is optional, it helps provide a consistent experience across platforms and prevents users from seeing the same study multiple times. It also helps you to optimize the number of events you send to Sprig. The user identifier should be unique and associated with a user in some way.

Set the USER_ID after the installation snippet if they are already logged in or after the user logs in to your website:

<script>
    Sprig('setUserId', 'USER_ID');
</script>

This user identifier is stored via local storage, and this function can be called multiple times safely. We recommend you set the user identifier every time you initialize Sprig and when your user logs in.

You can also provide Sprig with the user's email address. It is not required for Web and Mobile studies but is required to enable email-based studies.

<script>
    Sprig('setEmail', 'EMAIL_ADDRESS');
</script>

Logout

When a user logs out of your webpage, make sure to log out of Sprig. This will prevent new activity from being associated with the incorrect user.

<script>
    Sprig('logoutUser');
</script>

Sample Snippet

Following is a sample snippet of what an installation looks like on pages that track registered users:

<script>
   (function(l,e,a,p) {
     window.Sprig = function(){S._queue.push(arguments)}
     var S = window.Sprig;S.appId = a;S._queue = [];window.UserLeap=S;
     a=l.createElement('script');
     a.async=1;a.src=e+'?id='+S.appId;
     p=l.getElementsByTagName('script')[0];
     p.parentNode.insertBefore(a, p);
   })(document, 'https://cdn.sprig.com/shim.js', 'ENVIRONMENT_ID');
  
   // Increases tracking accuracy across devices
   Sprig('setUserId', 'USER_ID');
  
   // Allows the user to receive email studies 
   Sprig('setEmail', 'EMAIL_ADDRESS');
 </script>

Set Visitor Attributes

Sprig lets you build up user profiles to provide more context to understand the user's feedback better. Sprig tracks a default set of attributes and allows you to specify custom attributes and values specific to your business.

You can use visitor attributes for a study targeting to help refine the cohort of users you wish to study. They can also be used as filters to drill into the study response data in the Sprig Dashboard.

📘

Info

Visitor Attributes are limited to 100 distinct values for a given key

Default Attributes

Sprig's JavaScript snippet automatically tracks and attaches the following attributes:

• Browser and version
• Device
• Session count
• Page URL
• Screen size
• Browser Language
• Operating System and Version

Custom Attributes

Optionally, you can send in custom attributes about the visitor. This information is visible on the People section of the Sprig Dashboard when viewing a Visitor.

Values

• ATTRIBUTE {String} required - the attribute name to set. Attributes beginning with ! are reserved
• VALUE {Object} required - the value to set for the specified attribute name (typically a string or number, but anything convertible to JSON will work)

<script>
    //for a single attribute
    Sprig('setAttribute', ATTRIBUTE, VALUE);
    
    //for multiple attributes
    //saves multiple rounds trips and reduces data usage
    Sprig('setAttributes',{
        ATTRIBUTE1: VALUE1,
        ATTRIBUTE2: VALUE2
    });

    //if attributes no longer apply to the user
    //you can delete multiple at a time
    Sprig('removeAttributes', [ATTRIBUTE1, ATTRIBUTE2]);
</script>

Some common attributes to set are:

• Location
• Referral URL
• A/B test group

Track Events to Display Studies

Sprig provides two types of Events for triggering and filtering your Studies using our SDK. They are described as No Code and Code event types.

Code Events

To add or track a Code event for triggering or filtering, you will need the following snippet. If you or your colleague added a Code event via the UI, be sure that the event name used in the UI is identical to the name used in this snippet.

<script >
    Sprig('track', 'EVENT_NAME');
</script>

When Sprig receives this event, the study is displayed if the user is eligible to receive that study. You can see the eligibility of a given user on the People page.

📘

Info

Sprig('track', 'EVENT_NAME') makes a network call, so be sure to give it enough time to complete. Also, note that if you or your colleague added a Code event to the UI via the Code option there, the name used in the code would need to match the name in the UI exactly.

Verifying Studies

We have tests in place to make sure we show studies at the right time. To test that your studies show with the right attributes and events set, be sure to set up the SDK with your development ENVIRONMENT_ID. This will bypass throttling and the recontact window.

No Code Events

there are three types of No Code events: Page URL, Inner Text, and CSS Selector. No code events can only be used to trigger Web Studies. Once the Sprig JavaScript snippet is installed, No Code events permit study designers to create triggers outside the webpage, potentially not requiring engineering support. Sprig also supports Regular Expressions, which can be useful to include or exclude groups of pages from the triggering.

Page URLs

Page URLs allow you to define a single page or a set of pages to trigger a study.

Inner Text

The No-Code options allow you to track events when a user clicks one or more HTML elements, with some specific inner text, or rendered text, one or more pages. The snippet needs to be installed and configured. Once configured, they are viewed on the Events page.

CSS

The No-Code option allows you to track events when a user clicks a specific CSS class.

📘

Info

Studies only support one trigger at a time. So a single study may only have one event trigger or one Page URL trigger.

Customize Appearance

You can set a limit on the height of your study with the following javascript in the installation snippet:

Sprig.maxHeight = '50%';

This will set the maxHeight property of the iframe.

For custom installations, if Sprig is installed within an iframe that initially has 0 width, by default, studies will render with desktop styling and a width of 360px. In these cases, to make use of mobile styling and full-width studies on mobile web, you can tell us your window dimensions when Sprig is initialized, and when the window is resized.

Sprig('setWindowDimensions', width, height) # width and height are pixel numbers

You can further customize study placement and appearance in our dashboard: Settings > Look and Feel. See Study look and feel documentation for more details.

Study State Notifications

In Sprig SDK version 1.9.0 and above, Sprig introduces several new SDK events and exposes a new way to listen to the updates. Here is a sample code block for listening to SDK events in real-time:

// an example of a simple listener
const listener = function (e) {
    // does work with data
    console.log(e);
};
// to subscribe to Sprig study presented event
Sprig('addListener', Sprig.UPDATES.SURVEY_PRESENTED, listener);
// to remove a study presented event listener
Sprig('removeListener', Sprig.UPDATES.SURVEY_PRESENTED, listener);

The following supported events are available on Sprig.UPDATES:

Performance

In the modern web, performance is a critical part of any successful website. At Sprig, we ensure that you can get deep insights about your users without sacrificing your site's performance.

Speed impact on your website

The script is loaded asynchronously, so it does not impact website load times or scroll performance.

File Sizes:

The Sprig JS SDK is broken up into 2 JS files: a controller and a view.

controller.js: 188KB

The controller is responsible for keeping track of your users and your interface to track events and set attributes and identities. A vast majority of sessions are not shown studies, so we separated the view into a separate file, reducing data usage for your users.

view.js: 213KB (users only download this when a study is presented to them)

The view contains the code to show the study and send the responses to Sprig.

Availability and Load time:

The Sprig client-side script is hosted on a leading global CDN powered by AWS CloudFront. This allows for the fastest load times by hosting the script as close to the users as possible.

Cross-browser testing:

The Sprig client-side script is tested against all modern browsers, including:

Chrome (latest versions*)
Firefox (latest versions *)
Safari 8+
Internet Explorer 11
Microsoft Edge 40+

* Chrome and Firefox are on 6-week release cycles, so best-effort support is given to older releases

CPU Usage:

Sprig adds minimal CPU overhead (less than 0.1%), leaving application responsiveness virtually untouched. Our cross-browser testing suite ensures that Sprig remains performant across all browsers.