@bruit/component

bruit.io

bruit.io is a Web Component built with Stencil.js

Available on all frameworks that support Web Components such as

---

bruit.io is a tool to get your users feedbacks, designed to be as simple to use as possible, following the Web Components standards. Users' feedbacks are sent directly to your favorite project management tools 🎉 .

bruit.io is built around an open source Web Component and a backend reciving the users feedback.

And we do no data retention at all about those feedbacks 👏

---

Getting started

start on bruit.io

By default, bruit.io component posts feedbacks to bruit.io api. If you wish, It can be connected with your own.

The free bruit.io api allows to pass feedbacks on to tools such as

Table of Contents

Installation
Usage
Configuration
    BrtConfig
    BrtCoreConfig
    BrtField
    BrtLabels
    BrtColors
    BrtLogCacheLength
Add data in feedbacks
Handle errors
Send a feedback without modal
Frameworks integration
Contributing
Known issues
Having troubles?

Installation

bruit.io can be installed either with a command line

npm install @bruit/component --save

Or by directly modifying your index.html file

<script src="https://unpkg.com/@bruit/component/dist/bruit.js"></script>

---

Usage

Simply add this tag wherever you want in your project:

<bruit-io> ... optional element to click ... </bruit-io>

These properties are available on the component:

• brt-config (required)
• brt-data (optional)
• brt-data-fn (optional)
• onError (optional)

Integration code examples are available for these platforms:

              

Configuration

bruit-io Web Component has a config attribute, which takes a value of BrtConfig type.

defineBruitElements function which takes a configuration of BrtCoreConfig type.

BrtConfig

Describes the options for the bruit-io component

interface BrtConfig {
  apiKey?: string;
  form: Array<BrtField>;
  labels?: BrtLabels;
  colors?: BrtColors;
  closeModalOnSubmit?: boolean;
  apiUrl?: string;
  durationBeforeClosing?: number;
  elementToRenderSelector?: string;
  screenshot?: {
    maxWidth?: number,
    maxHeight?: number,
    imageType?: string,
    compression?: number
  }
}

Attribute	Type	Description	Mandatory	Default value
apiKey	string	your personal api key (create an api key)	no	-
form	array<BrtField>	inputs list for the generated form	yes	-
labels	BrtLabels	describes the labels of the modal (title / button / ...)	no	see
colors	BrtColors	Allows to pick your colors in the modal theming	no	see
closeModalOnSubmit	boolean	true to have modal closed automatically on submit (feedback is sent in background)	no	false
apiUrl	string	Allows to use some third party backend for feedback processing	no	see
durationBeforeClosing	number	Allows to define a number of milliseconds before the popup gets closed	no	-
elementToRenderSelector	string	sets the css selector of the element to use as the root of the rendering for the screenshot	no	document.body
screenshot.maxWidth	number	the maximum width of the generated screenshot. Set it to have the screenshot resized when it's too large	no	-
screenshot.maxHeight	number	the maximum height of the generated screenshot. Set it to have the screenshot resized when it's too tall	no	-
screenshot.imageType	image/png ; image/jpeg	the type of image to generate	no	image/png
screenshot.compression	number	the compression to apply to the screenshot between 1 (no compression) and 0 (fully compressed) ; only applies to image/jpeg type	no	0.9

Typescript import :

import { BrtConfig } from '@bruit/component';

BrtCoreConfig

Describes the options for the bruit core

interface BrtCoreConfig {
  logCacheLength?: BrtLogCacheLength;
  addQueryParamsToLog?: boolean;
}

Attribute	Type	Description	Mandatory	Default value
logCacheLength	BrtLogCacheLength	Used to filter the logs to send by their level (debug, warn, error, etc)	no	see
addQueryParamsToLog	boolean	Used to tell wether the parameters of the query parameters should be displayed in the logs	no	false

Typescript import :

import { BrtCoreConfig } from '@bruit/component';

BrtField

Describes both the fields displayed in the popup form and the users' answers.

interface BrtField {
  id?: string;
  label: string;
  type: BrtFieldType;
  required?: boolean;
  value?: any;
  max?: number;
}

Attribute	Type	Description	Mandatory
id	string	Unique identifier for the field	no
label	string	Placeholder / label for the field	yes
type	BrtFieldType	The input type of the field	yes
required	boolean	true to make the field required to send the feedback	no
value	any	The value typed by the user	no
max	number	max number for rating type	no

BrtConfig.form must contain one BrtField with id="agreement" and type="checkbox", used to check whether personal data should be sent with the feedback.

There are special values for the id attribute:

