Skip to content

Latest commit

 

History

History

collection-agent

README.md

SSDN Browser Collection Agent

Introduction

ssdn-collection-agent is a browser library for sending messages to a SSDN instance. By default, it encodes messages in the xAPI format and pushes them via image beacons. It features two data collection strategies out of the box: one for tracking user visits, and one for tracking user interactions with embedded videos.

Usage

The recommended way to use the library is by using the SSDN JavaScript snippet. When the snippet is included in a web page, it takes care of initialising a SSDN instance according to the provided configuration:

<!-- ssdn-collection-agent -->
<script>
  window.ssdn = window.ssdn || {
    configure: function() {
      (window.ssdn.args = window.ssdn.args || []).push(arguments);
    },
  };
  ssdn.configure("server", "<URL TO SSDN SERVER>");
  ssdn.configure("apiKey", "<AGENT API KEY+>");
  ssdn.configure("defaultNamespace", "<DEFAULT EVENT NAMESPACE>"); // Optional
  ssdn.configure("collectors", [
    "video",
    ["heartbeat", { heartbeatInterval: 5000 }],
    // Additional collectors
  ]);
  ssdn.configure("user", {
    id: "<USER ID OR EMAIL>",
    extensions: { homePage: "<URL FOR USER LOGIN (xAPI)>" },
  });
</script>
<script src="https://url/to/agent.js" async></script>
<!-- /ssdn-collection-agent -->

If necessary, it is also possible to postpone agent initialisation:

<script src="https://url/to/agent.js" async></script>
<script>
  $(function() {
    ssdn.configure("server", "<URL TO SSDN SERVER>");
    // ... more ssdn configuration with `ssdn.configure` ...
    ssdn.bootstrap();
  });
</script>

Implementation

ssdn-collection-agent is written in TypeScript and relies on the Node.js tooling ecosystem to test and build its browser component. The following tools are used in the project:

  • Yarn: manages dependencies and project scripts.
  • Parcel: provides a zero-config application bundler.
  • Babel: compiles TypeScript code into standard JavaScript and optimizes the production builds.
  • Jest: runs unit and integration tests.
  • WebdriverIO: runs end-to-end tests.
  • TSLint and Prettier: provide linting rules and formatting automation to enforce conventions across the codebase.

Requirements

In order to build the project, you'll need Node.js (version 10.15 or higher) and Yarn.

To run end-to-end tests in the default configuration, you should have a recent version of Google Chrome installed.

Project layout

The project has been modeled after the SSDN Core application.

ssdn-collection-agent/
├── dist/                 # Output folder that contains the generated build
├── tmp/                  # Temporary files generated by test or build processes, can be safely deleted
├── docs/                 # Additional project documentation
├── integration-test/     # Integration and e2e tests folder
│   ├── specs/            # e2e specs
│   ├── tsconfig.json     # Configuration file for the TypeScript compiler (E2E tests)
│   └── wdio.conf.js      # Configuration file for WebdriverIO, the E2E test runner
├── src/                  # Main source folder
│   ├── collectors/       # Data collectors
│   ├── messages/         # SSDN message types
│   ├── polyfills/        # Browser polyfills
│   ├── agent.ts          # Source code file
│   └── agent.test.ts     # Unit test for the corresponding code file
├── types/                # Custom TypeScript typings
├── .babelrc              # Configuration file for Babel
├── .browserslistrc       # Configuration for Browserslist, reflecting the supported browsers for the agent
├── .prettierrc           # Configuration file for Prettier
├── .env                  # Environment variables
├── .env.integration      # Environment variables for integration tests
├── README.md             # This file
├── jest.config.js        # Configuration file for the test runner
├── tsconfig.json         # Configuration file for the TypeScript compiler
├── tslint.json           # Configuration file for the TypeScript linter (tslint)
├── package.json          # Node.js dependencies
└── yarn.lock             # Yarn lockfile

Development setup

Run the following command to install the project dependencies:

yarn install

After the above command completes successfully, you can start development by running:

yarn start

This will take care of building your TypeScript code automatically whenever a change is detected. It will also open a browser window with an example page that includes the agent.

Testing

As we already mentioned, we use Jest as the default test runner, and WebdriverIO for the integration tests. You can use the following Yarn scripts to run specific types of tests.

Unit tests

yarn test

This will run all the unit tests; that is, all the tests that reside in the src folder. You can also run the following command to watch for changes in the tests and run them immediately:

yarn test:watch

Integration & End-to-End tests

These types of tests reside in their own separate folder and have a separate set of configuration files, as the end-to-end browser testing requirements are significantly different from the browser agent environment. You can run these tests with the following command:

yarn test:integration

To run all tests (both unit and integration), you can run:

yarn test:all

Deployment

Whenever you're ready to to deploy your changes to a live environment, you should run:

yarn build

This will compile the code, check the TypeScript types and run the linter, as well as generate an optimized build suitable for a production environment.

Additional Yarn scripts

You can use the following Yarn scripts to perform various useful tasks:

yarn check-types

Uses the tsc compiler to check for errors in the TypeScript code.

yarn lint

Performs code analysis in search for functional errors and potential improvements using tslint.