Quickstart

Getting started is easy:

Step 1. Copy the snippet

Copy and paste our snippet into your website:

📘

Install on Sift

Go to https://app.hellosift.com to get your JavaScript snippet.

<script>
  (function(){var Sift=window.Sift=window.Sift||[];if(Sift.initialized)return;if(Sift.invoked){window.console&&console.error&&console.error("Sift snippet included twice.");return}Sift.invoked=true;Sift.methods=["page","identify","on"];Sift.factory=function(method){return function(){var args=Array.prototype.slice.call(arguments);args.unshift(method);Sift.push(args);return Sift}};for(var i=0;i<Sift.methods.length;i++){var key=Sift.methods[i];Sift[key]=Sift.factory(key)}Sift.load=function(writeKey){var script=document.createElement("script");script.type="text/javascript";script.async=true;script.src="https://widget.hellosift.com/widget.js";var first=document.getElementsByTagName("script")[0];first.parentNode.insertBefore(script,first);Sift.WRITE_KEY=writeKey};Sift.SNIPPET_VERSION="0.0.1";
  Sift.load("YOUR_WRITE_KEY");
  Sift.page();
  })();
</script>

<script>
  (function() {
    var Sift = (window.Sift = window.Sift || []);

    // Return if `Sift` is already loaded.
    if (Sift.initialized) return;

    // If the snippet was invoked previously then show an error.
    if (Sift.invoked) {
      window.console &&
        console.error &&
        console.error('Sift snippet included twice.');
      return;
    }

    // Set invoked flag to ensure the snippet is never invoked twice.
    Sift.invoked = true;

    // A list of methods on the `Sift` widget to be stubbed.
    Sift.methods = ['page', 'identify', 'on'];

    // A factory to create stubs: placeholders for methods on the `Sift`
    // widget that can record data prior to loading. The `method` is stored
    // as the first argument so we can replay the data.
    Sift.factory = function(method) {
      return function() {
        // eslint-disable-next-line prefer-rest-params
        var args = Array.prototype.slice.call(arguments);
        args.unshift(method);
        Sift.push(args);
        return Sift;
      };
    };

    // Create stubbed methods for the queue.
    for (var i = 0; i < Sift.methods.length; i++) {
      var key = Sift.methods[i];
      Sift[key] = Sift.factory(key);
    }

    // Define a method to load the widget once and only once.
    Sift.load = function(writeKey) {
      var script = document.createElement('script');
      script.type = 'text/javascript';
      script.async = true;
      script.src = 'https://widget.hellosift.com/widget.js';
      var first = document.getElementsByTagName('script')[0];
      first.parentNode.insertBefore(script, first);
      Sift.WRITE_KEY = writeKey;
    };

    // A version so we know which snippet our awesome customer is using. ;)
    Sift.SNIPPET_VERSION = '0.0.1';

    // Load the widget.
    Sift.load('YOUR_WRITE_KEY');

    // Make a first page call.
    Sift.page();
  })();
</script>

🚧

Pasting the snippet

If you're copying and pasting the snippet from this documentation, please make sure to replace YOUR_WRITE_KEY with your own write key, which can be found in your widget installation screen on https://app.hellosift.com.

This snippet will load into your site asynchronously so it won't affect your page load speed. Once it's live, you can start identifying your users and tracking page views – both steps which are needed to start asking your users for feedback.

Step 2. Identify your users

Every time your user loads a page, you'll want to call identify to tell Sift who your current user is. You can read more about identify here.

Here's an example of a basic identify call:

Sift.identify('123', {
  name: 'Josh Smith',
  email: '[email protected]',
});

This identifies Josh with his userId (his unique ID from your database) and provides traits of name and email for you to reference later.

But you don't want to just copy this hard-coded data. You'll need to replace all those hard-coded values with your user's real data.

You could do this by injecting the values into JavaScript in a backend template generated by your server, or you could do this inside a front-end JavaScript application.

An example could look like this (click the tabs to change between server-side and JS):

Sift.identify('<%= @user.id %>', {
  name: '<%= @user.name %>',
  email: '<%= @user.email %>',
});

Sift.identify(user.id, {
  name: user.name,
  email: user.email,
});

In either case, that call will now identify every user on your site to Sift.

Step 3. Track user actions and pages

Tracking user actions is your last step before you can get feedback in your app.

You can use both page and track calls to help you target feedback. Let's see how they differ.

📘

Where should you focus?

We strongly recommend you focus on implementing track calls because they read more naturally when deciding who to ask for feedback and are far less prone to breaking when something in your site changes.

The page call lets you track page views. You can read more about page here.

We automatically call page inside your snippet for you. If you want to name pages, you can update the page call inside your snippet by calling it with an optional name string.

For example, a user might invite other users to your app on an "Invites" page. To track this, you would call page like so:

Sift.page('Invites');

You might want feedback about how the invite process works since it's important to your company's referral program.

Tracking this page will let you target feedback only to users who visit this page at the time they visit it.

However, one reason we prefer using track events over only page events is because track events are often more meaningful. If a user visits your "Invites" page you don't really know much about their behavior. Did they send an invite? How many invites did they send?

The track call lets you send expressive events like "Invite Sent". You call track with a required name string indicating the name of the event you're tracking. You can read more about track here.

For example, when your user sends an invite by clicking the invite button, you can call:

Sift.track('Invite Sent');

Now you can use Sift to get feedback from users who sent an invite, instead of just getting feedback from users who only visited the invites page. You could even get feedback from users where Invite Sent happened 5 or more times.

That's it! You've learned the basics about installing the widget, identifying your users, tracking page views, and tracking events.

You can now start asking your users for feedback or read more in-depth about the JavaScript Library.