@oddcamp/analytics

Odd Camp analytics helpers library

A collection of analytics helper functions.

Supported analytics services

• Plausible
• Ahoy

Plausible

Make sure the API object is available at window.plausible. It usually is if the snippet was inserted via <script>.

Plausible

Make sure the API object is available at window.ahoy. If you use it as NPM module you can expose the object like this:

import ahoy from "ahoy.js"

window.ahoy = ahoy

Usage

1. Install

$ yarn add @oddcamp/analytics

1. Enjoy

import { enableAutoEventAnalytics } from "@oddcamp/analytics"

enableAutoEventAnalytics()

HTML

  <a href="/" data-event-analytics='{"name": "Click", "props": {"trigger": "anchor"}}'>
    Link
  </a>

ERB

  <%= link_to 'Link', root_path, data: {event_analytics: {name: 'Click', props: {trigger: 'anchor'}}} %>

JSX

  <a href="/" data-event-analytics={JSON.stringify({name: 'Click', props: {trigger: 'anchor'}})}>
    Link
  </a>

Development

1. Create .env and set variables of analytics services you prefer to test:
   • PLAUSIBLE_DOMAIN=something.site
   • AHOY_SCRIPT_URL=https://unpkg.com/ahoy.js@0.4.0/dist/ahoy.js
2. $ yarn install
3. $ yarn dev
4. localhost:1234

API

enableAutoEventAnalytics

Enable automatic event analytics for element clicks and form submissions.

Defaults:

enableAutoEventAnalytics({
  attributeName = `event-analytics`,
  sourceNode = document,
  services = [`plausible`, `ahoy`],
  debug = false,
})

Returns: function which disables automatic event analytics if executed, e.g.:

const disableAutoEventAnalytics = enableAutoEventAnalytics()
// ...
disableAutoEventAnalytics()

The value of attributeName attribute must be a JSON, e.g.:

{
  "name": "", // name; mandatory
  "props": {}, // custom properties
  "options": {
    "allFieldsAsProps": false, // sets all form fields as props on form submissions
  }
}

Get all form field name and value pairs as props using boolean allFieldsAsProps option or specify field(s) manually by setting data-event-analytics-field attribute, e.g.

  <form data-event-analytics="{...}">
    <input type="search" name="query" data-event-analytics-field>
  </form>

Note: the attribute name may differ if you did set a custom value for attributeName parameter (${attributeName}-field).

analyticizeEvent

Analyticizes an event.

Defaults:

analyticizeEvent({ 
  data, 
  services = [`plausible`, `ahoy`],
  debug = false 
})

Example:

analyticizeEvent({
  data: {
    name: `Event name`,
    props: {
      key: `value`,
    },
  },
})