npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

ackee-tracker

v5.1.0

Published

Transfer data to Ackee

Downloads

2,635

Readme

ackee-tracker

Donate via PayPal

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

Ackee tracker code

🚀 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

| Type | Usage | Best for | Records (Views) | Actions (Events) | | :------------------------------ | :---------------------- | :---------------------------- | :-------------- | :--------------- | | Automatically | Via script tag | Simple sites | ✅ | ⛔️ | | Manually | Via script tag and code | Advanced sites | ✅ | ✅ | | Programmatic | Via module | Modern 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, opts)

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:

  • server {String} An URL that points to 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 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:

  • domainId {String} Id of the domain.
  • attributes {?Object} Attributes that should be transferred to the server. Will be ackeeTracker.attributes() unless specified otherwise.
  • callback {?Function}({?String}) Function that executes once the record has been created. Receives the id of the new record.

Returns:

  • {Object} Object with a stop function. Call the returned function to stop updating the visit duration of the created record.

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

  • recordId {String} Id of the record.

Returns:

  • {Object} Object with a stop function. Call the returned function to stop updating the visit duration.

.action(eventId, attributes, callback)

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

Tipps:

  • key won't show up in the Ackee UI for every event type, but must be specified nevertheless
  • Use 1 as value to count how many times an event occurred or a price (e.g. 9.99) to see the sum of successful checkouts in a shop
  • Reset an existing value using null when the user canceled an event (e.g. removed an item from the checkout)

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:

  • eventId {String} Id of the event.
  • attributes {Object} Attributes that should be transferred to the server.
    • key {String} Key that will be used to group similar actions in the Ackee UI.
    • value {?Number} Positive float value that is added to all other numerical values of the key.
  • callback {?Function}({?String}) Function that executes once the action has been created. Receives the id of the new action.

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

  • actionId {String} Id of the action.
  • attributes {Object} Attributes that should be transferred to the server.
    • key {String} Key that will be used to group similar actions in the Ackee UI.
    • value {?Number} Positive float value that is added to all other numerical values of the key.

🔧 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