Analytics?

[pietrop]

Hello,
Was wondering if there's any ideas on how to best integrate with third party (or custom) analytics for tracking user's usage of the player?

Eg when user click play, etc..

I think I can probably use the Events but I wanted to check if there was a recommended pattern? and/or what could be a good way to use Events to do this? And/or if there are going to be integrations with mux/data or other providers in the future?

apologies if you might have covered this elsewhere, but so far couldn't find it

Best

Pietro

[pietrop]

I guess it might be this vidstack/analytics ?

[mihar-22]

Yep! The stuff I wrote below would all be handled out of the box by vds-analytics. That package will most likely contain the third-party integrations as well.

<vds-analytics>
  <vds-media>
  ...
  </vds-media>
</vds-analytics>

[mihar-22]

Was wondering if there's any ideas on how to best integrate with third party (or custom) analytics for tracking user's usage of the player? I think I can probably use the Events but I wanted to check if there was a recommended pattern? and/or what could be a good way to use Events to do this?

Not sure how to do it with third-party integrations yet because I haven't had a chance to experiment with them all yet. I'd need some clarification on what you mean by "usage" so I can help more. I'm guessing something like the amount of playback time they've consumed in a single sesssion? Do note you'd need to account for any buffering and seek events as well.

We've done this before by creating a StopWatch class that has two methods start and stop. We called stop during vds-waiting, vds-seeking, and vds-pause events. We called start on vds-playing (not vds-play because that's before playback actually begins).

As you noted, the Vidstack Player Events can cover it. You can check if an event was dispatched by the system or user checking the isOriginTrusted prop on events:

const video = document.querySelector('vds-video');
video.addEventListener('vds-playing', (event) => {
  if (event.isOriginTrusted) {
    // user played media
  } else {
    // system played media (e.g., browser, or programmatic call)
  }
});

And/or if there are going to be integrations with mux/data or other providers in the future?

Yep definitely plans to add third-party integrations. Still a big question on how we should approach them such. I haven't thought about it deeply yet but on the surface probably by creating a flexible base analytics element. The element can listen to media events, do some work, and dispatch analyitcs events such as vds-user-play (maybe past-tense for analytics? - vds-user-played) and so on. We created something like this at Reddit so I'll need to dig through my notes.

The hope would be we can then use same base API to build out third-party integrations by simply wiring up the analytics events to their respective integration work. Need to talk to the Mux team on how to integrate with Mux Data because there's no public docs to my knowledge.

[pietrop]

👋 Thanks,

Analytics events examples

for context, I am working on a new player, but we have a legacy player that sends events to an existing analytics backend. So I am somewhat constrained by maintaining at least feature parity on the analytics before considering adding new once.

Here's a (lightly modified) table from out docs to show a list of events and user interactions we are tracking

Name	Description
pause	Triggered when a video is paused (usually by the user) - player.pause()
resume	From a paused state, user clicked to play the video
seek	User chooses a specific to advance or rewind the video to. - player on seeked event. - [HTMLMediaElement: seeked event - Web APIs
mute	User mutes the audio.player on volumechange event. - [HTMLMediaElement: volumechange event - Web APIs
unmute	User unmutes the audio. - player on volumechange event.
enter-fullscreen	Video expands to full screen. - player.toggleFullScreen()
exit-fullscreen	Video retracts to regular size. - player.toggleFullScreen()
player-load	When the player loads on the page. - The player code loaded on the page (but before the HTMLMediaElement video or audio)
media-load	Video or media within the player loads on the page. - Triggered on loaded data HTML5 media event - [HTMLMediaElement: loadeddata event - Web APIs
inview	Video player is within the browser window or app screen of the user. - It is fired only once if the player is ever in view view. Eg the user can see it. Like an "impression".
share-tools-twitter	User clicks on the twitter option in the share tools
share-tools-facebook	User clicks on the facebook option in the share tools
share-tools-embed	User clicks on the embed link option in the share tools
auto-play-start	Video automatically begins playing, triggered upon first video that autoplays if part of a playlist. - Triggered when autoplay starts (programmatically). - player on play {once: true}. - Should not be used for loop videos, trigger once when a standard linear video plays - The decision was to keep these event names separate based on which kind of video plays rather than mixing them
user-play	User initiates a video play. - player.play({ isUserGeneratedInteraction: true })
auto-play-loop	Designates an automatic play for looped videos, triggers only once upon first play. - Automatically playing, on a loop. Should trigger once when a loop video begins playing automatically.
user-play-loop	User initiated play on a looped video. - Designates a user play for looped videos, triggers only once upon first play.
auto-play-next	If a video is part of a playlist. - triggered When watch a new video in the playlist that automatically starts. - Triggered upon next video that autoplays if part of a playlist.
user-play-next	Same as above but the user initiated the new video play. - Triggered upon next video that user initiates a play for if part of a playlist.
media-complete	Completed playing the media. - Video or other media has completed playing. - For non loop video is ended event, - and for loop videos is using a helper function that compares end fragment in played with duration.
3-seconds-consumed	Video has progressed to 3 seconds. - ⚠️ Unfortunately this and the once below. Don't necessary indicate if the user has skipped around the player vs watched the video linearly.
30-seconds-consumed	Video has progressed to 30 seconds
percent-25-consumed	Video has progressed 25% of the way to completion
percent-50-consumed	Video has progressed 50% of the way to completion
percent-75-consumed	Video has progressed 75% of the way to completion
percent-90-consumed	Video has progressed 90% of the way to completion
ad-pause	Video advertisement is paused
ad-resume	Video advertisement is resumed
ad-start	Video advertisement begins
ad-skip	Video advertisement is skipped
ad-complete	Video advertisement completes playing
level-change	This might not apply to VHS 4. As for now there's only volume toggle and no volume slide in the UI.
endslate-inview	The end slate is in view
endslate-load	The end slate has loaded
caption-on	User turns captions on. - When captions are turned on, as part of player.toggleCaptions()
caption-off	User turns captions off. - When captions are turned off, as part of player.toggleCaptions()

Session based tracking

things like the amount of playback time they've consumed in a single session would be great, but I think it's currently aggregate by the backend after the fact, at the moment seems to be mostly event based. But we are definitely looking to improve. I always liked things like the wistia.com heat-map. So I guess more session based data might be able to provide data to the backend to make something similar as well.

Mux data

Need to talk to the Mux team on how to integrate with Mux Data because there's no public docs to my knowledge.

Yeah, I think our player used to use it (before I joined) but it was also removed before I joined, so I unfortunately don't know much about how that was done. But it seems like it could provide a pretty comprehensive set of analytics and insights.

Code example

In any case, I'll have a look into your code snippet 🙏 , I think that might get me most of the way there. mapping vds-video events to analytics once etc... 🤞

isOriginTrusted is also pretty cool, I can probl remove my existing workaround (which was passing a prop to the play method to identify use generated actions/events player.play({ isUserGeneratedInteraction: true }))