Atlas Tracking SDK for Website (JavaScript)
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci
.github/ISSUE_TEMPLATE
dist
docs
plugins/QuickSurvey
src
test
.babelrc
.esdoc.json
.eslintrc.js
.gitignore
CHANGELOG.md
Dockerfile
LICENSE.md
README-JP.md
README.md
gulpfile.js
package-lock.json
package.json
rollup.config.js
wdio.conf.js

README.md

Atlas Tracking JS (ATJ)

Circle CI

Atlas tracking library for general web site

  • ATJ is a tracking SDK for Atlas
  • ATJ transmits beacons for general purpose of web analytics
  • ATJ utilizes web-browser's modern features such as sendBeacon, requestAnimationFrame and Navigation Timing
  • Some features uses Event Delegation mechanism
  • A rich variety of auto tracking options available

Documents

  • README in Japanese is available. (日本語の説明 はこちら)
  • Configuration Guide describes all customizable features managed through c2p.js.
  • Some utility functions are available within ATJ core. You will find useful methods from a List of Methods
  • FAQ is here but is still under enhancement.
  • ATJ is published under MIT License
  • Special thanks to all contributors in this project.
  • As of today, we won't merge pull-requests from outside of Nikkei due to operational policy. Please create an issue on GitHub if you find any problems.

Build ATJ

Prerequisites

You may need one of the following environment:

  1. Node 10
  2. Docker

Create a build environment on Docker

docker build -t atj ./
docker run --name ATJ -e SDK_API_KEY=your_sdk_api_key -e DEFAULT_ENDPOINT=your.atlas.endpoint -e SDK_NAMESPACE=atlasTracking -i -t -v ${PWD##}:/var/atj atj

Environment Variables

Variable Purpose Default Example
SDK_API_KEY For the authentication at Atlas Endpoint which is a destination to put data to test_api_key abc123xyz789
DEFAULT_ENDPOINT A default endpoint. If you don't specify the endpoint in config variables in c2p.js, ATJ fall backs to the endpoint to this value atlas.local atlas-endpoint.your.domain
SDK_NAMESPACE A namespace which will contains all methods and variables for ATJ, so ATJ consumes just one global namespace. atlasTracking atlasTracking

Initialization

npm install

Test

  • You can lint the code by npm run eslint
  • For the unit test, run npm run test
  • The integration test can be done by npm run integration-test

Build

  • For the standalone ATJ, npm run build:dist (In general, this will fit with most use cases)
  • For generating NPM module, npm run build:npm

Implementation Guide

Requirements

  • One variable in global namespace is required to store ATJ related variables and methods. You can specify the name for this when you build ATJ.
  • ATJ uses one Cookie to identify unique browser. A Cookie name is defined in c2p.js but the default is atlasId
  • ATJ dispatch a custom event named atlasVisibilityStatus to detect visibility status of each elements for Scroll Depth, Read Through and Viewable Impression. Dispatch frequency depends on the combination of requestAnimationFrame and throttling.
  • ATJ supports many browsers as possible without polyfill, but it doesn't work with old Internet Explorer older than IE9

Basic Installation

  1. Build your ATJ by following Readme and then you will have atj.min.js in ./dist directory.
  2. Create a config file named c2p.js based on a sample file in ./dist directory. Read Config Guide carefully to customize ATJ.
  3. Load both files atj.min.js and c2p.js within <body>...</body> on each page in your web site.
    • You can call these files by embedding script tags like <script src='{path/to/file}'></script> directly.
    • Also, you can deploy ATJ files through Tag Management tools such as Adobe Dynamic Tag Management, Google Tag Manager and other tag management tools.
  4. Check your web site to confirm that there is no script errors and ATJ is sending beacons.

Inside c2p.js

  • c2p.js fires methods as below step:
    1. Configure ATJ core by calling config()
    2. Initialize the page data by calling initPage()
    3. Then, send a beacon for tracking pageview by trackPage()
  • Also, c2p.js is able to have some custom codes to retrieve and/or prepare data.
  • If your web site is SPA (Single Page Application), you can call initPage() and trackPage() each times when screen has been changed. (no need to re-initialize ATJ itself)

Debugging

Standard Check

The debug method is not special and is similar to other web analytics tool. If you see beacons without script error, ATJ may be working properly.

  1. Open the web browser's "developer console" or "developer tools"
  2. Switch the tab to "Console" and search any script errors related to ATJ. If there is nothing, it's OK.
  3. Move to "Resources" or "Network" tab, and filter the result by entering a keyword as ATJ-. If you see records having your endpoint location, ATJ is sending beacons.

ATJ Built-In Debugging Feature

You can recognize values transmitted to the endpoint by ATJ, and can identify the timing that data has been sent.

  1. Open the web browser's "developer console" or "developer tools"
  2. Go to the "Console" tab, and then execute atlasTracking.debug('enable');
  3. Reload the page, and you will see console logs containing a massive map object.
  4. Click the toggle icon near the log, you can check each values which ATJ is sending to the endpoint.
  • The debug feature uses a session Cookie. If you want to disable this, execute atlasTracking.debug('disable');.
  • You can get the current status of debug mode by running atlasTracking.debug('status'); or checking the value of atlasOutputLog Cookie.

Testing ATJ on your production web site with Adobe DTM

This is not ATJ's feature but Adobe DTM's.

  1. At the first, ATJ must be deployed through Adobe DTM.
  2. Run localStorage.setItem('sdsat_stagingLibrary',true) in browser's console. When the browser has this flag, DTM will load the staging tags.
  3. Reload the page and you can test the tags saved as "Staging" in DTM, only on your browser.
  4. Also, _satellite.setDebug(true) will helps you to find every events occurring on the page.

Opt-out for Privacy

ATJ has a built-in method to add "opt-out from tracking" feature in your service. This is strongly recommended at any cases from the privacy perspective. It's necessary to consider the opt-out feature if your service is used from countries which is applied GDPR.

  1. Create or modify your opt-out page or modal to add an "opt-out from tracking" button.
  2. Write a few code to call atlasTracking.optout('enable') when user clicks the opt-out button.
  • Opt-outed user can opt-in by atlasTracking.optout('disable');
  • To protect user's privacy perfectly within ATJ, you should place the opt-out feature before sending the first beacon, thus initPage() and trackPage() must be triggered once user has accepted tracking.