statewize-client-sdk-web 🌍 🖥

Integrate your website (static) or webapp with STATEWIZE using this library.

Official docs: https://docs.statewize.com

Installation

Static websites

Add this right before the end of your </body> tag.

<script type='text/javascript' src="https://unpkg.com/statewize-client-sdk-web/umd/index.js">
</script>
<script type="text/javascript">
    window._statewize.init("Your-API-key-here");
</script>

NPM

yarn add statewize-client-sdk-web

OR

npm install statewize-client-sdk-web

Then, initialize the library at the most appropriate place, for example:

import {init} from "statewize-client-sdk-web";

const App = () => {
  // This will ensure that the SDK is initialized only once:
  useEffect(() => {
    init(process.env.YOUR_TOKEN_HERE);
  }, []);
}

Integration

This is meant to be an automated way for easy, hassle-free integration with STATEWIZE.

There are 2 main integration routes;

1. Collect interaction events only for elements that hate the statewize attribute on them (data-statewize-slug)
2. Option 1 + Collect all interaction with events like links, buttons, inputs & forms

You can choose the right level of interaction when initialising the SDK by passing the right options.

Options

await init(YOUR_API_KEY, {
  // whether STATEWIZE should collect and report URL-changes.
  // You can pass a boolean, or provide your own listener override.
  // default: true
  historyListener: true,

  // automatically listen & report events when interacting with HTMl elements
  // like anchors, buttons, forms & inputs - regardless of whether they do
  // or do not have a STATEWIZE attribute on them.
  // default: true
  interactionsListener: true,

  // If passed as true in combination with `interactionsLitener: true` - will listen
  // only to interactions that occur with elements that have the STATEWIZE attribute them,
  // ignoring any elements that do NOT have that attribute, or that are explicitly ignored.
  // default: false
  listenOnlyToAttributes: false,

  // Defaults to false. If true - will send to STATEWIZE an event indicating that the journey is over right before the page is unloaded (when you leave the page, for example). 
  finishJourneyOnLeave: true,

  // Do not collect anything automatically.
  // default: false
  disabled: false
})

Using the STATEWIZE attributes

All you need to do is to add the right attributes to the elements you'd like to track. For example:

      <!--This will report to STATEWIZE when this element appears, and when it's destroyed:-->
<div data-statewize-slug="STEP_SLUG_FROM_STATEWIZE">

    <!--This will report to STATEWIZE an event when the button is clicked.-->
    <button id="some-button-id" data-statewize-slug="OTHER_STEP_SLUG_FROM_STATEWIZE">Your Button</button>
   
   <!--This will report to STATEWIZE an event when this div is clicked. -->
   <!--Non anchors / buttons need an explicit data-statewize-report-type attribute to be tracked.-->
   <div data-statewize-slug="some-slug" data-statewize-report-type="click">Clickable div</div>
   
   
   <!-- No matter what, this input will not be tracked as you've explicitly ignored it: -->
   <input data-statewize-ignore="true" />
</div>

What's happening?

1. When your <div> element (that has the data-statewize-slug attribute) appears - an event will be sent to STATEWIZE. It will tell STATEWIZE that the 'step' has 'started'. When it disappears (node is destroyed) - the SDK will report to STATEWIZE that this step has 'ended'.
2. When your customer clicks the child button - the SDK will report an event
3. When your customer clicks the div with the data-statewize-slug attribute - an event will be sent to STATEWIZE. If this div didn't have the STATEWIZE attribute - it would not have been tracked.
4. If you specify the data-statewize-report-type="click" - then the event will be sent to STATEWIZE only upon interaction, not when it appears.
5. If you'd like to omit/redact/ignore ANY element at all from being tracked - add the data-statewize-ignore attribute to it.

HTML attributes:

data-statewize-slug="STEP_SLUG_FROM_STATEWIZE - The state slug from STATEWIZE of the specific step that should be tracked. If no other attribute is supplied - the element will be tracked automatically when it appears.

data-statewize-report-type="appearance | click" - defaults to appearance - will report to STATEWIZE either when the element appeares, or when there's an interaction with it.

data-statewize-ignore="anything - This element will be ignored.

Custom integration

If you are looking for a more custom integration type, one that you can fully control in terms of when things are tracked (rather than relying on HTML elements) - check out our manual integration library.

Enriching user data

You can provide additional user data for users that you track. We don't know who your users are, and we don't use their information for any purposes. But for your own logging purposes, if you're interested to attach some rich data about the users you track - you can do so using setUserData method.

For example:

window._statewize.setUserData({yourUserId: 'my-user-1234', userData: {something: "important"}});

OR

import {setUserData} from "statewize-client-sdk-web";

// Something's happening...

setUserData({yourUserId: 'user-1234', data: {something: 'important'}});

Accessing the SDK directly

The base version of statewize-client-sdk is available to you as soon as it's initialized (meaning, after you call init). It's returned from the init call (with a promise):

const instance = await init(STATEWIZE_API_KEY, {});

and, after the init call, it will be populated on the window:

window._statewize.sdk