Iris is a framework agnostic library for dynamically attaching event handlers to DOM elements and sending those events to an upstream source.

Installation

yarn add @teachable/iris

Developing

For development, a package can be linked into another project. This is often useful to test out new features or when trying to debug an issue in a package that manifests itself in another project.

Yarn

Yarn creates the symlink for Iris to be used in other repos i.e. Fedora. When you are finished, make sure you unlink Iris.

yarn link
yarn build # Must be performed for changes to take effect
yarn unlink

Init

Once initialized, Iris automatically attaches itself to window.iris to make itself globally accessible.

import { iris } from '@teachable/iris'

iris.init({
  selector: 'my-selector',
  source: 'my-app',
  noun: 'my-id-key',
  noun_id: 'my-id-value',
  url: 'my-url'
})

Please keep properties snake_cased.

| Property | Description | |----------|---------------------------------------------------------------| | selector | This is the root element that Iris will watch for changes. | | source | Resource for your events. e.g. https://my-api.com/${source} | | noun | Name or type of identifier being sent. | | noun_id | Value of the identifier. | | url | The URL to POST data to. |

Usage

There are 3 possible ways for Iris to send data upstream.

HTML

Iris will automatically detect any new elements that are added to and attach itself to those elements if the iris attribute is present. Iris will automatically remove all iris-* attributes from the element once it's attached itself.

<div
  iris
  iris-event="click"
  iris-verb="User clicked the button"
  iris-meta-foo="bar"
  iris-meta-fizz="bang"
>Click Me!</div>

Currently, the only supported DOM event is click. More will be added as needed in the future.

Manual Attachment

It's also possible to attach iris programmatically. It's important to note that this is a lower level Iris API method. Once this element is removed from the DOM it's up to you to re-attach to it if it's inserted back in.

import '@teachable/iris'

const myElement = document.querySelector('my-element')

iris.attach(myElement, 'click', 'My Event', { foo: 'bar', meta: 'data' })

Forced Emit

Iris also exposes the emit method. This is especially useful for sending events for non-user actions, such as page load.

import '@teachable/iris'

iris.emit('My Event', { foo: 'bar', meta: 'data' })

Anonymous User Tracking

The Iris JS client automatically tracks anonymous user ids via the _afid cookie, which is simply a UUID. If the cookie is not currently set in the browser, Iris will generate one when it initializes and store it in the browser cookie. Use this cookie for tracking users in a funnel from an anonymous (pre-authenticated) to an identified (post-authenticated) state.

This cookie can be used for Mixpanel tracking purposes. Simply set the noun_id for the emitted event(s) to the _afid cookie, and Mixpanel will assign all events to that distinct ID.

Todo

[x] Actually send API calls...

[x] Plain JS helper functions

[ ] AngularJS directive

[ ] React higher order component