Service: Player Analytics Eventsink - EyevinnOSC/community GitHub Wiki

Player Analytics Eventsink

Player Analytics Eventsink (serviceId eyevinn-player-analytics-eventsink) receives events from video players according to the Eyevinn Player Analytics Specification (EPAS), an open standard for video player analytics, validates them and pushes them to an SQS queue for workers to pick up. It is a long-running service instance. License: MIT.

What it can do

  • Receive EPAS events (init, heartbeat and so on) over HTTP from video players.
  • Validate the events and place them on an Amazon SQS queue, or on an SQS-compatible queue such as SmoothMQ.
  • Restrict which browser origins may post events (CORS).

Creating an instance

The eventsink needs an SQS queue. Either use AWS SQS, or create a SmoothMQ instance (serviceId poundifdef-smoothmq) in OSC, which provides an SQS-compatible queue. Create the queue service first and confirm it is running.

  1. Create SmoothMQ with create-service-instance (serviceId: "poundifdef-smoothmq") with AccessKey and SecretKey, preferably from secrets. Read its URL with describe-service-instance. Other OSC services in the same workspace can use its internal endpoint.
  2. Create the queue in SmoothMQ with any SQS client, for example the AWS CLI. The --endpoint-url is the SmoothMQ instance URL:
% AWS_ACCESS_KEY_ID=<access-key> AWS_SECRET_ACCESS_KEY=<secret-key> AWS_REGION=osc \
  aws sqs create-queue --queue-name=events --endpoint-url=https://<tenant>-guide.poundifdef-smoothmq.auto.prod-se.osaas.io
{
    "QueueUrl": "https://sqs.us-east-1.amazonaws.com/1/events"
}

Note the returned QueueUrl; it is the value for SqsQueueUrl.

  1. Store the access key and secret key as secrets with create-service-secret (serviceId: "eyevinn-player-analytics-eventsink").
  2. Create the eventsink with create-service-instance using serviceId: "eyevinn-player-analytics-eventsink". The instance name must be alphanumeric and at most 20 characters.
{
  "name": "guide",
  "SqsQueueUrl": "https://sqs.us-east-1.amazonaws.com/1/events",
  "AwsAccessKeyId": "{{secrets.accesskey}}",
  "AwsSecretAccessKey": "{{secrets.secretkey}}",
  "SqsEndpoint": "https://<tenant>-guide.poundifdef-smoothmq.auto.prod-se.osaas.io"
}

Wait with wait-for-service-ready and get the eventsink URL with describe-service-instance.

Options

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric, at most 20 characters.
SqsQueueUrl Yes string URL of the SQS queue where validated analytics events are sent (SQS_QUEUE_URL).
AwsAccessKeyId Yes string, sensitive AWS access key id used to authenticate to SQS. With SmoothMQ, use the AccessKey of the SmoothMQ instance. Store it as a secret and pass {{secrets.NAME}}.
AwsSecretAccessKey Yes string, sensitive AWS secret access key paired with the access key id. With SmoothMQ, use the SecretKey of the SmoothMQ instance. Store it as a secret and pass {{secrets.NAME}}.
SqsEndpoint No string Custom SQS endpoint URL, used for SQS-compatible services such as a SmoothMQ instance instead of AWS.
AllowedOrigins No string Comma-separated list of origins allowed to post events (CORS). If empty, all origins are allowed.

A {{secrets.NAME}} reference must be the whole field value. Changing a secret later does not restart a running instance.

Using the instance

Send a test event

Post an init event to the eventsink URL:

% curl -X POST --json '{ "event": "init", "sessionId": "3", "timestamp": 1740411580982, "playhead": -1, "duration": -1 }' https://<tenant>-guide.eyevinn-player-analytics-eventsink.auto.prod-se.osaas.io
{"sessionId":"3","heartbeatInterval":5000}

Check that the event reached the queue

% AWS_ACCESS_KEY_ID=<access-key> AWS_SECRET_ACCESS_KEY=<secret-key> AWS_REGION=osc \
  aws sqs receive-message \
  --queue-url=https://sqs.us-east-1.amazonaws.com/1/events \
  --endpoint-url https://<tenant>-guide.poundifdef-smoothmq.auto.prod-se.osaas.io

The message body contains the event, for example {"event":"init","sessionId":"3","timestamp":1740411580982,"playhead":-1,"duration":-1}, with the message attributes Event and Time.

Resources

⚠️ **GitHub.com Fallback** ⚠️