# Customize Your Tracking ### 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 `` section of your pages. **Base Script:** ```html ``` **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:** ```html ``` #### 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:** 1. Create a new **Custom HTML** tag in GTM 2. Paste the HockeyStack script (same as above) 3. 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:** ```jsx // 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:** ```jsx // Identify a user when you have their information HockeyStack.identify('[user@example.com]()'); // Identify with properties HockeyStack.identify({ email: '[user@example.com]()', plan: 'premium', signupDate: '2024-01-15' }); ``` **Control Timing:** ```jsx // 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 1. **Create a Custom HTML tag** with the HockeyStack script 2. **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 3. **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`](http://cdn.jsdelivr.net) * **connect-src**: [`data.hockeystack.com`](http://data.hockeystack.com) *** ### Key Takeaways **Customer Control is Built-In:** 1. ✅ **When the script loads**: Control via async loading, conditional logic, or tag manager triggers 2. ✅ **When page views fire**: Control via script loading timing, tag manager triggers, or disabling automatic tracking 3. ✅ **When custom events fire**: Full programmatic control via `HockeyStack.goal()` and `HockeyStack.identify()` API calls 4. ✅ **Deployment flexibility**: Works whether deployed directly on the page or through any tag manager 5. ✅ **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. *** --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.hockeystack.com/technical-details/tracking/customize-your-tracking.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.