Visitor API

Usage no npm install needed!

<script type="module">
  import adobeMcidVisitorJsClient from 'https://cdn.skypack.dev/@adobe-mcid/visitor-js-client';


Visitor JS Client

This is the new home for VisitorAPI. We have updated the build system and everything around it to make the DEV environment as dev friendly as possible.


Read public docs

Internal WIKI

For developers:

To get started, clone the repo to your local machine, then install all the dependencies:

Clone the repo

git clone git@git.corp.adobe.com:mc-visitor/visitor-js-client.git

Install all the dependencies from NPM

npm install

Build & Dev explanation

We use simple NPM scripts to run our build processes.

The dev environment will help prevent syntax errors, enforce a coding standard and make sure unit tests are always apssing.

To do that, we lint the code and run the unit tests every time you commit.

How to build the project

Building the code will output 3 files into the dist/js directory:

  • bundle.js: Since Visitor is using Modules, we use browserify to transform the file to a browser friendly object. This file is the bundle of Visitor and all the dependency that it needs, unminified.

  • visitorapi.min.js: Prod-Ready, minified and obfuscated version of Visitor.

  • visitorapi_debug.min.js: A debug version of Visitor. This is a work in progress, but the goal is to have a debug version of Visitor that outputs to the console, turns on metrics by default, checks the configuration and make sure it is done correctly and more...

To build Visitor: npm run build

Testing pyramid

We have 3 layers of testing in this build environment:

Unit Tests

We have a suite of unit tests that is run every time you commit. This is a work in progress, working towards the optimal coverage that can confirm a happy path. We use Karma-browserify as test runner, write our tests in Jasmine 2.5, and use browserify-shim to make sure we can run Visitor in the console in NodeJS, since Visitor depends on window and document a good amount.

To run the Unit Tests: npm run test

Run Unit Tests cross platform

Since Visitor supports ALL browsers, we have built a simple Node project that will take our unit tests, and run them in Sauce Labs against multiple platforms and browsers. Read more about test-cross-platform

In order to change or view the test-cross-platform configurations, open package.json and look for the "testCrossPlatform" property.

To run the Unit Tests cross platform: npm run test:crossplatform

Integration Tests

The last layer of testing are the integration tests. The goal of those tests is to place Visitor, AppMeasurement, AT.js and hopefully more soon on an HTML page, instantiate them, and make sure they play together nicely.

We use a combination of Jasmine, selenium-webdriver and BrowserMob proxy to run those tests.

About browsermob-proxy and selenium standalone.

  • browsermob-proxy is an node binding to communicate with the actual Browsermob Proxy REST API and collect HAR data.

  • selenium-standalone can install the Selenium Standalone Server JAR file which is a requirement for browser mob, and can start the server.

To use all this cool stuff:

Terminal Tab 1: npm run startSelenium Terminal Tab 2: npm run startProxy’ Terminal Tab 3: npm run test:integration`

More to come, but this is the base framework.

Run HTML coverage report

Use npm run test:htmlCoverageReporter and Istanbul will generate a very helpful HTML page that shows the sections we need to test, complexity and more... The page will go under test/unit-tests/coverage.

Sample app

We have implemented a sample app that implements Visitor and showcases it's features and best practices. The app resides in the /dist/ folder. Features:

  • Visitor's interface.
  • Best practices
  • Pitfalls and known issues
  • Debugging

To run the Sample App: npm run start

Then open any browser and go to localhost:8080.

Github pages

We are publishing our sample on Github pages.

Visit the page here

To publish a change to the Sample App: npm run deployToGitPages

Git process

In order to contribute to this repo, please follow this process:

  1. Create a branch with a name that looks like this: feature/TICKET_NUMBER.
  2. Once your code is committed, make a Pull Request against the DEV branch for that release.
  3. Once your PR is approved, rebase your feature branch on top of the dev branch, then merge it into dev. Don't squash merge, keep all the commits as they were.

More about PRs (IMPORTANT):

The way we create PRs and commits affects the way we think about problems and how we can break them down into simpler problems which allows faster and better implementation. Breaking down user stories into sub tasks that relates to PRs is a great plus as well.

When we put up a pull request for review, we should have the reviewer in mind. Small PRs with well named commits with atomic changes are very important so that the reviewer can follow and understand your implementation. You don't want the reviewer to open "Files Changed", instead he should be able to select each commit separately and understand the intention of this commit. You want your PR to be reviewed for language errors as well as logic issues, detect repetition, suggestions for abstractions and more. The only way the reviewer can do is when the PRs and commits are small and meaningful.

Taking PRs seriously will enforce more readable code as well, which is another win.

Example of a good commit message:

[MCID-666] This is a brief description of my commit

This is more details about the commit, if necessary. We can add TODOs, depenencies, WIP items...
  • Provide a brief description on the first line (60 characters max). Include the issue id as the first part of the commit message (optionally)
  • Insert a single blank line after the first line
  • Provide a detailed description of the change in the following lines, breaking paragraphs where needed
  • Include external references to help the reviewer

Things to avoid

  • No mixing functional changes with refactoring: use separate commits or, even better, separate pull requests
  • No mixing whitespace changes with functional code changes (separate the changes in two separate commits)
  • No mixing two functional changes in the same commit. If you have to use "and", break it in two separate commits
  • No All-in-one huge commits. Separate your commits in atomic pieces of functional changes.