{"id":13907904,"url":"https://github.com/Eyevinn/player-analytics-client-sdk-web","last_synced_at":"2025-07-18T06:31:47.250Z","repository":{"id":43322880,"uuid":"440139731","full_name":"Eyevinn/player-analytics-client-sdk-web","owner":"Eyevinn","description":"EPAS Client SDK for Web","archived":false,"fork":false,"pushed_at":"2025-05-12T10:26:32.000Z","size":755,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-07-11T01:57:10.842Z","etag":null,"topics":["library"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Eyevinn.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-12-20T11:06:03.000Z","updated_at":"2025-05-12T10:26:36.000Z","dependencies_parsed_at":"2025-04-11T13:47:14.825Z","dependency_job_id":"c9ccf479-e51e-4af6-b92f-0e9333829f16","html_url":"https://github.com/Eyevinn/player-analytics-client-sdk-web","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/Eyevinn/player-analytics-client-sdk-web","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eyevinn%2Fplayer-analytics-client-sdk-web","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eyevinn%2Fplayer-analytics-client-sdk-web/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eyevinn%2Fplayer-analytics-client-sdk-web/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eyevinn%2Fplayer-analytics-client-sdk-web/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Eyevinn","download_url":"https://codeload.github.com/Eyevinn/player-analytics-client-sdk-web/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eyevinn%2Fplayer-analytics-client-sdk-web/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264911862,"owners_count":23682367,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["library"],"created_at":"2024-08-06T23:02:17.471Z","updated_at":"2025-07-18T06:31:47.236Z","avatar_url":"https://github.com/Eyevinn.png","language":"TypeScript","funding_links":[],"categories":["HarmonyOS"],"sub_categories":["Windows Manager"],"readme":"[![Badge OSC](https://img.shields.io/badge/Evaluate-24243B?style=for-the-badge\u0026logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPGNpcmNsZSBjeD0iMTIiIGN5PSIxMiIgcj0iMTIiIGZpbGw9InVybCgjcGFpbnQwX2xpbmVhcl8yODIxXzMxNjcyKSIvPgo8Y2lyY2xlIGN4PSIxMiIgY3k9IjEyIiByPSI3IiBzdHJva2U9ImJsYWNrIiBzdHJva2Utd2lkdGg9IjIiLz4KPGRlZnM%2BCjxsaW5lYXJHcmFkaWVudCBpZD0icGFpbnQwX2xpbmVhcl8yODIxXzMxNjcyIiB4MT0iMTIiIHkxPSIwIiB4Mj0iMTIiIHkyPSIyNCIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPgo8c3RvcCBzdG9wLWNvbG9yPSIjQzE4M0ZGIi8%2BCjxzdG9wIG9mZnNldD0iMSIgc3RvcC1jb2xvcj0iIzREQzlGRiIvPgo8L2xpbmVhckdyYWRpZW50Pgo8L2RlZnM%2BCjwvc3ZnPgo%3D)](https://app.osaas.io/browse/eyevinn-player-analytics-eventsink)\n\n# Player Analytics Client SDK Web\n\nPart of [Eyevinn Player Analytics Specification (EPAS)](https://github.com/Eyevinn/player-analytics-specification). To be used together with [Eyevinn Player Analytics Eventsink](https://github.com/Eyevinn/player-analytics-eventsink)\n\n```\nnpm install @eyevinn/player-analytics-client-sdk-web\n```\n\n## EPAS backend in Open Source Cloud\n\nThe quickest way to get started is to setup an EPAS compatible backend in [Eyevinn Open Source Cloud](https://www.osaas.io)\n\n![EPAS pipeline in OSC](pipeline.png)\n\n1. Setup an Eventsink in OSC as described in the [documentation](https://docs.osaas.io/osaas.wiki/Service%3A-Player-Analytics-Eventsink.html).\n2. Setup an Analytics Worker and Clickhouse Database by following the instructions in the [documentation](https://docs.osaas.io/osaas.wiki/Service%3A-Player-Analytics-Worker.html)\n3. Add Clickhouse as datasource in Grafana and start visualizing the metrics\n\n## Usage\n\n### Automatic Event Listening\n\n```js\nimport { PlayerAnalyticsConnector } from \"@eyevinn/player-analytics-client-sdk-web\";\n\n// Create your instance and set the analytics eventsink endpoint\nconst playerAnalytics = new PlayerAnalyticsConnector(\n  \"https://your-eventsink-url.io\"\n);\n\n// Initiate the analytics with the base data needed\n// This will create you session in the backend\ntry {\n  await playerAnalytics.init({\n    sessionId: \"generated-unique-uuid-session-id\",\n  });\n\n  // Get your video element from the site, or your video player of choice\n  const videoElement = document.querySelector(\"video\");\n  // Load the analytics library with the video element to fetch the events\n  playerAnalytics.load(videoElement);\n} catch (err) {\n  console.error(err);\n  // Remove event listeners and heartbeat timers if init fails.\n  playerAnalytics.deinit();\n}\n```\n\nDue to bitrate changes not being reported, and errors not being reported in any descriptive way, there is a possibility to do separate calls for these events - which you may trigger based on you video player of choice following these examples.\n\n```js\nplayerAnalytics.reportBitrateChange({\n  bitrate: 246.440, // bitrate in Kbps\n  width: 320, // optional, video width in pixels\n  height: 136, // optional, video height in pixels\n  videoBitrate: 0, // optional, if available provide the bitrate for the video track\n  audioBitrate: 0, // optional, if available provide the bitrate for the audio track\n});\n```\n\n```js\n// error is fatal, i.e. sends an end event as well\nplayerAnalytics.reportError({\n  category: \"\", // optional, eg. NETWORK, DECODER, etc.\n  code: \"\",\n  message: \"\", // optional\n  data: {}, // optional\n});\n\n// warning is not fatal\nplayerAnalytics.reportWarning({\n  category: \"\", // optional, eg. NETWORK, DECODER, etc.\n  code: \"\",\n  message: \"\", // optional\n  data: {}, // optional\n});\n```\n\n```js\n// when leaving the player, to stop the analytics in a correct manor\nplayerAnalytics.reportStop();\nplayerAnalytics.destroy();\n```\n\n### Manual Event Triggering\n\n```js\nimport { PlayerAnalytics } from \"@eyevinn/player-analytics-client-sdk-web\";\n\n// Create your instance and set the analytics eventsink endpoint\nconst playerAnalytics = new PlayerAnalytics(\"https://your-eventsink-url.io\");\nawait playerAnalytics.initiateAnalyticsReporter({\n  sessionId: \"generated-unique-uuid-session-id\",\n  contentId: \"big-buck-bunny-720\",\n  contentUrl:\n    \"https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/720/Big_Buck_Bunny_720_10s_1MB.mp4\",\n});\n\n// then trigger the method calls accordingly, e.g.\nconst videoElement = document.querySelector(\"video\");\nvideoElement.addEventListener(\"play\", () =\u003e {\n  playerAnalytics.playing({\n    event: \"playing\",\n    timestamp: Date.now(),\n    playhead: 0,\n    duration: 3600,\n    sessionId: \"generated-unique-uuid-session-id\",\n  });\n});\n```\n\n### Report Metadata\n\nYou can report your metadata at a later stage in your code and tailor ther callbacks for your tech stach, for example when you have parsed your manifest.\nIn this example we're using hls.js\n\n```js\nimport Hls from \"hls.js\";\nimport { PlayerAnalyticsConnector } from \"@eyevinn/player-analytics-client-sdk-web\";\n\n// Create your instance and set the analytics eventsink endpoint\nconst playerAnalytics = new PlayerAnalytics(\"https://your-eventsink-url.io\");\nawait playerAnalytics.initiateAnalyticsReporter({\n  sessionId: \"generated-unique-uuid-session-id\",\n});\n\nconst hls = new Hls();\nconst videoElement = document.querySelector(\"video\");\n\nhls.attachMedia(videoElement);\nhls.load(src);\nhls.on(Hls.Events.LEVEL_LOADED, (event, data) =\u003e {\n  playerAnalytics.metadata({\n    live: data?.details?.level?.live,\n  });\n});\n```\n\nThese are the available keys for metadata, which can be sent anytime between a `init` and a `stopped` call.\n\n```ts\nexport interface TMetadataEventPayload {\n    live?: boolean;\n    contentTitle?: string;\n    contentId?: string;\n    contentUrl?: string;\n    drmType?: string;\n    userId?: string;\n    deviceId?: string;\n    deviceModel?: string;\n    deviceType?: string;\n}\n```\n\n### Constructor parameters\n\nThese applies to both the `PlayerAnalyticsConnector` and `PlayerAnalytics`.\n\n- `eventsinkUrl`, the url to your event sink.\n- `debug`, default false, triggers output to dev console rather than actual http posts.\n\n### Init parameters\n\n```ts\nexport interface IPlayerAnalyticsInitOptions {\n  sessionId?: string; // should be generated by the backend if not sent in\n  hearbeatInterval?: number; //Defaults to 30_000 (ms)\n}\n```\n\n## Development\n\nRun the demo page by `npm start`\n\n## Release\n\n- Pull latest master\n- `npm version patch | minor | major`\n- This triggers an update of the version in package.json + creates a tag with that version number\n- This will automatically be pushed to Github upon success.\n- At github.com go to releases (far right)\n  - click \"Draft a new release\"\n  - choose your tag\n  - give it a name (preferably your version number, e.g. `v0.0.1`)\n  - click \"Auto-generate release notes\"\n  - click \"Publish release\"\n- A Github Action is triggered to do the releases towards the npmjs and github packages repositories.\n\u003cbr/\u003e\n\u003cbr/\u003e\n\n# About Eyevinn\nWe are [Eyevinn Technology](https://www.eyevinntechnology.se/), and we help companies in the TV, media, and entertainment sectors optimize costs and boost profitability through enhanced media solutions. We are independent in a way that we are not commercially tied to any platform or technology vendor. As our way to innovate and push the industry forward, we develop proof-of-concepts and tools. We share things we have learn and code as open-source.\n\nWith Eyevinn Open Source Cloud we enable to build solutions and applications based on Open Web Services and avoid being locked in with a single web service vendor. Our open-source solutions offer full flexibility with a revenue share model that supports the creators.\n\nRead our blogs and articles here:\n\n- [Developer blogs](https://dev.to/video)\n- [Medium](https://eyevinntechnology.medium.com/)\n- [OSC](https://blog.osaas.io)\n- [LinkedIn](https://www.linkedin.com/company/eyevinn/)\n\nWant to know more about Eyevinn, contact us at [info@eyevinn.se](mailto:info@eyevinn.se)!\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEyevinn%2Fplayer-analytics-client-sdk-web","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FEyevinn%2Fplayer-analytics-client-sdk-web","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEyevinn%2Fplayer-analytics-client-sdk-web/lists"}