Proof-of-Play submission service

info-beamer doesn't yet have a fully native proof-of-play system. This package aims to provide an interim solution for a future PoP standart method.

A Proof-of-Play compatible package should accept TCP connection at root/::pop and provide line based data. Each line is a full json object.

The first line is a header and must at least provide

{"pop": "some-sender"}

to indicate which mechanism generated the data. In the future the endpoint might be natively provided by the info-beamer runtime. Right now a Lua script has to implement the listener using the "connect" and node.client_write features.

All following lines are proof-of-play events. Right now they look like this:

{
    "uuid": "80832514-f984-4af8-9e0b-f755b15c21d0",
    "ts": 1774549328, 
    "asset": {
        "filename": "video.mp4",
        "id": 1234
    },
    "device": {
        "id": 456,
        "serial": "123098123"
    },
    "setup": {
        "id": 243317
    }, 
    "duration": 10,
    "extra": {
        "tags": ["foo", "bar"]
    }
}

uuid is UUID Version 4 and is unique to this playback event. Logging can deduplicate potentially multiple log lines for a single event.

ts is the unix timestamp of when the playback started.

device provides device id and its hardware serial number.

setup.id is the currently active setup id.

asset provides asset id as well as asset backend filename.

extra can contain any free form data provided by the playback code that's associated with the asset.

Theory of operation

This package contacts the running info-beamer node. It listens for events in the above format and batch-submits them to a given target backend using POST requests.

Optionally the content of the Authorization header can be set in case authorization is needed.

The received events are first spool in memory and submitted in batches to the specified url.

If submission fails, the events will be persisted in the scratch directory on the device's local storage. Upon restarting the package service, this file is read again. The package uses "package" scope for its scratch directory, so having the same package added to multiple setups will allow it to persist events across setup changes.

If submission was successful, both memory and on-disk spool is flushed.

Rebooting the device or forcefully switching to setups without this package added will kill the package service and events buffered in memory will be lost. This should be limited to those gathered within the configured minimum interval only.

If the network is unreliable it could happen that events are submitted multiple times. The storage backend can deduplicate those events using the uuid value.

Feedback

Yes. Please.