diff --git a/CHANGELOG.md b/CHANGELOG.md index 73102bc..8531c54 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [3.3.0] - 2020-11-04 +### Added +- Adding VISION and CONTRIBUTING files. + +### Changed +- Updating README file. + ## [3.0.0] - 2020-09-04 ### BREAKING CHANGES - It is necessary pass an object to create an event. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3e23da1..89c22a6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -110,6 +110,7 @@ Before merging a code in a **Pull Request** to the `master` branch, it is requir * The branch must be **updated** with the latest commit of `master` branch. * The required fields in the issue are **filled**. * The package.json version must be bumped following the [Semver](https://semver.org/) convention. +* The [CHANGELOG](CHANGELOG.md) must be updated with relevant information about the changes that have been made. ## Release diff --git a/README.md b/README.md index 815261a..7531cf4 100644 --- a/README.md +++ b/README.md @@ -1,112 +1,65 @@ -# huha.js # +# HUHA -![Chimo Bayo GIF](https://img.buzzfeed.com/buzzfeed-static/static/2015-07/9/15/enhanced/webdr06/anigif_enhanced-28562-1436468716-8.gif?downsize=715:*&output-format=auto&output-quality=auto) +This repository contains the source code for HUHA (Hyperactive Users Hint Analysis). -huha.js (Hyperactive Users Hint Analysis) is a JavaScript -framework that measures the usability and user experience -in an automated way, including the limitations of the -model and the best practices. +HUHA is a JavaScript library that helps measure the usability and user experience of a project in an automated way. -## Documentation ## +1. [Vision](VISION.md) +1. [Code Owners](CODEOWNERS) +1. [Contributing](CONTRIBUTING.md) +1. [Installation](#installation) +1. [Usage](#usage) +1. [Prerequisites](#prerequisites) +1. [References](#references) -### Installation ### +## Installation -#### NPM #### - -NPM is the recommended installation method +If you want to contribute to the library then you will have to clone the repository and install all dependencies: +```sh +git clone https://github.com/Ebury/huha.git +cd huha +npm install ``` + +## Usage + +If you want to use the library in your project then you will have to install it (via [npm](https://www.npmjs.com/package/@ebury/huha)) as a dependency: + +```sh npm install github:Ebury/huha --save ``` -Then you can import the `Huha` class in your application +And then you can import the `Huha` class in your application: ```javascript import Huha from '@ebury/huha' ``` -#### CDN #### - -Alternatively, you can load the script directly from our cdn +Alternatively, you can load the script directly from our `cdn`, specifying the desired version: ```html - + ``` -### Reference ### - -#### `Huha` class #### - -Method | Description | -------------- | ------------- | -`constructor(options)` | Instantiates a new `Huha` class with the given `options`. The `options` argument is an object containing the configuration of the class. Options available are:
- `trackOnGoogleAnalytics` (Boolean): Indicates if the task need to be tracked on Google Analytics
- `trackOnIntercom` (Boolean): Indicates if the task need to be tracked on Intercom
- `trackOnSegment` (Boolean): Indicates if the task need to be tracked on Segment -`createTask({ name: 'TaskName' })` | Creates and returns a `HuhaTask` class. The `properties` argument is an object containing the given `name` and the other fields are used for providing extra context:
- `label`: Label of the task (by default is the task name)
- `category`: Name of the category of the task
- `value`: Value of the action done to the object
- `parentTask` (Object): Huha parent task. Use it to link child tasks to a parent task via the execId
- `execId` (String): Identifier to link events to tasks
- `persistent` (Boolean): Indicates if the task should be persisted. If the task is persisted, it will be saved on localStorage and you will need to abandon it manually. -`getTask(name)` | Gets an in progress task giving its `name` -`createEvent({ name: 'EventName' })` | Creates, tracks (*) and returns a `HuhaEvent` class with the given `name`. The `properties` argument is an object containing the given `name` and the other fields are used for providing extra context:
- `object`: Name of the object that is being manipulated during the event
- `action`: Name of the action that is being executed in the object during the event
- `category`: Name of the the section og this event, so it can be grouped as categories
- `value`: Value of the action done to the object
- `eventGroup`: Identifier of the group this event is linked to
- `task`: Task associated to the event - -(*) The event is tracked in Google Analytics or Segment based on the `Huha` options. +### API Reference -#### `HuhaTask` class #### +You can visit [Reference](REFERENCE.md) to check the reference. -Method | Description | -------------- | ------------- | -`addInteraction()` | Increments the count of effort in 1 -`addError()` | Increments the count of errors in 1 -`complete()` | Marks the task as completed (*) -`abandon()` | Marks the task as abandoned (*) +## Prerequisites -(*) When a task is completed or abandoned, is is tracked in Google Analytics, Intercom or Segment based on the `Huha` options. +For the correct registration of the information in the tracking tools it is required that the set-up scripts of those tools to be used have been executed, which will define the necessary global variables. For instance, if the option `trackOnSegment` is set to `true`, HUHA expects to find the Segment corresponding global variable, [analytics](https://segment.com/docs/connections/sources/catalog/libraries/website/javascript/quickstart/), filled in. -#### Example #### +## References -```javascript -import Huha from '@ebury/huha'; - -const huha = new Huha({ - trackOnGoogleAnalytics: false, - trackOnIntercom: false, - trackOnSegment: true, -}); -const huhaTask = huha.createTask({ name: 'TaskName' }); -huhaTask.addInteraction(); -huhaTask.addError(); -huhaTask.complete(); -``` - -### Automatic tasks ### -It is possible to create tasks and measuring the user activity directly in the DOM without writing Javascript. - -Any user activity done in DOM elements having the `data-huha-task` attribute will be monitored using the following -attributes: +[JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) -Attribute | Description | -------------- | ------------- | -`data-huha-task` | Name of the task that will store the user activity related with the DOM element -`data-huha-trigger` | Javascript event that is listened to for storing the activity: click, focus or change -`data-huha-event` | Type of user activity that is stored when the Javascript event is triggered:
- start: Beginning of the task
- complete: Completion of the task
- abandon: Abandonment of the task
- interaction: New interaction in the task
- error: New error in the task - -#### Example #### - -```html - - - - - - -``` +[Jest](https://jestjs.io/) -## Our story ## +[npm](https://www.npmjs.com/) -We thought we had to honour the great Chimo Bayo, -we’ve programmed this while listenting all his hits -“asi me gusta” and the must-listen “techno valencia”, -then we thought what if a user interacts with our app -while listenting Chimo Bayo? Bang! There you have your -Hyperactive User and here we have our Hint Analytics. -It makes totally sense for us. +[Google Analytics](https://analytics.google.com/analytics/web/) +[Intercom](https://www.intercom.com/) +[Segment](https://segment.com/). diff --git a/REFERENCE.md b/REFERENCE.md new file mode 100644 index 0000000..90f2964 --- /dev/null +++ b/REFERENCE.md @@ -0,0 +1,75 @@ +# Reference + +## `Huha` class + +Method | Description | +------------- | ------------- | +`constructor(options)` | Instantiates a new `Huha` class with the given `options`. The `options` argument is an object containing the configuration of the class. Options available are:
- `trackOnGoogleAnalytics` (Boolean): Indicates if the task need to be tracked on Google Analytics.
- `trackOnIntercom` (Boolean): Indicates if the task need to be tracked on Intercom.
- `trackOnSegment` (Boolean): Indicates if the task need to be tracked on Segment. +`createTask({ name: 'TaskName' })` | Creates and returns a `HuhaTask` class. The `properties` argument is an object containing the given `name` and the other fields are used for providing extra context:
- `label`: Label of the task (by default is the task name).
- `category`: Name of the category of the task.
- `value`: Value of the action done to the object.
- `parentTask` (Object): Huha parent task. Use it to link child tasks to a parent task via the execId.
- `execId` (String): Identifier to link events to tasks.
- `persistent` (Boolean): Indicates if the task should be persisted. If the task is persisted, it will be saved on localStorage and you will need to abandon it manually +`getTask(name)` | Gets an in progress task giving its `name` +`createEvent({ name: 'EventName' })` | Creates, tracks (*) and returns a `HuhaEvent` class with the given `name`. The `properties` argument is an object containing the given `name` and the other fields are used for providing extra context:
- `object`: Name of the object that is being manipulated during the event.
- `action`: Name of the action that is being executed in the object during the event.
- `category`: Name of the the section of this event, so it can be grouped as categories.
- `value`: Value of the action done to the object.
- `eventGroup`: Identifier of the group this event is linked to.
- `task`: Task associated to the event. + +(*) The event is tracked in Google Analytics or Segment based on the `Huha` options. + +## `HuhaTask` class + +Method | Description | +------------- | ------------- | +`addInteraction()` | Increments the count of effort in 1. +`addError()` | Increments the count of errors in 1. +`complete()` | Marks the task as completed. (*) +`abandon()` | Marks the task as abandoned. (*) + +(*) When a task is completed or abandoned, it is tracked in Google Analytics, Intercom or Segment based on the `Huha` options. + +Example: + +```javascript +import Huha from '@ebury/huha'; + +const huha = new Huha({ + trackOnGoogleAnalytics: false, + trackOnIntercom: false, + trackOnSegment: true, +}); + +const huhaTask = huha.createTask({ name: 'TaskName' }); +huhaTask.addInteraction(); +huhaTask.addError(); +huhaTask.complete(); + +const huhaEvent = huha.createEvent({ + name: 'Event Name', + action: 'Click', + category: 'Dashboard', + object: 'Download button', + task: huhaTask +}); +``` + +## Automatic tasks + +It is possible to create tasks and measuring the user activity directly in the DOM without writing Javascript. + +Any user activity done in DOM elements having the `data-huha-task` attribute will be monitored using the following +attributes: + +Attribute | Description | +------------- | ------------- | +`data-huha-task` | Name of the task that will store the user activity related with the DOM element. +`data-huha-trigger` | Javascript event that is listened to for storing the activity: click, focus or change. +`data-huha-event` | Type of user activity that is stored when the Javascript event is triggered:
- start: Beginning of the task.
- complete: Completion of the task.
- abandon: Abandonment of the task.
- interaction: New interaction in the task.
- error: New error in the task. + +Example: + +```html + + + + + + +``` diff --git a/package-lock.json b/package-lock.json index 87999d6..35ea83f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "@ebury/huha", - "version": "3.2.0", + "version": "3.3.0", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/package.json b/package.json index a4e2839..0b862b8 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@ebury/huha", "description": "huha.js (Hyperactive Users Hint Analysis) is a JavaScript framework that measures the usability and user experience in an automated way, including the limitations of the model and the best practices.", - "version": "3.2.0", + "version": "3.3.0", "repository": "github:Ebury/huha", "license": "MIT", "scripts": {