paella-core/doc/event_log_plugins.md

Multistream HTML video player

# Event log plugins

They are used to trigger actions following events generated by Paella Player. These events can be triggered by automatic actions, for example, the `Events.TIMEUPDATE` event, or by user actions, such as `Evens.PLAY`. It is also possible to capture custom events. See the [events](events.md) document for more information.



## Create an event log plugin

To implement an event log plugin, you must to overwrite the property `get events()` and the method `async onEvent(event, params)`.

`get events()`: returns an array with the events that you want to handle by the `onEvent()` function.

`async onEvent(event, params)`: this function is invoked whenever one of the events returned by  `get events()`  is triggered by the player.



```javascript
import { Events, EventLogPlugin } from 'paella-core';

export default class TestEventLogPlugin extends EventLogPlugin {
  get events() {
    return [
      Events.PLAY,
      Events.PAUSE,
      Events.TIMEUPDATE
    ]
  }
  
  async onEvent(event, params) {
    console.log(event);
    console.log(params);
  }
}
```



## Track user actions

It is possible to use an event plugin together with a [data plugin](data_plugins.md) to implement user tracking. The procedure consists of writing data to a context that we predefine for this purpose, for example `userTracking`:

```javascript
export default class MyUserTrackerEventLogPlugin extends EventLogPlugin {
  ...
  
	async onEvent(event, params) {
    await this.player.data.write(
      'userTracking', 
      { id: this.player.videoId }, 
      { event: event }
    );
  }
}
```



Then you just have to define a data plugin that responds to the `userTracking` context to write the events to any system. We could have two different data plugins: one for Google Analytics and one for Matomo:

**es.upv.paella.matomoDataPlugin.js:**

```javascript
export default class MatomoDataPlugin extends DataPlugin {
  async write(context, id, data) {
    // Write Matomo event for the video `id`
    ...
  }
}
```



**es.upv.paella.analyticsDataPlugin.js:**

```javascript
export default class AnalyticsDataPlugin extends DataPlugin {
  async write(context, id, data) {
    // Write Analytics event for the video `id`
    ...
  }
}
```



In the player configuration is where we define the priority level of each data plugin, to determine which of the analysis systems we are going to use, depending on the plugin priority:

```json
{
  "plugins": {
    ...
    "es.upv.paella.matomoDataPlugin": {
      "enabled": true,
      "order": 0
    },
    "es.upv.paella.analyticsDataPlugin": {
      "enabled": true,
      "order": 1
    }
  }
}
```

## Event log plugins and life cycle

Event handlers that are registered in an event plugin are automatically deleted if the player is unloaded. This is desirable because if after downloading the player another reload occurs, the plugins will be reloaded again, and therefore the event handlers registered in an event plugin will be re-registered again.

More information on this topic can be found in the [documentation about event handlers](events.md).