@iflix/events-receiver-client

Events receiver client

Events receiver client is iflix user tracking SDK that allows web based platforms to report user behavior. Using this SDK is the easiest way to reliably identify users. It doesn't report any data by default and it is up to the client (user of this SDK) to send data.

Install

We currently assume that you are using package manager in your project. If you're not please let us know and we can prepare some standalone bundle.

npm i @iflix/events-receiver-client

Usage

Complete documentation of events is on developer portal. To see more detailed examples you can check scripts/send-test.ts and testbed/testbed.ts for inspiration.

But basically you want to do something like:

Minimal Example:

In most cases more information should be provided but this is the minimal info you should set.

import { createEvent, createClient, EventType, EventOrigin } from '@iflix/events-receiver-client'

// initiate events client, you usually want to do this only once and store it in some shared (possibly global) place.
const queueEvent = createClient({
  client: {
    attribution: {
      utmsource: "your-app-id",
      clientuserid: 123456
    }
  }
})

// create an event when user does desired action
const event = createEvent({
  contentRegion: 'xx', // iflix region which is being presented to the user
  type: EventType.APP_EVENT,
  name: `test event ${eventCount}`,
  origin: EventOrigin.SYSTEM,
  data: {}
})

// and queue the event to be sent to server
queueEvent(event) // you can `await` this if you want to make sure it's in the DB before continuing

Device ID

Device ID is unique randomly generated string we use for identifying the device. It has important role to count users right. In some cases we may request your integration to pass it to us so we can keep it in sync and avoid double counting. To get current deviceId you can use following code. The library will make sure it is stable and consistent.

import { getDeviceId } from '@iflix/events-receiver-client'
const deviceId = getDeviceId()

How it works under the hood

Calling createClient gives you an "event queuing" function (you can call it what you like but the convention is queueEvent) you can call with a fully built-out event. This will either store it in a memory buffer, or if available, IndexedDB.

createClient will start a timer in the background that will periodically flush events once an "accumulation" time period has elapsed. If you set priority to EventPriority.HIGH for an event, then the timer will send the whole buffer immediately. (also queueEvent will attempt to fire off an immediate flush as soon as it's queued).

createEvent takes your PartialEvent and decorates it with extra info that you probably can't be bothered getting yourself. It returns an Event suitable for giving to queueEvent. There is nothing magical about this function though, if you construct an Event from scratch (don't do this) you don't have to call createEvent

queueEvent has a few extra functions on it too:

• queueEvent.flush(force = false) - this will basically do the check to see if anything needs flushing, and flush it (or always flush if force=true). Generally speaking, you don't need to flush -- just use priority on events if you want things sent quickly.
• queueEvent.shutdown() - this will turn off the timer, and attempt to do a final flush of the buffer

Considerations

Client and server usage

This package is designed to be used primarily in a browser but works and can be used in NodeJS as well.

Buffering

This package is more complex than it might otherwise be because of the buffering. It's pretty important though, because of the way iflix uses these events; we can't let them go missing. So it does a lot of work to try and get stuff through.