feat(FEC-8629): add hooks to kava to enable analytics event tampering…

… and sending custom events (#26)

Add tamperAnalyticsHandler config option and expose sendAnalytics API.
Read more from the docs.

README.md

@@ -56,16 +56,13 @@ var config = {
     partnerId: {PARTNER_ID}
     ...
   },
-  player: {
-   plugins: {
-     kava: {
-        ...
-     }
-    ...
-   }
+  plugins: {
+    kava: {
+       ...
+    }
    ...
   }
- ...
+...
 };
 var player = KalturaPlayer.setup(config);
 player.loadMedia({
@@ -79,7 +76,7 @@ player.loadMedia({
 
 ### Table of Contents
 
-- [Configuration](./docs/configuration.md)
+- [Configuration & API](docs/configuration-api.md)
 - [Events](./docs/kava-events.md)
 - [Parameters](./docs/kava-parameters.md)
 

docs/configuration-api.md

@@ -0,0 +1,106 @@
+# Configuration & API
+
+### Table of Contents
+
+- [KavaConfigObject](#kavaconfigobject)
+  - [tamperAnalyticsHandler](#tamperanalyticshandler)
+- [Kava](#kava)
+  - [destroy](#destroy)
+  - [reset](#reset)
+  - [sendAnalytics](#sendanalytics)
+  - [defaultConfig](#defaultconfig)
+  - [isValid](#isvalid)
+
+## KavaConfigObject
+
+Type: [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)
+
+**Properties**
+
+- `serviceUrl` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** The Kaltura API server.
+- `viewEventCountdown` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** The interval in seconds that VIEW event will be sent.
+- `resetSessionCountdown` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** The interval in seconds that Kava session will be reset.
+- `dvrThreshold` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Threshold in seconds from the live edge.
+- `applicationVersion` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Used to send the application version from which the user is playing the entry.
+- `playbackContext` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Used to send the id of the category from which the user is playing the entry.
+- `tamperAnalyticsHandler` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)?** An optional handler to implement. Can be used to manipulate the model data before analytics event sent, or to cancel a certain analytics request.
+- `customVar1` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Custom objects field.
+- `customVar2` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Custom objects field.
+- `customVar3` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Custom objects field.
+
+**Examples**
+
+```javascript
+// Default config
+{
+  serviceUrl: '//analytics.kaltura.com/api_v3/index.php',
+  viewEventCountdown: 30,
+  resetSessionCountdown: 30,
+  dvrThreshold: 120,
+  applicationVersion: '',
+  playbackContext: ''
+}
+```
+
+### tamperAnalyticsHandler
+
+**Parameters**
+
+- `model` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Event model
+
+**Examples**
+
+```javascript
+tamperAnalyticsHandler: function (model) {
+     // Always add myCustomFlag but don't send the request if the event type equals to 2
+     model.myCustomFlag = true;
+     if (model.eventType !== 2) {
+       return true;
+     }
+     return false;
+   }
+```
+
+Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Should send the request or not.
+
+## Kava
+
+**Extends BasePlugin**
+
+**Parameters**
+
+- `name` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The plugin name.
+- `player` **Player** The player instance.
+- `config` **[KavaConfigObject](#kavaconfigobject)** The plugin config.
+
+### destroy
+
+Destroys the plugin.
+
+Returns **void**
+
+### reset
+
+Reset the plugin.
+
+Returns **void**
+
+### sendAnalytics
+
+Sends KAVA analytics event to analytics service.
+
+**Parameters**
+
+- `model` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Event model.
+
+Returns **void**
+
+### defaultConfig
+
+Default config of the plugin.
+
+Type: [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)
+
+### isValid
+
+Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Whether the plugin is valid in the current environment.

flow-typed/types/kava-config.js

@@ -0,0 +1,54 @@
+// @flow
+
+/**
+ * @typedef {Object} KavaConfigObject
+ * @property {string} [serviceUrl] - The Kaltura API server.
+ * @property {number} [viewEventCountdown] - The interval in seconds that VIEW event will be sent.
+ * @property {number} [resetSessionCountdown] - The interval in seconds that Kava session will be reset.
+ * @property {number} [dvrThreshold] - Threshold in seconds from the live edge.
+ * @property {string} [applicationVersion] - Used to send the application version from which the user is playing the entry.
+ * @property {string} [playbackContext] - Used to send the id of the category from which the user is playing the entry.
+ * @property {Function} [tamperAnalyticsHandler] - An optional handler to implement. Can be used to manipulate the model data before analytics event sent, or to cancel a certain analytics request.
+ * @property {Object} [customVar1] - Custom objects field.
+ * @property {Object} [customVar2] - Custom objects field.
+ * @property {Object} [customVar3] - Custom objects field.
+ * @example
+ * // Default config
+ * {
+ *  serviceUrl: '//analytics.kaltura.com/api_v3/index.php',
+ *  viewEventCountdown: 30,
+ *  resetSessionCountdown: 30,
+ *  dvrThreshold: 120,
+ *  applicationVersion: '',
+ *  playbackContext: ''
+ * }
+ */
+type _KavaConfigObject = {
+  serviceUrl?: string,
+  viewEventCountdown?: number,
+  resetSessionCountdown?: number,
+  dvrThreshold?: number,
+  customVar1?: Object,
+  customVar2?: Object,
+  customVar3?: Object,
+  applicationVersion?: string,
+  playbackContext?: string,
+  tamperAnalyticsHandler?: Function
+};
+
+/**
+ * @function tamperAnalyticsHandler
+ * @param {Object} model - Event model
+ * @memberof KavaConfigObject
+ * @returns {boolean} - Should send the request or not.
+ * @example
+ * tamperAnalyticsHandler: function (model) {
+ *      // Always add myCustomFlag but don't send the request if the event type equals to 2
+ *      model.myCustomFlag = true;
+ *      if (model.eventType !== 2) {
+ *        return true;
+ *      }
+ *      return false;
+ *    }
+ */
+declare type KavaConfigObject = _KavaConfigObject;

karma.conf.js

@@ -17,7 +17,7 @@ const customLaunchers = {
 module.exports = function(config) {
   let karmaConf = {
     logLevel: config.LOG_INFO,
-    browsers: ['Chrome', 'Firefox'],
+    browsers: ['Chrome'],
     browserDisconnectTimeout: 30000,
     browserNoActivityTimeout: 60000,
     concurrency: 1,

package.json

@@ -14,7 +14,9 @@
     "eslint": "eslint . --color",
     "flow": "flow check",
     "commit:dist": "git add --force --all dist && (git commit -m 'chore: update dist' || exit 0)",
-    "precommit": "lint-staged"
+    "precommit": "lint-staged",
+    "docs:generate": "documentation build flow-typed/** src/** -f md",
+    "docs:serve": "documentation serve flow-typed/** src/** --watch"
   },
   "lint-staged": {
     "*.{js,jsx}": [
@@ -44,6 +46,7 @@
     "copy-webpack-plugin": "^4.3.1",
     "cross-env": "^3.1.4",
     "css-loader": "^0.28.4",
+    "documentation": "^8.1.2",
     "eslint": "^3.10.0",
     "eslint-config-prettier": "^2.9.0",
     "eslint-loader": "^1.6.1",

src/kava-event-model.js

@@ -118,6 +118,7 @@ export const KavaEventModel: {[event: string]: KavaEvent} = {
 
 /**
  * Gets the full event model for a certain event object including the common params.
+ * @private
  * @param {KavaEvent} eventObj - The event model.
  * @param {KavaModel} model - The plugin model store.
  * @returns {Object} - The full event model.