Home

Awesome

<div align="center"> <img src="https://s.electerious.com/images/ackee-tracker/icon.png" title="ackee-tracker" alt="ackee-tracker logo" width="128">

ackee-tracker

Donate via PayPal

A script that interacts with the API of Ackee. Should be included on your site to track data.

<br/>

Ackee tracker code

</div>

🚀 Installation

We recommend loading ackee-tracker from your Ackee instance. This ensures that the script is always in sync with your installation. The script is served as tracker.js or as a name of your choice.

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

It's also possible to install ackee-tracker as a module via npm or yarn.

npm install ackee-tracker

yarn add ackee-tracker

🤗 Usage

TypeUsageBest forRecords (Views)Actions (Events)
AutomaticallyVia script tagSimple sites✅⛔️
ManuallyVia script tag and codeAdvanced sites✅✅
ProgrammaticVia moduleModern sites with build tools✅✅

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.

This approach is perfect for static sites. It tracks a visit whenever a user visits the site or navigates to a new page. Websites with client-side routing however should consider to use any of the other approaches as this one would only track the initial page.

<script async src="dist/ackee-tracker.min.js" data-ackee-server="https://ackee.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://ackee.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.

This approach is perfect for sites without a build system. It gives you more control than the automatic solution, but still allows you to use ackee-tracker without a package manager or JS bundler.

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

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

Programmatic

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

This approach is perfect if your site uses client-side routing or changes content without reloading the site. It allows you to call Ackee whenever you need.

Example:

const ackeeTracker = require('ackee-tracker')

ackeeTracker.create('https://ackee.example.com').record('hd11f820-68a1-11e6-8047-79c0c2d9bce0')

import * as ackeeTracker from 'ackee-tracker'

ackeeTracker.create('https://ackee.example.com').record('hd11f820-68a1-11e6-8047-79c0c2d9bce0')

⚙️ API

.detect()

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

This function runs automatically in a browser environment and fails silently when it can't find a suitable element. You usually don't need to call this function.

Example:

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

ackeeTracker.detect()

.create(server, options)

Creates a new ackee-tracker instance.

Be sure to assign your instance to a variable. Tracking a visit or event is only possible with an instance.

Examples:

const instance = ackeeTracker.create('https://ackee.example.com')

const instance = ackeeTracker.create('https://ackee.example.com', {
	detailed: false,
	ignoreLocalhost: true
})

Parameters:

Returns:

.attributes()

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

Examples:

const attributes = ackeeTracker.attributes()

const attributes = ackeeTracker.attributes(true)

Parameters:

Returns:

⚙️ Instance API

Each ackeeTracker instance is an object with functions you can use to track visits and events.

.record(domainId, attributes, callback)

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

Examples:

instance.record('hd11f820-68a1-11e6-8047-79c0c2d9bce0')

instance.record('hd11f820-68a1-11e6-8047-79c0c2d9bce0', {
	siteLocation: window.location.href,
	siteReferrer: document.referrer
})

instance.record('hd11f820-68a1-11e6-8047-79c0c2d9bce0', undefined, (recordId) => {
	console.log(`Created new record with id '${ recordId }'`)
})

const { stop } = instance.record('hd11f820-68a1-11e6-8047-79c0c2d9bce0')

// 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:

Returns:

.updateRecord(recordId)

Updates a record constantly to track the duration of a visit. You usually don't need to call this function, because .record calls this function for you. It's however helpful when you want to continue tracking a record after a page reload or after a record has been stopped.

Updating attributes of an existing record isn't possible.

Examples:

instance.updateRecord('dfa929d3-bfbf-43f2-9234-ed646eb68767')

const { stop } = instance.updateRecord('dfa929d3-bfbf-43f2-9234-ed646eb68767')

// 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:

Returns:

.action(eventId, attributes, callback)

Creates a new action on the server to track an event.

Tipps:

Examples:

instance.action('513a082c-2cd5-4939-b417-72da2fe1761d', {
	key: 'Checkout',
	value: 9.99
})

instance.action('1b6e20cb-7c7d-48ca-8cb6-958a55d7a9e3', {
	key: 'Subscription',
	value: 1
}, (actionId) => {
	console.log(`Created new action with id '${ actionId }'`)
})

Parameters:

.updateAction(actionId, attributes)

Updates an action on the server.

Examples:

instance.updateAction('7fe70f50-cb16-4e27-90ab-d6210296a4b7', {
	key: 'Checkout',
	value: '4.99'
})

instance.updateAction('24776c2b-c5d6-4fac-852a-067d086dc4af', {
	key: 'Subscription',
	value: null
})

Parameters:

🔧 Options

The option-object can include the following properties:

{
	/*
	 * Enable or disable tracking of personal data.
	 * We recommend to ask the user for permission before turning this option on.
	 */
	detailed: false,
	/*
	 * Enable or disable tracking when on localhost.
	 */
	ignoreLocalhost: true,
	/*
	 * Enable or disable the tracking of your own visits.
	 * This is enabled by default, but should be turned off when using a wildcard Access-Control-Allow-Origin header.
	 * Some browsers strictly block third-party cookies. The option won't have an impact when this is the case.
	 */
	ignoreOwnVisits: true
}

Miscellaneous

Donate

I am working hard on continuously developing and maintaining Ackee. Please consider making a donation to keep the project going strong and me motivated.

Links