@ada-support/embed2

Embed 2 helps clients to setup Ada Web Chat in their web application. These docs are for internal-use only; for client-facing docs check out our [docs repo](https://adasupport.github.io/documentation/#embed2).

Usage no npm install needed!

<script type="module">
  import adaSupportEmbed2 from 'https://cdn.skypack.dev/@ada-support/embed2';
</script>

README

Embed 2

Embed 2 helps clients to setup Ada Web Chat in their web application. These docs are for internal-use only; for client-facing docs check out our docs repo.

Setup

These instructions will get Embed 2 up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

1. Initialize

If you are using Embed 2 for the first time, you will need to run:

make init

This will handle most of the setup configuration required for Embed 2, including:

  • Installing nginx, and npm dependencies
  • Configuring the hosts file
  • Starting the NGINX server

In most cases you will just need to run this once, ever. However, you may need to start your NGINX server again from time to time (for example if you have restarted your computer). To re-start NGINX simply run:

make startnginx

2. Start local server

yarn start

🎉 Head over to http://localhost:9000/. You should now be good to go! 🎉

If you are new to Embed 2, the next step will be to familiarize yourself with its architecture. You can find README.mds in each of the major directories that will explain how it works.

You can also test different configuration options in example/index.html.

Finally, it is highly recommend that you install the following plugins (or equivalent) into your text editor / IDE:

Tooling

Linting and Type Checking

You can check for ESLint violations and type errors by running:

yarn lint

This will also run automatically during CI.

Sentry

If you want to run Sentry locally, you will need to set the value for the Sentry DSN in your .env file. Create and open your .env file:

cp .env.example .env
vim .env

Find the Sentry DSN for the Embed 2 project at https://docs.sentry.io/error-reporting/configuration/?platform=browser and selecting "Embed" from the dropdown menu above the code snippet. Copy this value (it should be a string that looks like a URL) to the .env file.

Checking Bundle Size

Embed 2 is the entry to Ada's web chat, and is downloaded more than any other Ada script. As such, maintaining a small bundle size is extremely important. We do this by leveraging the browser cache, and using lightweight modules. Additionally, separate modern and legacy bundles are generated, so the majority of users who use new browser versions do not need to fetch superfluous polyfills.

Bundle size should be checked periodically. You can check the bundle size by running:

yarn bundle-report:modern

and

yarn bundle-report:legacy

You will notice that many tabs are opened when running this command. Because Embed 2 is split between many sub-applications (representing framed components), a bundle analyzer is run for each application. The total bundle size is equal to sum of bundle sizes, plus external dependencies.

Testing

Unit testing

Unit testing is done with Karma and Jasmine. Tests can be run on a local Chrome browser with:

yarn test

End-to-end testing

TestCafe

TestCafe can run E2E tests on real browsers via LambdaTest. These tests will run automatically during the CI pipeline, but can also be run locally.

To run locally, you will first need to add LT_USERNAME and LT_ACCESS_KEY to your .env file. You can find your username and access key in the LambdaTest dashboard. If you have not used LambdaTest before, follow this setup guide here.

Once you have added valid keys, you can now run TestCafe with:

yarn ci-testcafe

Note that this is the same command that runs during CI, and will make requests against the production API. If you would like to run against your local API, you can run:

yarn tc

Cypress

Cypress E2E tests can be run using:

yarn ci-cypress

Deployment

Beta

Deployment of the beta script is handled automatically by CircleCI when merging a branch into master. Once merged, two different scripts will be added to the Ada CDN:

# Verisoned

https://static.ada.support/embed-beta/legacy/entry/<FIRST 7 CHAR OF COMMIT HASH>/embed2.beta.js

And:

# Verisonless

https://static.ada.support/embed2.beta.js

Before deploying to production, you should manually smoke test to make sure the beta script is working here.

Production

Once a beta script has been created, a production deployment will be "held" until approved by an Embed 2 admin. To approve the deploy, open the CircleCI job in question, and click on "Approve Job". You can read more about manual approval here.

Deploying production will create the following scripts:

# Verisoned

https://static.ada.support/embed/legacy/entry/<FIRST 7 CHAR OF COMMIT HASH>/embed2.js

And:

# Verisonless

https://static.ada.support/embed2.js

If you require access to the Embed Procuction Deploys team (needed for production deployment), please reach out to an Engineering admin.

Versioning

We use SemVer for versioning. For the versions available, see the releases on this repository.

Architecture

Frontend Architecture@2x(1)