Tracking events

Pulse allows you to track specific events on your website, such as button clicks, form submissions, or any other user interaction. Events help you measure how many visitors performed a particular action and calculate conversion rates.

Overview of Events

Events measure:

• how many visitors performed a specific action on your site (or a specific page)
• the conversion rate for that action

Important points:

• Events count toward your billable monthly page views.
• No personally identifiable information (PII) should be sent in metadata.

Limits

There are limits to the structure of events you can send:

• You can send up to 20 key-value metadata pairs
• Metadata keys can be up to 255 characters long
• Metadata values can be up to 255 characters long

Implementation Methods

1. Using data- attributes

The simplest way to add event tracking is to use data attributes in your HTML. This method is ideal for tracking clicks on elements.

<button data-hakanai-event="Signup" 
        data-hakanai-meta-source="Homepage" 
        data-hakanai-meta-plan="Premium">
    Sign up
</button>

• The data-hakanai-event attribute defines the event name.
• The data-hakanai-meta-* attributes allow you to add metadata to the event.

2. Using JavaScript

For more precise control or to track events that are not clicks, you can directly use the JavaScript API.

// Track a Basic event
window.Hakanai.trackEvent('Signup');


// Track a simple event with metadata
window.Hakanai.trackEvent('Signup', {
    source: "Homepage",
    plan: "Premium"
});

Usage Examples

Example 1: Tracking a button click

<button data-hakanai-event="Download" 
        data-hakanai-meta-file="guide.pdf" 
        data-hakanai-meta-category="Resources">
    Download guide
</button>

Example 2: Tracking a form submission

<form id="contact-form" method="post">
    <input type="text" name="name" required>
    <textarea name="message" required></textarea>
    <button type="submit">Send</button>
</form>

<script>
    document.addEventListener('DOMContentLoaded', function() {
        let form = document.getElementById('contact-form');
        let isSubmitting = false;
        
        form.addEventListener('submit', function(e) {
            // Prevent double submission
            if (isSubmitting) return;
            
            e.preventDefault();
            isSubmitting = true;
            
            // Track the event
            window.Hakanai.trackEvent('Contact', {
                page: window.location.pathname,
                referrer: document.referrer
            }).then(() => {
                // Submit the form after tracking
                form.submit();
            }).catch((err) => {
                console.error('Error during tracking', err);
                // Still submit the form in case of error
                form.submit();
            });
        });
    });
</script>

Viewing in the Dashboard

Events are listed in their own panel on the dashboard and on each post page. The panel displays the number of events and the conversion rate.

Tips for Optimal Use

1. Use consistent event names: Adopt a naming convention for your events (e.g., "Article Read", "Product Added", etc.)
2. Structure your metadata: Organize your metadata consistently to facilitate later analysis.
3. Avoid excessive tracking: Only track events that have analytical importance to avoid overloading your dashboard.
4. Respect privacy: Never include personally identifiable information in your events without the user's explicit consent.

Troubleshooting

• Events not showing in the dashboard? Check that the Pulse script is correctly loaded on your site.
• Metadata not appearing? Make sure the data-hakanai-meta-* attributes are properly formatted.
• Events not triggering? Open the browser console to check for potential errors.