Bnbot.ai-widgets NPM

bnbot-widgets

Production usage
Widgets theme customisation
Development usage

Production usage

Native usage

To use widgets you need to include widgets.bundle.js script from @agiliumlabs/bnbot-widgets/bundle at the end of body.

Typescript usage

You can import widgets classes from module directly

import { StatisticsWidgetComponent } from '@agiliumlabs/bnbot-widgets';
import { FeedbackWidgetComponent } from '@agiliumlabs/bnbot-widgets';
import { TrainingWidgetComponent } from '@agiliumlabs/bnbot-widgets';

NOTE: Typescript widget classes has no styles. You need to import them to your project manually

@import '~@agiliumlabs/bnbot-widgets/styles/index';

Typings

Module has typescript typings that can be imported in any typescript project

import { RefreshTokens, Statistics, StatisticsOptions } from '@agiliumlabs/bnbot-widgets';
import { Feedback, FeedbackOptions } from '@agiliumlabs/bnbot-widgets';
import { TrainingOptions, UrlType } from '@agiliumlabs/bnbot-widgets';

See all available exported typings in @agiliumlabs/bnbot-widgets/index.d.ts

Mocks

Module has mock instances that can be imported in any project

import { refreshTokensMock, statisticsMock, statisticsOptionsMock, StatisticsWidgetClassMock } from '@agiliumlabs/bnbot-widgets';
import { feedbackMock, feedbackOptionsMock, FeedbackWidgetClassMock } from '@agiliumlabs/bnbot-widgets';
import { trainingOptionsMock, TrainingWidgetClassMock } from '@agiliumlabs/bnbot-widgets';

See all available exported mocks in @agiliumlabs/bnbot-widgets/index.d.ts

Widget params usage

You have three ways to set widget params

through data-attributes
through javascript params
combined by using both data-attributes and javascript params (javascript params has higher priority and overrides params from data-attributes)

<body>
<h1>Statistics widget container bellow</h1>

<div class="al-statistics-widget"
     data-token="xxx"
     data-user-id="alex.test@agiliumlabs.com"
     data-host-id="host-id"
     data-apartment-id="apartment-id"
     data-start-time="2018-11-01T00:00:00.000Z"
     data-end-time="2018-12-01T00:00:00.000Z"
     data-url-type="staging"
     data-link-text="Train bot"></div>

<h1>Feedback widget container bellow</h1>

<div class="al-feedback-widget"
     data-firebase-token="xxx"
     data-device-id="qqq-zzz"
     data-dialog-id="yyy"></div>

<h1>Training widget</h1>

<div class="al-training-widget"
     data-token="xxx"
     data-host-id="yyy"
     data-listing-id="zzz"></div>

    <script src="/widgets.bundle.js"></script>
    <script>
        let statistics = Agiliumlabs.StatisticsWidget.create({
            apartmentId: 'apartment-id',
            endTime: '2018-12-01T00:00:00.000Z',
            hostId: 'host-id',
            linkText: 'Train me',
            selector: '.al-statistics-widget',
            startTime: '2018-11-01T00:00:00.000Z',
            token: 'xxx',
            urlType: 'production',
            userId: 'alex.test@agiliumlabs.com'
        });

        let feedback = FeedbackWidgetComponent.create({
                deviceId: 'yyy',
                dialogId: 'yyy',
                firebaseToken: 'xxx',
                selector: '.al-feedback-widget'
            });
        let training = Agiliumlabs.TrainingWidget.create({
                hostId: 'xxx',
                listingId: 'yyy',
                selector: '.al-training-widget',
                token: 'zzz'
            });
    </script>
</body>

Statistics widget params

data-token - current session token
data-user-id - current user id to match statistics for
data-host-id - optional current host id to match statistics for (return for all hosts if empty)
data-apartment-id - optional current apartment id to match statistics for (return for all apartments if empty)
data-url-type - optional url type for train link (default - relative, available - staging | production)
data-link-text - optional text for train link (default - Train/test bot)
data-start-time - optional start time range to match statistics for (default - 3 month ago)
data-end-time - optional end time range to match statistics for (default - now) NOTE: if you set time range manually - you need to update them on each widget reload. Otherwise you can lost newest (created after your initial time range) statistics info. Default values are dynamical and handle this case

You can use statistics widget with following optional params combinations

just with user-id
with user-id and host-id
with user-id and host-id and apartment-id

Feedback widget params

