Hbf-webchat NPM

HBF Webchat Library

About the Project
- Built With
Installation
Getting Started
- Prerequisites
- Run Locally for Development
Contributing [as a Developer]
- Steps
Contributing [as Leader/Code Reviewer]
- Merging Pull Requests
- Making a Release
Upload on CDN for Production

About the Project

The HBF Webchat Library is the library that gets shared between all the Webchat Widgets that are used on Helvia's bots. Bellow we will describe the general Architecture of the project, the requirements and how to run it locally so that you can develop on it.

HBF Webchat Library enhances the OpenSource library of Microsoft's Bot Framework Webchat as CDN.

Branch v0 uses v3.0 of Microsoft's Webchat. Master and Develop branches use v4.0 of Microsoft's Webchat.

Built With

Installation

Guide

Assuming that you have already created your Tenant for the Webchat, in order to create your Webchat Widget you should add the following lines in the <Body> of your HTML page.

<script src="https://cdn.helvia.io/hbf-webchat/lib/latest/webchat.min.js"></script>
<script>
  window.HBFWebchat.init({
    id: "<GENERATED_UUID>", // It is the second part of tenant's handle "bot.id***this.id"
    tokenURL: "<HBF-BOT-URL_TO_REQUEST_FOR_TOKEN>",
    secret: "<SECRET_OF_YOUR_WEBCHAT_CHANNEL_ON_AZURE_APP>", // DEPRICATED, secret and tokenUrl are mutual exclusive. You can use either one or another
    bot: { id: "<BOT_HANDLE>", name: "<BOT_NAME>" },
    greetingActivityMessages: [
      {
        type: "message",
        text: "Hi there, I’m the default bot used for development."
      },
      {
        type: "message",
        text: "How can I help you?"
      }
    ]
    // ...MORE OPTIONS
  });
</script>

Note

Keep in mind that in the above example we used the latest version of the library. We recommend to use a specific version of the HBF Webchat Library that you want, e.g. https://cdn.helvia.io/hbf-webchat/lib/1.0.0/webchat.min.js

Available Options

Check out the available properties in the link: https://github.com/Helvia/hbf-webchat/blob/v<VERSION>/src/default-properties.js, after you replace the <VERSION> with the version of the Library you used. E.g https://github.com/Helvia/hbf-webchat/blob/v1.0.0/src/default-properties.js

If you used 'latest' as the version on CDN link, then you check here the options.

Features

Go to a webpage that has the Webchat Widget with the parameter hws=on in the URL, the page will load with the Widget open, but you will be able to close it again. Add the parameter hws=alwayson in the URL and the webchat will load open, and will hide the x icon in the header.
Go to a webpage that has the Webchat Widget with the parameter hcn=<NODE_ID> in the URL, when the webchat will open it will start on the specified Conversation Node
Go to a webpage that has the Webchat Widget with the parameter hsh=<UNIQUE_SUBSCRIBER_ID> in the URL, when the webchat will open it will continue the conversation for the subscriber with handle UNIQUE_SUBSCRIBER_ID
Inside a WebPage that features a Webchat, the Developers of the WebPage can add one or more buttons with the class btn-hcn and data data-hcn="<NODE_ID>" and then, when those buttons get's clicked the webchat will begin from the specified Conversation Node

Getting Started

Prerequisites

The only requirement is that you must have installed Node v10 (tested with v10.15.3) and NPM v6.11.0 or above (tested with v6.11.2).

Run Locally for Development

At first, make sure you have the credentials of the Azure Bot Registration App that belong to an existing Tenant in the Database. The credentials needed are: - The secret of the Webchat Channel - The Bot ID (bot handle) - The Bot Name (bot name)
Create a local.json file as a copy of the default.json inside config/ and pass the credentials there.
{ "secret": , "bot": { "id": <BOT_ID>, "name": <BOT_NAME> }, }
You can pass more configurations if you want, but the above are the bare minimum to make the webchat working on Development Mode.
Run npm install and then npm start. That way you will start the webpack-dev-server and build the /src directory of the project on-the-fly by running the development configurations of the webpack (webpack.common.js+webpack.development.js).
Now, you are able to make changes in the code inside /src and see them live.

Contributing as a Developer

Before we move into the steps of the contributions, let's define some useful notes.