• agreement: sets the field to use to check whether user agrees to send his personal data
• title: sets the field used to display the title of feedback

Typescript import:

import { BrtField } from '@bruit/component';

BrtLabels

Used to describe the texts displayed in the modal.

interface BrtLabels {
  title?: string;
  introduction?: string;
  button?: string;
}

Attribute	Description	Default value
title	Defines the title of the modal	bruit.io
introduction	Defines the description text	send a feedback
button	Defines the text of the submit button	send

Typescript import:

import { BrtLabels } from '@bruit/component';

BrtColors

If you feel like an artist 🎨 , you may use BrtColors to change the theme of the modal.

This gives the possiblity to change the header, body, background, errors and focus colors.

Only hexadecimal values are allowed here.

interface BrtColors {
  header?: string;
  body?: string;
  background?: string;
  errors?: string;
  focus?: string;
}

Attribute	Description	Default value
header	the modal's header color	#2D8297
body	the color for the background of the modal	#eee
background	the color used to dim what's behind the modal	#444444ee
errors	the text color to use for errors	#c31313
focus	the color to use on focused field	#1f5a6

Typescript import:

import { BrtColors } from '@bruit/component';

BrtLogCacheLength

By default, all log levels (log, warn, errors, ...) are sent in the feedback. BrtLogCacheLength allows to disable specific ones.

To disable a type, just set the related type to 0 in the logCacheLength section of core configuration:

{
  "logCacheLength": {
    "log": 0,
    ...
  }
}

interface BrtLogCacheLength {
  log?: number;
  debug?: number;
  info?: number;
  warn?: number;
  error?: number;
  network?: number;
  click?: number;
  url?: number;
}

bruit.io adds special types of logs:

• network type is for your fetch and xmlHttpRequest calls.
• click type is for mouse click event.
• url type logs all url changing

Typescript import:

import { BrtLogCacheLength } from '@bruit/component';

BrtFeedback

By default, bruit.io component posts a feedback to bruit.io API (https://api.bruit.io/feedback).

If you wish, it can be connected with your own API.

To do it, you must provide a API endpoint, to be passed to BrtConfig as apiUrl.

bruit.io component posts a BrtFeedback to your API endpoint.

interface BrtFeedback {
  apiKey?: string;
  canvas?: string;
  url?: string;
  cookies?: BrtCookies;
  navigator?: BrtNavigatorInfo;
  display?: BrtScreenInfo;
  logs?: Array<BrtLog>;
  data: Array<BrtData>;
}

Typescript import:

import { BrtFeedback } from '@bruit/types';

Add data to the feedback

It is possible to automatically had technical data in the feedback, for example the version number of your application, the identifier of the user sending the feedback, etc.

This is done by using either the brt-data or brt-data-fn property on the component.

data

brt-data property is used to send an array of objects to add to the feedback to the component.

The property takes a BrtData array as a value.

dataFn

brt-data-fn property takes a function as a value. The function should return either an array of BrtData or a promise of an array of BrtData.

BrtData

Used to pass additional data to the feedback (ie the application version number)

interface BrtData {
  label: string;
  type?: string;
  value: any;
  id?: string;
}

Attribute	Type	Description	Mandatory
label	string	a label for the data	yes
type	string	the type of the data	no
value	any	the value to send	yes
id	string	an identifier for the data	no

Typescript import:

import { BrtData } from '@bruit/component';

Handle errors

event

bruit-io emits onError events when an error occurs.

An error is of type BrtError, composed by a code and a text.

more information about errors

BrtError

Format of the errors which may be sent by the component.

interface BrtError {
  code: number;
  text: string;
}

Typescript import:

import { BrtError } from '@bruit/component';

Send a feedback silently

You may want to skip bruit-io default modal, for example :

• to send a feedback from an another modal
• to send a feedback from a catched error
• to send a feedback on a particular situation in your application

To programatically send a feedback, use Bruit's send core function:

import :

import { Bruit } from '@bruit/component/dist/core';

usage :

Bruit.send('myApiKey', true, myData, myDataFunction)
  .then(() => console.log('success'))
  .catch(error => console.error(error));

OR

var Bruit = document.querySelector('bruit-core');

usage :

Bruit.sendFeedback('myApiKey', true, myData, myDataFunction)
  .then(() => console.log('success'))
  .catch(error => console.error(error));

send (or sendFeedback) function take 4 parameters :

Parameter	Type	Description	Mandatory
apiKey	string	your api key	yes
agreement	boolean	set to true to send user personal data (device, sreenshot, logs, ...)	no
data	Array<BrtData>	an array of additional data to show in feedback	no
dataFn	Promise<Array<BrtData>>	a Promise or a simple function returning an array of additional data to show in feedback	no

Framework integrations

JavaScript

Integrating bruit-io component to a project without a JavaScript framework is pretty straight forward. When using a simple HTML page, bruit.io can be added from a CDN as follows:

<!DOCTYPE html>
<html lang="en">
  <head>
    <script src="https://unpkg.com/@bruit/component/dist/bruit.js"></script>
  </head>
  ...
</html>

Then, you may add the bruit-io component directly:

<body>
  <bruit-io></bruit-io>
  ...
  <script>
    var bruitCmp = document.querySelector('bruit-io');
    bruitCmp.addEventListener('onReady', function () {
      bruitCmp.start();
    });
    bruitCmp.config = {
      // whatever your config is
    };
  </script>
</body>

Or, should you load different pages and the component would not be on the main one, you can include the bruit-core component and initialise the framework from the same location

<body>
  <bruit-core ></bruit-core>
  ...
  <script>
    var bruitCore = document.querySelector('bruit-core');
    if (bruitCore) {
      bruitCore.config = {
        // whatever your config is
      };
    }
  </script>
</body>

You may then add bruit-io component anywhere else.

from stencil documentation

Angular

Using bruit-io component within an Angular project is a two-step process. You need to:

1. Include the CUSTOM_ELEMENTS_SCHEMA in the modules that use the components
2. Call defineBruitElements() from main.ts (or some other appropriate place)

Including the Custom Elements Schema

Including the CUSTOM_ELEMENTS_SCHEMA in the module allows the use of Web Components in the HTML files. Here is an example of adding it to AppModule:

import { BrowserModule } from '@angular/platform-browser';
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule],
  bootstrap: [AppComponent],
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppModule {}

