Customize Your Tracking

This document describes how the HockeyStack website tracking pixel is deployed and emphasizes the customer's complete control over when and how the pixel fires.

Overview

The HockeyStack pixel is a lightweight JavaScript tracking script that enables website analytics and event tracking. The pixel is designed to give customers full control over when tracking events fire, making it compatible with various deployment scenarios and privacy requirements.

Deployment Methods

Customers have two primary deployment options, both of which provide complete control over when the pixel fires:

1. Direct Page Deployment

Deploy the pixel directly in your website's HTML by inserting the tracking script into the <head> section of your pages.

Base Script:

<script>
  var hsscript = document.createElement("script");
  [hsscript.id](<http://hsscript.id>) = "wphs";
  hsscript.src = "<https://cdn.jsdelivr.net/npm/hockeystack@latest/hockeystack.min.js>";
  hsscript.async = 1;
  hsscript.dataset.apikey = "YOUR_API_KEY";
  hsscript.dataset.cookieless = 1;
  hsscript.dataset.autoIdentify = 1;
  document.getElementsByTagName('head')[0].append(hsscript);
</script>

Customer Control:

When it loads: The script uses async = 1, so you control when it's added to the DOM
When it fires: The pixel automatically tracks page views on initialization, but you can disable automatic tracking or control it via JavaScript
Manual triggering: You have full access to the HockeyStack API to fire events on demand using HockeyStack.goal() and HockeyStack.identify()

Example - Conditional Loading:

<script>
  // Only load the pixel after user consent
  if (userHasConsented()) {
    var hsscript = document.createElement("script");
    hsscript.src = "<https://cdn.jsdelivr.net/npm/hockeystack@latest/hockeystack.min.js>";
    hsscript.async = 1;
    hsscript.dataset.apikey = "YOUR_API_KEY";
    document.getElementsByTagName('head')[0].append(hsscript);
  }
</script>

2. Tag Manager Deployment

Deploy the pixel through any tag manager (Google Tag Manager, Tealium, Segment, etc.) for centralized tag management.

Google Tag Manager Example:

Create a new Custom HTML tag in GTM
Paste the HockeyStack script (same as above)
Configure the trigger to fire when you want (e.g., "All Pages", "Consent Granted", custom events)

Customer Control:

When it loads: Tag managers give you complete control via trigger conditions
When it fires: Configure triggers based on:
- Page views (all pages, specific pages, or custom conditions)
- User interactions (clicks, form submissions, scroll depth)
- Custom events you define
- Consent status (GDPR/CCPA compliance)
- Any other condition supported by your tag manager

Example GTM Trigger Configuration:

Trigger Type: Page View
This trigger fires on: All pages
- OR: Specific pages matching a regex pattern
- OR: Custom events
- OR: After consent is granted

Customer Control Over Pixel Firing

Automatic vs. Manual Tracking

The HockeyStack pixel provides multiple layers of customer control:

1. Script Loading Control

Async loading: The script loads asynchronously, so you control when it's added to the page
Conditional loading: Only load the script when specific conditions are met (consent, user type, page type, etc.)
Tag manager triggers: Use tag manager trigger conditions to control exactly when the script loads

2. Automatic Page View Tracking

By default, the pixel automatically tracks page views when initialized
This automatic tracking can be:
- Delayed: Load the script after page load using tag manager triggers or custom JavaScript
- Conditional: Only load/fire on specific pages or conditions
- Disabled: Load the script but prevent automatic page tracking (requires custom configuration)

3. Manual Event Tracking

Customers have full programmatic control via the HockeyStack JavaScript API:

Track Custom Goals:

// Fire a custom event whenever you want
HockeyStack.goal('Button Clicked', {
  buttonId: 'signup',
  page: '/pricing'
});

// Fire after a specific user action
document.getElementById('cta-button').addEventListener('click', function() {
  HockeyStack.goal('CTA Clicked', {
    buttonText: this.textContent,
    section: 'hero'
  });
});

Identify Users:

// Identify a user when you have their information
HockeyStack.identify('[user@example.com](<mailto:user@example.com>)');

// Identify with properties
HockeyStack.identify({
  email: '[user@example.com](<mailto:user@example.com>)',
  plan: 'premium',
  signupDate: '2024-01-15'
});

Control Timing:

// Fire events based on any condition
if (purchaseCompleted) {
  HockeyStack.goal('Purchase Completed', {
    amount: orderTotal,
    items: itemCount
  });
}

// Fire only after consent
if (consentGranted) {
  HockeyStack.identify(userEmail);
}

Configuration Options

The pixel supports various data attributes that give you additional control:

Attribute

Description

Customer Control

data-apikey

Your HockeyStack API key

Required for identification

data-cookieless

Enable cookieless tracking

Choose privacy mode

data-auto-identify

Auto-identify from forms

Control automatic behavior

data-privacy-mode

Enable privacy mode

Control data collection level

data-interval-start

Initial tracking interval

Control tracking frequency

data-interval-increment

Interval increment

Fine-tune tracking behavior

Tag Manager Best Practices

When deploying through tag managers, you have complete control:

Google Tag Manager

Create a Custom HTML tag with the HockeyStack script
Configure triggers to control when it fires:
- All pages → immediate tracking
- Specific pages → selective tracking
- Custom events → event-based tracking
- Consent status → privacy-compliant tracking
Use variables to dynamically set the API key or other configuration

Other Tag Managers

Tealium: Use Custom HTML tags with trigger conditions
Segment: Deploy via Segment's JavaScript integration
Adobe Launch: Use custom code extensions with rules
Any tag manager: The script works with any tag manager that supports custom HTML/JavaScript

Content Security Policy (CSP)

If you have a Content Security Policy, whitelist the following:

script-src: cdn.jsdelivr.net
connect-src: data.hockeystack.com

Key Takeaways

Customer Control is Built-In:

✅ When the script loads: Control via async loading, conditional logic, or tag manager triggers
✅ When page views fire: Control via script loading timing, tag manager triggers, or disabling automatic tracking
✅ When custom events fire: Full programmatic control via HockeyStack.goal() and HockeyStack.identify() API calls
✅ Deployment flexibility: Works whether deployed directly on the page or through any tag manager
✅ Privacy compliance: Control tracking based on consent status, user preferences, or any custom condition

The pixel is designed to be customer-controlled at every level—from when it loads to when it fires events. This gives you the flexibility to integrate HockeyStack tracking in a way that matches your technical requirements, privacy policies, and business needs.

This document describes how the HockeyStack website tracking pixel is deployed and emphasizes the customer's complete control over when and how the pixel fires, whether deployed directly on the page or through a tag manager.

PreviousWhy Website Tracking via HockeyStack’s JS Snippet Outperforms CDP Data

NextData Processing from Integrations

Last updated 8 months ago