data-firebase-token - current token for firebase
data-user-id - current user id to match statistics for
data-dialog-id - current dialog id to leave feedback for

Training widget params

data-token - current authorisation token
data-host-id - current host id training for
data-listing-id - current listing id to training for
data-link-text - optional text to replace default train bot link text
data-url-type - optional allowed values are production/staging/relative, default value is relative

Statistics widget dynamic methods

Statistics and feedback widgets are bound together if located on same page. When user add new feedback - statistics will be automatically reload. Technically all statistics widget instances saved in window object and feedback widget call reload method for all saved statistics instances

let statistics = Bnbot.StatisticsWidget.create({ ...statisticsOptions });

Then all available dynamic methods will be available in variable. Available methods are

reload - will recreate new statistics widget instance with custom options
update - will update current statistics widget instance with new options

Feedback UAT tests usage

You can wait figure out current feedback widget state by additional css class on DOM element widget container

is-widget-loading-in-progress - widget is loading for now (some async actions is running in background)
is-widget-loading-complete - widget is fully loaded for now (all async actions is complete)

Widgets theme customisation

All widgets will be added to your page html tag container by tag selector. You need to customise element container by yourself with desired css rules. Widgets wrapper container is fluent and adjust to size of your container. All css rules are defined with single class selector without important flag and can be simply redefined. You can see common class names for widgets theme customisation in bellow sections

Feedback widget customisation sample

.al-feedback-widget { // your widget container class name
    .al-theme {
        &-error { // styles for error block
            background-color: green; // error container background color
            color: red; // error text message color

            &-close { // styles for error close button
                stroke: red; // close icon color
            }
        }

        &-feedback-button { // styles for widget buttons
            border-color: green; // button border color

            &-icon {
                fill: green; // buttons color
            }

            &-icon.al-feedback { // styles for feedback buttons
                width: 100px;
                height: 100px;
            }
        }

        &-submit-button {
            &-icon.al-submit { // styles for negative feedback submit button
                width: 200px;
                height: 200px;
            }
        }

        &-tooltip {
            border-color: red; // color for tooltip border
            color: green; // color for tooltip text
            
            &:before {
                border-color: red transparent transparent; // color for tooltip arrow
            }
        }

        &-textarea { // styles for negative feedback text comment block
            color: green;
            font-size: 50px;
        }
    }
}

Statistics widget customisation sample

.al-statistics-widget { // your widget container class name
    $statisticIconColor: purple; // statistics icons (comments/positive/negative) color
    $statisticIconOpacity: 1; // statistics icons (comments/positive/negative) opacity

    .al-theme {
        &-error { // styles for error block
            background-color: #2b542c; // error container background color
            color: #8a6d3b; // error text message color

            &-close {
                stroke: #8a6d3b; // error close icon color
            }
        }

        &-header { // styles for header block
            height: 40px; // header block height
            background-color: grey; // header block background color
            color: red; // header title text color
            
            &-text {
                color: green; // text color
                font-size: 20px; // text font size
            }
        }

        &-text { // all widget texts styles
            color: green; // text color
            font-size: 20px; // text font size
        }

        &-icon { // styles for statistics icons (comments/positive/negative)
            transform: scale(1.5);

            &-comments {
                fill: $statisticIconColor; // icon color
                opacity: $statisticIconOpacity; // icon opacity (default 0.2)
            }

            &-positive,
            &-negative {
                stroke: $statisticIconColor; // icon color
                opacity: $statisticIconOpacity; // icon opacity (default 0.2)
            }
        }

        &-link { // train button styles
            color: yellow; // button text color
        }
    }
}

Training widget customisation sample

.al-training-widget { // your widget container class name
    .al-theme-text {
        color: white; // color for train description text
    }
    .al-theme-link {
        background-color: #34AFEB; // background link color
        color: white; // color for train bot link
    }
}

Development usage

Launch dev server

npm start

Launch unit tests

npm test
npm run tw
npm test some-file.service
npm run tw some-file.component

Check for code style

npm run cs
npm run cs:fix

Check for code documentation coverage

npm run doc:create
npm run doc:check
npm run doc:serve

Build all widgets for native usage

npm run build-all:prod

Build just statistics widget for native usage

npm run build-statistics:prod

Build just feedback widget for native usage

npm run build-feedback:prod

When build is complete you will see main.bundle.js and main.bundle.js.gz in dist folder. To use widget you need to include following code to your site