The CUSTOM_ELEMENTS_SCHEMA needs to be included in any module that uses bruit.io.

Calling defineBruitElements

bruit.io component includes a function used to load itself in the application window object. That function is called defineBruitElements() and needs to be executed once during the bootstrapping of your application. One convenient place to add it is in the main.ts file as follows:

import { enableProdMode } from '@angular/core';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';

import { AppModule } from './app/app.module';
import { environment } from './environments/environment';

import { defineBruitElements } from '@bruit/component/dist/init';

if (environment.production) {
  enableProdMode();
}

platformBrowserDynamic()
  .bootstrapModule(AppModule)
  .catch(err => console.log(err));
defineBruitElements();

Using bruit.io in an Angular component

<bruit-io
  [brt-config]="bruitConfig"
  [brt-data]="bruitData"
  [brt-dataFn]="bruitDataPromise()"
  (brt-onError)="handleBruitError($event)"
></bruit-io>

public bruitConfig: BrtConfig = {
  apiKey:"xxxxxxxxxxx",
  form:[...]
};

public bruitData: Array<BrtData> = [
  {
    label:"version",
    value: environment.version
  }
];

constructor(private api : ApiService){}

bruitDataPromise(): Promise<Array<BrtData>>{
  return this.api.getUser().then( user =>
    [
      {
        label: "user id",
        value: user.id
      },
      {
        label: "user email",
        value: user.email
      }
    ]
  );
}

handleBruitError(error: BrtError){
  ...
}

from stencil documentation

React

With an application built using React CLI (namely create-react-app), the easiest way is to include the bruit-io component by calling the defineBruitElements() method in the index.js file.

import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import registerServiceWorker from './registerServiceWorker';

import { defineBruitElements } from '@bruit/component/dist/init';

ReactDOM.render(<App />, document.getElementById('root'));
registerServiceWorker();
defineBruitElements();

from stencil documentation

Vue

In order to use the bruit-io Web Component inside of a Vue application, it should be modified to define the custom elements and to inform the Vue compiler which elements to ignore during compilation. This can all be done within the main.js file as follows:

import Vue from 'vue';
import App from './App.vue';
import { defineBruitElements } from '@bruit/component/dist/init';

Vue.config.productionTip = false;
Vue.config.ignoredElements = [/bruit-\w*/];

defineBruitElements();

new Vue({
  render: h => h(App)
}).$mount('#app');

from stencil documentation

Contributing

Bruit.io web component is 100% free and open source. Contributing to bruit.io may involve writing TypeScript, TSX, Stencil, SCSS or Markdown depending on the component you are working on. We are looking for help in any of these areas!

Known issues

• Type 'CustomEvent' is not generic : component properties typing requires typescript version 2.7+.

Having troubles ?

• Github issues
• StackOverflow