@mediavine/kinesis-client

@mediavine/kinesis-client

A client for sending data to AWS Kinesis Data Streams without clients-side authentication. This is particularly useful for collecting browser data. The data can then be directed to S3, RedShift, or ElasticSearch.

Prerequisite Tasks

• Create a Kinesis stream. You need to include the stream's resource ARN in the browser script. For more information about creating Amazon Kinesis Data Streams, see Managing Kinesis Streams in the Amazon Kinesis Data Streams Developer Guide.
• Create an Amazon Cognito identity pool with access enabled for unauthenticated identities. You need to include the identity pool ID when instantiating the client. For more information about Amazon Cognito identity pools, see Identity Pools in the Amazon Cognito Developer Guide.
• Create an IAM role whose policy grants permission to submit data to an Kinesis stream. For more information about creating an IAM role, see Creating a Role to Delegate Permissions to an AWS Service in the IAM User Guide.

Use the following role policy when creating the IAM role.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "mobileanalytics:PutEvents",
        "cognito-sync:*"
      ],
      "Resource": [
        "*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "kinesis:Put*"
      ],
      "Resource": [
        "STREAM_RESOURCE_ARN"
      ]
    }
  ]
}

Installation

yarn add @mediavine/kinesis-client

or

npm i @mediavine/kinesis-client

Usage

Import and instantiate the client:

import KinesisClient from '@mediavine/kinesis-client'

const options = {
  debug: false,           // <required> boolean
  identityPoolId: '...',  // <required> string (AWS Cognito Pool ID)
  interval: 5000,         // <optional> number (interval in ms for sending batched data)
  region: '...',          // <required> string (https://docs.aws.amazon.com/general/latest/gr/rande.html)
  sendOnBlur: false,      // <optional> boolean (send events when page is blurred or closed)
  streams: [
    { key: 'k1', name: '...' },  // <required> array<{ key: string, name: string }>
    { key: 'k2', name: '...' }   // (AWS Kinesis streams you wish to track)
  ]
}

// Client can be instantiated normally, but there is will be a small delay
// before AWS Cognito can authenticate.
const client = new KinesisClient(options)

// Client can be initialized asynchronously and will be ready for immediate
// tracking.
KinesisClient.init(options).then((client) => {
  // start tracking...
})

Track events using the stream key corresponding to an AWS Data Stream name with the proper authentication settings, allowing the AWS Cognito role to send data to it.

// Add en event to be sent to a Kinesis stream
client.track('k1', { foo: 'bar' })
client.track('k2', { fizz: 'buzz' })

If an interval options was included in instantiation of the client, data will be sent automatically at regular intervals. To manually trigger a data batch to be sent to Kinesis, use the following. It will clear all pending data.

client.send().then((data) => {
  // do something with AWS data stream response
})