| 1 | # Snowplow YouTube Tracking
|
| 2 |
|
| 3 | [![npm version][npm-image]][npm-url]
|
| 4 | [![License][license-image]](LICENSE)
|
| 5 |
|
| 6 | Browser Plugin to be used with `@snowplow/browser-tracker`.
|
| 7 |
|
| 8 | Adds YouTube Video and Audio tracking events to your Snowplow tracking.
|
| 9 |
|
| 10 | ## Maintainer quick start
|
| 11 |
|
| 12 | Part of the Snowplow JavaScript Tracker monorepo.
|
| 13 | Build with [Node.js](https://nodejs.org/en/) (12 LTS or 14 LTS) and [Rush](https://rushjs.io/).
|
| 14 |
|
| 15 | ### Setup repository
|
| 16 |
|
| 17 | ```bash
|
| 18 | npm install -g @microsoft/rush
|
| 19 | git clone https://github.com/snowplow/snowplow-javascript-tracker.git
|
| 20 | rush update
|
| 21 | ```
|
| 22 |
|
| 23 | ### Package Installation
|
| 24 |
|
| 25 | With npm:
|
| 26 |
|
| 27 | ```bash
|
| 28 | npm install @snowplow/browser-plugin-youtube-tracking
|
| 29 | ```
|
| 30 |
|
| 31 | ## Usage
|
| 32 |
|
| 33 | Initialize your tracker with the YouTubeTrackingPlugin:
|
| 34 |
|
| 35 | ```js
|
| 36 | import { newTracker } from '@snowplow/browser-tracker';
|
| 37 | import { YouTubeTrackingPlugin } from 'snowplow-browser-youtube-tracker';
|
| 38 |
|
| 39 | newTracker('sp2', '{{collector}}', { plugins: [ YouTubeTrackingPlugin() ] }); // Also stores reference at module level
|
| 40 | ```
|
| 41 |
|
| 42 | Then, use the `enableYouTubeTracking` function described below to produce events from your YouTube IFrame(s).
|
| 43 |
|
| 44 | ```js
|
| 45 | enableYouTubeTracking({ id, options?: { label?, captureEvents?, percentBoundries?, updateRate? } })
|
| 46 | ```
|
| 47 |
|
| 48 | | Parameter | Type | Default | Description | Required |
|
| 49 | | ----------------------- | ---------- | ------------------- | --------------------------------------------------------- | -------- |
|
| 50 | | `id` | `string` | - | The HTML id attribute of the youtube element | Yes |
|
| 51 | | `options.label` | `string` | - | An identifiable custom label sent with the event | No |
|
| 52 | | `options.captureEvents` | `string[]` | `['DefaultEvents']` | The name(s) of the events to capture | No |
|
| 53 | | `options.boundries` | `number[]` | `[10, 25, 50, 75]` | The progress percentages to fire an event at (if enabled) | No |
|
| 54 | | `options.updateRate` | `number` | `500` | The rate at which volume/seek events are checked in ms | No |
|
| 55 |
|
| 56 | ## Example Usage
|
| 57 |
|
| 58 | ```html
|
| 59 | ...
|
| 60 | <body>
|
| 61 | <video id="my-video" src="my-video.mp4">
|
| 62 | </body>
|
| 63 | ...
|
| 64 | ```
|
| 65 |
|
| 66 | ```js
|
| 67 | import { enableYouTubeTracking } from '@snowplow/browser-plugin-youtube-tracking'
|
| 68 |
|
| 69 | enableYouTubeTracking({
|
| 70 | id: 'my-video',
|
| 71 | options: {
|
| 72 | label: "My Custom Video Label",
|
| 73 | captureEvents: ["pause", "volumechange", "percentprogress"],
|
| 74 | boundries: [10, 25, 50, 75],
|
| 75 | }
|
| 76 | })
|
| 77 | ```
|
| 78 |
|
| 79 | ## Copyright and license
|
| 80 |
|
| 81 | Licensed and distributed under the [BSD 3-Clause License](LICENSE) ([An OSI Approved License][osi]).
|
| 82 |
|
| 83 | Copyright (c) 2022 Snowplow Analytics Ltd.
|
| 84 |
|
| 85 | All rights reserved.
|
| 86 |
|
| 87 | [npm-url]: https://www.npmjs.com/package/@snowplow/browser-plugin-form-tracking
|
| 88 | [npm-image]: https://img.shields.io/npm/v/@snowplow/browser-plugin-form-tracking
|
| 89 | [docs]: https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/javascript-tracker/
|
| 90 | [osi]: https://opensource.org/licenses/BSD-3-Clause
|
| 91 | [license-image]: https://img.shields.io/npm/l/@snowplow/browser-plugin-form-tracking |
| \ | No newline at end of file |