HBF Webchat Library uses a workflow similar to Git Flow. If you know Git Flow, you mostly know how to contribute, if not please spend a couple of minutes on studying it.
- NEVER commit directly to develop or master branches. ALWAYS create a new branch.
- For FIX, create a new fix branch from master with name fix/ and make the fix. Then make the PR.
- For FEATURE, create a new feature branch from develop with name feature/ and build it. Then make the PR.
- The code that exists in master MUST exist in develop, too.
- Follow strictly the rule: one feature per PR. Do not develop multiple features on the same feature branch.
HBF Webchat Library keeps a CHANGELOG generated automatically.
HBF Webchat Library uses Semantic Versioning 2.0.0. Bumped almost automatically.
HBF Webchat Library uses an exact version of Prettier. Format the code before the PR.

Steps

Clone the repository git clone git@github.com:Helvia/hbf-webchat.git
Create your feature/fix branch following the rules we discussed in the notes above git checkout -b <feature/fix-branch-name>
Develop and Format your code with prettier.
Commit your changes git commit -m 'Add some AmazingFeature/Fix'
Push your branch to remote git push origin <feature/fix-branch-name>
Submit a pull request back to the base branch 🎉 😃

Contributing as Leader/Code Reviewer

HBF Webchat Library uses the module Standard Version for the releases.

Merging Pull Requests

PRs are merged with --squash and a commit message. Therefore, we don't care about the commits inside the feature or fix branches.
PR merge commits must follow the Conventional Commits Specification.
Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope, and a subject:
```
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
```
The header is mandatory, and the scope of the header is optional. The type must be one of the following:
- feat: A commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in semantic versioning).
- fix: A commit of the type fix patches a bug in your codebase (this correlates with PATCH in semantic versioning)
- chore: Any small semantic change (version bump)
- build: Changes that affect the build system or external dependencies
- ci: Changes to our CI configuration files and scripts
- docs: Documentation only changes
- refactor: A code change that neither fixes a bug nor adds a feature
- style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
- test: Adding missing tests or correcting existing tests
  Any line of the commit message cannot be longer 100 characters! This allows the message to be easier to read on GitHub as well as in various git tools.
  Append a ! after the type/scope, to introduce a breaking API change (correlating with MAJOR in semantic versioning). A BREAKING CHANGE can be part of commits of any type.
  The footer should contain a closing reference to an issue if any.
  Samples: (even more samples)
```
docs(changelog): update changelog to beta.5
```
```
fix(release): need to depend on latest rxjs and zone.js

The version in our package.json gets copied to the one we publish, and users need the latest of these.
```
CHANGELOG is generated automatically based on the Conventional Commits.
Versioning is generated automatically based on the Conventional Commits.

Making a Release

Normal

To prepare develop for release you just need to execute this command on the develop branch:

npm run release

This command will automatically:

Retrieve the current version of your repository by looking at packagge.json, falling back to the last git tag.
bump the version in package.json based on your commits (it uses the Conventional Commits standard).
Generates a changelog based on your commits (uses conventional-changelog under the hood).
Creates a new commit including your package.json and updated CHANGELOG.md.
Creates a new tag with the new version number.

After that, you just need to merge develop into master and push all the changes.

HotFix

Hotfixes are merged directly to master branch, so you just need to execute this command on the master branch:

npm run release

After that, you just need to rebase the develop with the master and push all the changes.

BETA

To prepare develop for a BETA release you just need to execute this command on the develop branch:

npm run release-beta

After that, you just need to merge develop into master and push all the changes.

Upload on CDN for Production

NOTE: This workflow will soon be replaced by CI/CD.

Let's say that you have contributed, and your Pull Request (PR) has been merged (for Contribution rules check here and here).

Please make sure you have installed and configured awscli on your bash environment. If you don't know how, follow the official installation guide and the configuration guide. This has to be done once.

Checkout to master branch and pull the latest changes. git checkout master && git pull
Upload the code to AWS S3 for CDN npm run up-on-cdn. The Webpack, alongside the Babel will build the src code and will create a /dist folder. Then this folder will be synced with s3 bucket through awscli and then the /dist will be removed. Follow the logs to learn the link to the new version of the HBF Webchat Library.

chatbot

@ungap/url-search-params config core-js css-vars-ponyfill deepmerge node-sass regenerator-runtime uuid whatwg-fetch

1.10.0

3 years ago

hbf-webchat v1.10.0