npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

paella-user-tracking

v1.42.5

Published

User analytics and tracking plugins for Paella Player

Downloads

1,073

Readme

Paella Player user tracking plugin

It contains basic plugins for capturing user events, such as button or key presses.

Usage

Step 1: Import the plugin context and add it to the Paella Player initialization parameters:

Usin plugin context API:

...
import getUserTrackingPluginsContext from 'paella-user-tracking';

let paella = new Paella('player-container', {
    customPluginContext: [
        getUserTrackingPluginsContext()
    ]
});
...

Using explicit plugin import API (paella-user-tracking >= 1.41):

...
import {
    userTrackingPlugins, // All plugins
    MatomoUserTrackingDataPlugin      // Independent plugin
} from 'paella-basic-plugins';

let paella = new Paella('player-container', {
    plugins: [
        ...userTrackingPlugins,    // All plugins
        { // One plugin
            plugin: MatomoUserTrackingDataPlugin,
            config: {
                enabled: true
            }
        }
    ]
});
...

From version 1.42.2, you can also use the generic plugin array name to import all the plugins:

import { allPlugins as userTracking } from 'paella-user-tracking'
...

All the plugin libraries exports the allPlugins array. This is done in order to have a method to import all plugins using always the same name for all libraries.

Step 2: Configure the plugins you want to use in the paella player configuration.

{
    "plugins": {
        ...
        "es.upv.paella.userEventTracker": {
            "enabled": true
            ...
        }
        ... other plugin settings
    }
}

Included plugins

User event tracker

It is an event plugin that records user events and sends them to a data target. Subsequently, a second data plugin will be responsible for collecting this data and sending it to the corresponding target. The events captured by the plugin will be sent to the context defined by the context attribute of the plugin configuration.

{
    "es.upv.paella.userEventTracker": {
        "enabled": true,
        "context": "userTracking"
    },
    ...
}

The events captured by the plugin are as follows:

```js
    Events.PLAY,
    Events.PAUSE,
    Events.SEEK,
    Events.STOP,
    Events.ENDED,
    Events.FULLSCREEN_CHANGED,
    Events.VOLUME_CHANGED,
    Events.BUTTON_PRESS,
    Events.SHOW_POPUP,
    Events.HIDE_POPUP,
    Events.RESIZE_END

Exported as UserEventTrackerPlugin.

Debug user tracking data plugin

Collects the events sent by the es.upv.paella.userEventTracker plugin and sends them to the javascript console. It allows to debug the event configuration. The plugin can subscribe to one or more data contexts, but generally it will subscribe to the same context where the en.upv.paella.userEventTracker plugin sends events.

{
    "es.upv.paella.debug.userTrackingDataPlugin": {
        "enabled": true,
        "context": [
            "userTracking"
        ],
        "events": [
            "PLAY",
            "PAUSE",
            "SEEK",
            "TIMEUPDATE"
        ]
    },
    ...
}

The events property is used to specify the events that will trigger an user tracking data event. If the events key is not defined in the configuration, the following events will be used by default:

  • PLAY
  • PAUSE
  • SEEK
  • STOP
  • ENDED
  • FULLSCREEN_CHANGED
  • VOLUME_CHANGED
  • BUTTON_PRESS
  • RESIZE_END

If you define the events property, the list that you define will replace all the default events. In addition to this, if the LOG event is captured, the logLevel attribute can be used to customize the log level we want to write. Note that the log level defined in paella-core does not affect LOG events, as these are always generated. The paella-core log level only affects whether or not the log message will be written to the console:

{
    "es.upv.paella.debug.userTrackingDataPlugin": {
        ...
        "events": [
            ...
            "LOG"
        ],
        "logLevel"; "DEBUG"
    },
    ...
}

Exported as DebugUserTrackingDataPlugin.

Matomo user tracking data plugin

Collects the events sent by the es.upv.paella.userEventTracker plugin and sends them to Matomo. In the plugin configuration, we'll set one or more data context, that must contains at least those defined in the es.upv.paella.userEventTracker plugin configuration, and the specific data for the analytics account.

{
    "es.upv.paella.matomo.userTrackingDataPlugin": {
        "enabled": false,
        "context": [
            "userTracking"
        ],
        "server": "//matomo.server.com/",
        "siteId": "1",
        "trackerUrl": {
            "php": "matomo.php",
            "js": "matomo.js"
        },
        "matomoGlobalLoaded": false,
        "mediaAnalyticsTitle": "${videoId}",
        "events": {
            "category": "PaellaPlayer",
            "action": "${event}",
            "name": "${eventData}"
        },
        "customDimensions": {
            "1": "${videoId}"
        }
    },
}

events property can be a boolean value or an object

  • true: events are loagged with default values.
  • false: events are not logged.
  • object: events are logged with custom template values.
    {
        "category": "PaellaPlayer",
        "action": "${event}",
        "name": "${videoId}"
    }

Available template variables are:

  • ${event}: The event name.
  • ${videoId}: The video identifier.
  • ${eventData}: A text representation of the data received by the event.
  • ${metadata}: The video manifest metadata field.

customDimensions property is an object where key is the custom dimension id and the value is a string template.

{
    "1": "${videoId}"
}

The mediaAnalyticsTitle property defines the template variable that will be used as title information in the Matomo Media Analytics plugin. If not set, document.title will be used.

Adapt to your institution

You can extends this plugin and adapt it to your institution. In most cases you only need to implement two functions:

  • getCurrentUserId: returns a text representation of the logged user.
  • getTemplateVars: return an object with te available template variables.
import { MatomoUserTrackingDataPlugin } from 'paella-user-tracking';

export default class MyExtentedMatomoUserTrackingDataPlugin extends MatomoUserTrackingDataPlugin {

    async getCurrentUserId() {
        return 'anonymous';
    }

    async getTemplateVars() {
        let templateVars = await super.getTemplateVars();

        return {
            ...templateVars,
            newvar: "My new variable"
        };
    }

Exported as MatomoUserTrackingDataPlugin.

Google Analytics user tracking data plugin

Collects the events sent by the es.upv.paella.userEventTracker plugin and sends them to Google Analytics. In the plugin configuration, we'll set one or more data context, that must contains at least those defined in the es.upv.paella.userEventTracker plugin configuration, and the specific data for the analytics account.

{
    "es.upv.paella.analytics.userTrackingDataPlugin": {
        "enabled": false,
        "trackingId": "G-xxxxxxxxxx",
        "domain": "",
        "category": true,
        "context": [
            "userTracking"
        ]
    },
}

Exported as GoogleAnalyticsUserTrackingDataPlugin.