# statewize-client-sdk-web

> Integrate with STATEWIZE from web applications

Latest version **1.2.3** (published 2022-04-21) · GPL-3.0-only license · 0 weekly downloads

## Install

```sh
npm install statewize-client-sdk-web
pnpm add statewize-client-sdk-web
yarn add statewize-client-sdk-web
bun add statewize-client-sdk-web
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.3 |
| Published | 2022-04-21 |
| First published | 2021-11-19 |
| Weekly downloads | 0 |
| License | GPL-3.0-only |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 330 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | justlev |

## Links

- npm: https://www.npmjs.com/package/statewize-client-sdk-web
- npm.io page: https://npm.io/package/statewize-client-sdk-web

## Dependencies (3)

- [lodash](https://npm.io/package/lodash.md) ^4.17.21
- [nanoid](https://npm.io/package/nanoid.md) ^3.1.30
- [statewize-client-sdk](https://npm.io/package/statewize-client-sdk.md) ^2.7.4

## Recent versions

- 1.2.3 (latest) — 2022-04-21
- 1.2.2 — 2022-04-20
- 1.2.1 — 2022-04-19
- 1.2.0 — 2022-04-19
- 1.1.15 — 2022-01-03
- 1.0.2 — 2021-11-21
- 1.0.1 — 2021-11-20
- 1.0.0 — 2021-11-20
- 0.0.14 — 2021-11-19
- 0.0.13 — 2021-11-19
- 0.0.12 — 2021-11-19
- 0.0.1 — 2021-11-19

## README

# statewize-client-sdk-web 🌍 🖥

Integrate your website (static) or webapp with [STATEWIZE](https://statewize.com) using this library.

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

## Installation

### Static websites

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

```html

<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

```shell
yarn add statewize-client-sdk-web
```

OR

```shell
npm install statewize-client-sdk-web
```

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

```javascript
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

```js
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:

```html
      <!--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](https://www.npmjs.com/package/statewize-client-sdk).

### 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:

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

OR

```js
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](https://www.npmjs.com/package/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):
```js
const instance = await init(STATEWIZE_API_KEY, {});
```

and, after the `init` call, it will be populated on the `window`:
```js
window._statewize.sdk
```

---
_Source: https://npm.io/package/statewize-client-sdk-web · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._