adnantium/ackee-tracker

Transfer data to Ackee.

ackee-tracker

A script that interacts with the REST API of Ackee. Should be used to feed your server with data from your visitors.

Contents

• Requirements
• Installation
• Usage
• API
• Instance API
• Options

Requirements

ackee-tracker requires a running Ackee server.

Installation

We recommend installing ackee-tracker using npm or yarn.

npm install ackee-tracker

yarn add ackee-tracker

It's also possible to load ackee-tracker from your Ackee server. The script is served as tracker.js.

<script src="https://example.com/tracker.js"></script>

Usage

Automatically

The easiest way to send data to your Ackee server is by including the script along with the required attributes. Ackee will now track each page visit automatically.

<script async src="dist/ackee-tracker.min.js" data-ackee-server="https://example.com" data-ackee-domain-id="hd11f820-68a1-11e6-8047-79c0c2d9bce0"></script>

It's also possible to customize Ackee using the data-ackee-opts attribute.

<script async src="dist/ackee-tracker.min.js" data-ackee-server="https://example.com" data-ackee-domain-id="hd11f820-68a1-11e6-8047-79c0c2d9bce0" data-ackee-opts='{ "ignoreLocalhost": true }'></script>

Manually

Include the JS-file at the end of your body and start tracking page visits by calling create manually.

<script src="dist/ackee-tracker.min.js"></script>

<script>
	ackeeTracker.create({
		server: 'https://example.com',
		domainId: 'hd11f820-68a1-11e6-8047-79c0c2d9bce0'
	}).record()
</script>

Programmatic

Use ackee-tracker as a module and start tracking page visits by calling create.

Example:

const ackeeTracker = require('ackee-tracker')

import * as ackeeTracker from 'ackee-tracker'

ackeeTracker.create({
	server: 'https://example.com',
	domainId: 'hd11f820-68a1-11e6-8047-79c0c2d9bce0'
}).record()

API

.detect()

Looks for an element with Ackee attributes, creates an instance and starts tracking.

The function fails silently when it can't find a suitable element.

Example:

<div hidden data-ackee-server="https://example.com" data-ackee-domain-id="hd11f820-68a1-11e6-8047-79c0c2d9bce0"></div>

ackeeTracker.detect()

.create(server, opts)

Creates a new ackee-tracker instance.

Be sure to assign your instance to a variable. Tracking a visit by creating a new record is only possible with an instance.

Examples:

const instance = ackeeTracker.create({
	server: 'https://example.com',
	domainId: 'hd11f820-68a1-11e6-8047-79c0c2d9bce0'
})

const instance = ackeeTracker.create({
	server: 'https://example.com',
	domainId: 'hd11f820-68a1-11e6-8047-79c0c2d9bce0'
}, {
	ignoreLocalhost: true,
	detailed: false
})

Parameters:

• server {Object} An object that contains details about your ackee-server installation. The server property must not end with a slash.
• opts {?Object} An object of options.

Returns:

• {Object} The created instance.

.attributes()

Gathers and returns all platform-, screen- and user-related information.

Examples:

const attributes = ackeeTracker.attributes()

const attributes = ackeeTracker.attributes(true)

Parameters:

• detailed {Boolean} Include personal data.

Returns:

• {Object} User-related information.

Instance API

Each ackeeTracker instance is an object with functions you can use to track your visitor.

.record(attributes)

Creates a new record on the server and updates the record constantly to track the duration of the visit.

Examples:

instance.record()

instance.record(ackeeTracker.attributes())

Parameters:

• attributes {?Object} Attributes that should be transferred to the server. Will be ackeeTracker.attributes() unless specified otherwise.

Options

The option-object can include the following properties:

{
	/*
	 * Enable or disable tracking when on localhost.
	 */
	ignoreLocalhost: true,
	/*
	 * Enable or disable tracking of personal data.
	 * We recommend to ask the user for permission before turning this option on.
	 */
	detailed: false
}