@edulib-france/yawl
v0.2.0
Published
Simple, powerful JavaScript analytics
Readme
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.
Table of Contents
Installation
Via npm
npm install @edulib-france/yawlFrom the repository
Clone the repository and install the dependencies:
git clone https://github.com/edulib-france/yawl.git
cd yawl
npm installConfiguration
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',
});Reset Visit
The yawl.resetVisit function allows you to reset the current visit and visitor tracking session. This is useful when a user logs out of your application, ensuring that their analytics session is properly terminated and prepare for a new one.
Note: The reset includes a 500ms delay to ensure pending events are sent before the session ends. A new visit is automatically created after the reset.
Example:
await yawl.resetVisit();Development
Build Scripts
The project uses Rollup to generate the bundles (UMD and ES Modules).
Build: Generates the bundles in the dist/ folder.
License
This project is distributed under the MIT license.