statewize-client-sdk-web
v0.0.12statewize-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;
- Collect interaction events only for elements that hate the statewize attribute on them (
data-statewize-slug
) - 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?
- When your
<div>
element (that has thedata-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'. - When your customer clicks the child button - the SDK will report an event
- 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. - If you specify the
data-statewize-report-type="click"
- then the event will be sent to STATEWIZE only upon interaction, not when it appears. - 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
Metadata
- GPL-3.0-only
- Whatever
- Unknown
- released 11/19/2021