/ackee-tracker

Transfer data to Ackee.

Primary LanguageJavaScriptMIT LicenseMIT

ackee-tracker

Dependencies

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

Contents

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 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. The update of old records will be canceled when you call this function once again.

Examples:

instance.record()
instance.record({
	siteLocation: window.location.href,
	siteReferrer: document.referrer
})
const stop = instance.record()

// Manually stop updating the visit duration. The returned function should be used in
// single-page applications. Call the function when the user navigates to a new page
// before creating a new record.
stop()

Parameters:

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

Returns:

  • {Function}() Call the returned function to stop updating the visit duration of the created record.

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
}

Related