@edulib-france/yawl NPM

NPM Version

Yawl

Yawl is a simple and powerful JavaScript analytics solution, derived from a fork of ahoy.js by Edulib. It allows you to track visits and other custom events on your website.

Yawl

Installation

Via npm

npm install @edulib-france/yawl

From the repository

Clone the repository and install the dependencies:

git clone https://github.com/edulib-france/yawl.git
cd yawl
npm install

Configuration

yawl.configure({ apiKey: 'your_api_key' }) must be called before tracking events. The configuration is asynchronous and returns a Promise. You can also specify the environment using the env property, which defaults to 'prod'.

await yawl.configure({
  apiKey: "your_api_key",
  env: "prod", // optional, defaults to 'prod'
});

Usage

After configuration, you can initialize Yawl and track events on your site. For example, in your HTML file:

<!DOCTYPE html>
<html>
  <head>
    <title>Yawl Analytics</title>
    <script src="dist/yawl.js"></script>
    <script>
      // Initialize Yawl with your API key
      (async function() {
        await yawl.configure({
          apiKey: 'your_api_key',
          env: 'prod' // optional, defaults to 'prod'
        });

        // Example of tracking a custom event
        await yawl.track({
          name: 'event_name',
          ean: 12323938432,
          establishment_account_id: '456',
          properties: {
            key: 'value'
          },
          user_type: 'student',
        });
      })();
    </script>
  </head>
  <body>
    <!-- Your HTML content -->
  </body>
</html>

Events

The yawl.track function is used to track custom events on your website. It sends event data to the analytics backend for processing. This is an asynchronous method that returns a Promise.

Here are the parameters for the track event:

Parameter	Type	Description
`ean`	Integer	The article ID associated with the event.
`establishment_account_id`	String	The establishment account ID.
`name`	String	The name of the event (e.g., "click").
`properties`	Object	Additional properties related to the event.
`user_type`	String	The type of user (e.g., "client", "admin").

Example:

await yawl.track({
  name: "event_name",
  ean: 12323938432,
  establishment_account_id: "456",
  properties: {
    key: "value",
  },
  user_type: "student",
});

Views

The yawl.trackView function is used to track page views on your website. It automatically collects common page information like URL, title, and page path, and allows you to add custom properties. This is an asynchronous method that returns a Promise.

Here are the parameters for the trackView:

Parameter	Type	Description
`ean`	Integer	The article ID associated with the page view.
`establishment_account_id`	String	The establishment account ID.
`properties`	Object	Additional properties related to the page view.
`user_type`	String	The type of user (e.g., "client", "admin").

Example:

// Track a basic page view
await yawl.trackView();

// Track a page view with additional properties
await yawl.trackView({
  ean: 12323938432,
  establishment_account_id: "456",
  properties: {
    key: "value",
  },
  user_type: "student",
});