Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/moventes/bruit.io
bruit.io is a brilliant✨ easy to use feedback tool
https://github.com/moventes/bruit.io
angular bruit feedback react stencil trouble typescript vue web webcomponent
Last synced: about 1 month ago
JSON representation
bruit.io is a brilliant✨ easy to use feedback tool
- Host: GitHub
- URL: https://github.com/moventes/bruit.io
- Owner: Moventes
- License: mit
- Created: 2018-10-23T08:56:56.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2022-07-04T13:51:24.000Z (over 2 years ago)
- Last Synced: 2024-10-14T02:02:38.684Z (about 1 month ago)
- Topics: angular, bruit, feedback, react, stencil, trouble, typescript, vue, web, webcomponent
- Language: TypeScript
- Homepage: https://bruit.io/
- Size: 517 KB
- Stars: 65
- Watchers: 6
- Forks: 6
- Open Issues: 18
-
Metadata Files:
- Readme: readme.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
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
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](#installation)**
**[Usage](#usage)**
**[Configuration](#Configuration)**
**[BrtConfig](#BrtConfig)**
**[BrtField](#BrtField)**
**[BrtLabels](#BrtLabels)**
**[BrtColors](#BrtColors)**
**[Add data in feedbacks](#add-data-to-the-feedback)**
**[Handle errors](#handle-errors)**
**[Frameworks integration](#Framework-integrations)**
**[Contributing](#Contributing)**
**[Known issues](#known-issues)**
**[Having troubles?](#Having-troubles-)**
# Installation
bruit.io can be installed either with a command line
```bash
npm install @bruit/component --save
```
Or by directly modifying your `index.html` file
```html
```
---
# Usage
Simply add this tag wherever you want in your project:
```html
... optional element to click ...
```
These properties are available on the component:
- [_brt-config_](#configuration) (**required**)
- [_brt-data_](#Add-data-in-feedback) (optional)
- [_brt-data-fn_](#Add-data-in-feedback) (optional)
- [_onError_](#Handle-errors) (optional)
Integration code examples are available for these platforms:
## Configuration
> `bruit-io` Web Component has a `config` attribute, which takes a value of [BrtConfig](#brtconfig) type.
### _BrtConfig_
Describes the options for the `bruit-io` component
```ts
interface BrtConfig {
apiKey?: string;
form: Array;
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)](https://bruit.io/get-started) | no | - |
| **form** | array<[BrtField](#brtfield)> | inputs list for the generated form | **yes** | - |
| labels | [BrtLabels](#brtlabels) | describes the labels of the modal (title / button / ...) | no | [see](#brtlabels) |
| colors | [BrtColors](#BrtColors) | Allows to pick your colors in the modal theming | no | [see](#BrtColors) |
| 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](#BrtFeedback) |
| 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 :
```javascript
import { BrtConfig } from '@bruit/component';
```
### _BrtField_
Describes both the fields displayed in the popup form and the users' answers.
```ts
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:
```javascript
import { BrtField } from '@bruit/component';
```
### _BrtLabels_
Used to describe the texts displayed in the modal.
```ts
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:
```javascript
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.
```ts
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:
```javascript
import { BrtColors } from '@bruit/component';
```
### _BrtFeedback_
By default, bruit.io component posts a feedback to bruit.io API ().
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](#brtconfig) as `apiUrl`.
bruit.io component posts a `BrtFeedback` to your API endpoint.
```ts
interface BrtFeedback {
apiKey?: string;
canvas?: string;
url?: string;
cookies?: BrtCookies;
navigator?: BrtNavigatorInfo;
display?: BrtScreenInfo;
logs?: Array;
data: Array;
}
```
Typescript import:
```javascript
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)
```ts
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:
```javascript
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](https://github.com/Moventes/bruit.io/blob/master/DOC_ERRORS.md)
### _BrtError_
Format of the errors which may be sent by the component.
```ts
interface BrtError {
code: number;
text: string;
}
```
Typescript import:
```javascript
import { BrtError } from '@bruit/component';
```
# 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:
```html
...
```
Then, you may add the `bruit-io` component directly:
```html
...
var bruitCmp = document.querySelector('bruit-io');
bruitCmp.config = {
// whatever your config is
};
```
[_from stencil documentation_](https://github.com/ionic-team/stencil-site/blob/master/src/docs/framework-integration/javascript.md)
## 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 `defineCustomElements()` 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`:
```ts
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 defineCustomElements
bruit.io component includes a function used to load itself in the application window object. That function is called `defineCustomElements()` 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:
```ts
import { enableProdMode } from '@angular/core';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { AppModule } from './app/app.module';
import { environment } from './environments/environment';
import { applyPolyfills, defineCustomElements } from '@bruit/component/loader';
// if you want set bruit config :
// import BruitCoreConfig from '@bruit/component/dist/collection/start';
if (environment.production) {
enableProdMode();
}
platformBrowserDynamic()
.bootstrapModule(AppModule)
.catch(err => console.log(err));
applyPolyfills().then(() => {
defineCustomElements(window)
// if you want set bruit config :
// defineCustomElements(window).then(() => {
// BruitCore({
// logCacheLength: {
// click: 5
// }
// });
// });
})
```
### Using bruit.io in an Angular component
```html
```
```ts
public bruitConfig: BrtConfig = {
apiKey:"xxxxxxxxxxx",
form:[...]
};
public bruitData: Array = [
{
label:"version",
value: environment.version
}
];
constructor(private api : ApiService){}
bruitDataPromise(): Promise>{
return this.api.getUser().then( user =>
[
{
label: "user id",
value: user.id
},
{
label: "user email",
value: user.email
}
]
);
}
handleBruitError(error: BrtError){
...
}
```
[_from stencil documentation_](https://github.com/ionic-team/stencil-site/edit/master/src/docs/framework-integration/angular.md)
## 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 `defineCustomElements()` method in the `index.js` file.
```tsx
import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import registerServiceWorker from './registerServiceWorker';
import { applyPolyfills, defineCustomElements } from '@bruit/component/loader';
// if you want set bruit config :
// import BruitCoreConfig from '@bruit/component/dist/collection/start';
ReactDOM.render(, document.getElementById('root'));
registerServiceWorker();
applyPolyfills().then(() => {
defineCustomElements(window);
// if you want set bruit config :
// defineCustomElements(window).then(() => {
// BruitCore({
// logCacheLength: {
// click: 5
// }
// });
// });
});
```
[_from stencil documentation_](https://github.com/ionic-team/stencil-site/blob/master/src/docs/framework-integration/react.md)
## 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:
```tsx
import Vue from 'vue';
import App from './App.vue';
import { applyPolyfills, defineCustomElements } from '@bruit/component/loader';
Vue.config.productionTip = false;
Vue.config.ignoredElements = [/bruit-\w*/];
applyPolyfills().then(() => {
defineCustomElements(window);
});
new Vue({
render: h => h(App)
}).$mount('#app');
```
[_from stencil documentation_](https://github.com/ionic-team/stencil-site/blob/master/src/docs/framework-integration/vue.md)
# 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](https://github.com/Moventes/bruit.io/issues/20) : component properties typing requires typescript version **2.7+**.
# Having troubles ?
- [Github issues](https://github.com/Moventes/bruit.io/issues)