Installation Guide

Beginner https://datalayer-tracker.com/knowledge-base/installation-guide/
Last updated: October 22, 2025 First Event Getting Started Installation Quick Setup

Complete setup instructions for Advanced DataLayer Tracker

Overview

This guide walks you through installing Advanced DataLayer Tracker on your WordPress site. Whether you’re setting up for the first time or migrating from another tracking solution, you’ll have everything configured in 15-20 minutes.

What You’ll Learn:

  • Plugin installation methods
  • Initial configuration
  • Feature activation
  • Integration options
  • Verification steps

Prerequisites:

  • WordPress 5.0 or higher
  • PHP 7.4 or higher
  • Admin access to your WordPress site

Installation Methods

Choose the method that works best for you:

Method 1: WordPress Plugin Directory (Recommended)

Easiest installation method for most users

Steps:

  1. Log into WordPress Admin
  2. Navigate to: Plugins → Add New
  3. Search for: “Advanced DataLayer Tracker”
  4. Click Install Now on the ADT plugin
  5. Click Activate when installation completes

Verification:

  • New menu item appears: Settings → Advanced DataLayer
  • No error messages displayed
  • Plugin shows as “Active” in plugin list

Method 2: Upload Plugin ZIP File

Best when you have the plugin file from another source

Steps:

  1. Download the plugin ZIP file to your computer
  2. Log into WordPress Admin
  3. Navigate to: Plugins → Add New
  4. Click Upload Plugin button (top of page)
  5. Click Choose File and select the ZIP file
  6. Click Install Now
  7. Click Activate Plugin when installation completes

Verification:

  • Plugin appears in Plugins → Installed Plugins
  • Status shows “Active”
  • No PHP errors in admin

Method 3: FTP/SFTP Upload

For users comfortable with FTP or hosting control panel file managers

Steps:

  1. Download and extract the plugin ZIP file on your computer
  2. Connect to your site via FTP/SFTP
  3. Navigate to: /wp-content/plugins/
  4. Upload the entire advanced-datalayer-tracker folder
  5. In WordPress Admin, go to: Plugins → Installed Plugins
  6. Find “Advanced DataLayer Tracker”
  7. Click Activate

File structure should be:

/wp-content/plugins/advanced-datalayer-tracker/
    ├── advanced-datalayer-tracker.php (main file)
    ├── includes/
    ├── assets/
    └── readme.txt

Initial Configuration

Now that the plugin is installed, let’s configure the basics.

Step 1: Access Plugin Settings

  1. Navigate to: Settings → Advanced DataLayer in WordPress Admin
  2. You’ll see the ADT settings dashboard with multiple tabs

Main tabs available:

  • Core Settings – Enable/disable features
  • GTM Export – Generate GTM container
  • GA4 Settings – Configure Measurement Protocol
  • Consent Management – Privacy compliance
  • Pixel Manager – Third-party integrations
  • Advanced – Performance and debugging options

Step 2: Configure Core Settings

Navigate to the Core Settings tab

Essential settings to configure first:

Page Tracking:

  • Enable: Page View Tracking
  • Purpose: Foundation event for all tracking
  • Default: Enabled

Session Management:

  • Enable: Session Tracking
  • Purpose: Groups user actions into sessions
  • Creates persistent session ID across pages
  • Default: Enabled

Engagement Tracking:

  • Enable: Active Time Tracking (highly recommended)
  • Purpose: Measures TRUE user engagement
  • Tracks only when user is actively interacting
  • Default: Enabled
  • Enable: Scroll Depth Tracking
  • Purpose: Measures content consumption
  • Fires at 25%, 50%, 75%, 100% scroll depth
  • Default: Enabled

Form Tracking:

  • Enable: Form Tracking
  • Purpose: Tracks form starts and submissions
  • Automatically detects supported form plugins
  • Default: Enabled if forms detected

Click Tracking:

  • Enable: Click Tracking
  • Purpose: Tracks link clicks, button interactions
  • Filters internal vs external links
  • Default: Disabled (enable if needed)

Save your changes after enabling features.

Step 3: Choose Your Integration Path

ADT supports multiple integration methods. Choose the one that fits your needs:

Option A: Google Tag Manager (Most Popular)

Best for:

  • Sending data to multiple platforms (GA4, Meta, TikTok, etc.)
  • Marketing teams needing no-code control
  • Sites using A/B testing tools
  • Maximum flexibility

Setup time: 10-15 minutes

Quick setup:

  1. Click GTM Export tab
  2. Select features to include
  3. Generate and download JSON file
  4. Import to Google Tag Manager
  5. Publish container

Full guide: Google Tag Manager Setup Guide

Option B: GA4 Measurement Protocol (Server-Side)

Best for:

  • Direct GA4 connection only
  • Enhanced privacy compliance
  • Ad blocker resistance
  • Server-side tracking preference

Setup time: 5-10 minutes

Quick setup:

  1. Click GA4 Settings tab
  2. Enter GA4 Measurement ID (G-XXXXXXXXXX)
  3. Enter API Secret (from GA4 admin)
  4. Configure server-side events
  5. Save settings

Full guide: GA4 Measurement Protocol Setup Guide

Option C: Pixel Manager Integration

Best for:

  • Sites already using third-party pixel managers
  • Need compatibility with existing tracking
  • Using platforms like PixelYourSite, GTM4WP, etc.

Setup time: 5 minutes

Quick setup:

  1. Ensure pixel manager plugin is installed
  2. ADT automatically populates dataLayer
  3. Configure pixel manager to read ADT events
  4. No additional ADT configuration needed

Full guide: Pixel Manager Guide

Option D: Multiple Integrations

You can use multiple integration methods simultaneously:

  • GTM for marketing platforms
  • GA4 MP for server-side backup
  • Pixel manager for specific tools

This provides redundancy and maximizes data collection.

Step 4: Configure Consent Management

IMPORTANT: Proper consent configuration ensures privacy compliance.

Navigate to: Consent Management tab

If using a Consent Management Platform (CMP):

Supported platforms:

  • OneTrust
  • Cookiebot
  • CookieYes
  • Complianz
  • Cookie Notice
  • WP Cookie Consent
  • Borlabs Cookie
  • GDPR Cookie Compliance
  • Custom/Other

Setup steps:

  1. Select your CMP from the dropdown
  2. Map consent categories to tracking features:
    • Analytics consent → Page views, engagement, sessions
    • Marketing consent → UTM tracking, attribution
    • Advertising consent → Pixels, remarketing tags
  3. Save settings

Behavior:

  • Events respect user consent choices
  • Only enabled features fire when consent is granted
  • Consent changes take effect immediately
  • No data sent before consent granted

If NOT using a CMP:

Select “No Consent Platform”

  • All events fire immediately when enabled
  • User consent not required
  • Consider your privacy obligations

Full guide: Consent Management Guide

Step 5: Configure Advanced Settings (Optional)

Navigate to: Advanced tab

Performance options:

Event Queue:

  • Purpose: Batches events for performance
  • Reduces network requests
  • Recommended: Leave enabled
  • Default: Enabled

Debug Mode:

  • Purpose: Enables detailed console logging
  • Shows all event data in browser console
  • Recommended: Enable during setup, disable in production
  • Default: Disabled

DataLayer Name:

  • Purpose: Customize dataLayer variable name
  • Default: dataLayer (standard GTM name)
  • Change only if required by your setup

Session Timeout:

  • Purpose: Defines when a session expires
  • Default: 30 minutes of inactivity
  • Adjust based on your site’s typical engagement

Cookie Domain:

  • Purpose: Sets domain for tracking cookies
  • Default: Auto-detected
  • Override only for multi-domain setups

Feature Activation Guide

Now that core settings are configured, let’s enable specific features based on your needs.

E-commerce Tracking (WooCommerce)

Requirements:

  • WooCommerce plugin installed and active
  • Products configured in WooCommerce

Setup:

  1. Navigate to: Core Settings tab
  2. Find E-commerce Tracking section
  3. Enable: WooCommerce Integration
  4. Configure events to track:
    • view_item (product page views)
    • add_to_cart
    • remove_from_cart
    • view_cart
    • begin_checkout
    • purchase
  5. Save changes

Events automatically fire:

  • When users view products
  • Add/remove from cart
  • View cart page
  • Start checkout
  • Complete purchase

Full guide: E-commerce Tracking Guide

Video Tracking

Automatically detects:

  • YouTube embeds
  • Vimeo embeds
  • HTML5 video elements

Setup:

  1. Navigate to: Core Settings tab
  2. Enable: Video Tracking
  3. Configure tracking points:
    • 0% (start)
    • 25% (quarter point)
    • 50% (midpoint)
    • 75% (three-quarter)
    • 90% (near complete)
    • 100% (complete)
  4. Save changes

Events track:

  • video_start
  • video_progress (at each milestone)
  • video_complete
  • video_pause

Form Tracking (Advanced)

Automatically detects:

  • Gravity Forms
  • Contact Form 7
  • WPForms
  • Formidable Forms
  • Marketo forms
  • HubSpot forms
  • Generic HTML forms

Setup:

  1. Navigate to: Core Settings tab
  2. Enable: Form Tracking
  3. Enable: Field-Level Tracking (for detailed analysis)
  4. Select form vendors to track
  5. Save changes

Events tracked:

  • form_start (first field interaction)
  • form_submit (successful submission)
  • form_field_interaction (field-level detail)

Field-level tracking reveals:

  • Which fields cause abandonment
  • Time spent on each field
  • Error-prone fields
  • Completion patterns

UTM & Attribution Tracking

Captures campaign data automatically

Setup:

  1. Navigate to: Core Settings tab
  2. Enable: UTM Parameter Tracking
  3. Enable: Attribution Tracking
  4. Configure attribution windows (optional)
  5. Save changes

Automatically captures:

  • utm_source
  • utm_medium
  • utm_campaign
  • utm_term
  • utm_content
  • First touch attribution
  • Last touch attribution
  • Multi-touch journey data

Full guide: Attribution in Session Management Guide

Premium Features (Optional)

Session Manager (Premium):

  • Cross-page session persistence
  • Session quality scoring
  • Advanced attribution modeling
  • Intelligent event aggregation

Content Intelligence (Premium):

  • Automatic content type detection
  • Section-level engagement tracking
  • CTA exposure analysis
  • Intent scoring

Setup: Contact support for premium feature activation

Full guide: Session Management Guide

Verification & Testing

Let’s verify everything is working correctly.

Step 1: Check Plugin Status

In WordPress Admin:

  1. Navigate to: Plugins → Installed Plugins
  2. Verify “Advanced DataLayer Tracker” shows Active
  3. No error messages displayed
  4. Version number visible

Check for conflicts:

  • Deactivate other tracking plugins temporarily
  • Test if ADT works properly
  • Reactivate one at a time if conflicts occur

Step 2: Verify Events Are Firing

Using Debug Overlay (Recommended):

  1. Visit your website (frontend, not admin)
  2. Open browser console (F12)
  3. Type: ADT.debugOverlay.open()
  4. Debug overlay appears on screen

What to verify:

  • Session ID displays
  • page_view event fires immediately
  • Scroll page → scroll_depth events at 25%, 50%, 75%, 100%
  • Wait 30s with activity → active_time event fires
  • No error messages in overlay

Full guide: First Successful Event Guide

Using Browser Console:

  1. Open console (F12)
  2. Type: dataLayer
  3. Press Enter
  4. Should see array of events
  5. Each event contains name and parameters

Example output:

[
  {
    event: "page_view",
    page_location: "https://yoursite.com/page",
    page_title: "Page Title",
    session_id: "sess_xxxxx"
  },
  {
    event: "scroll_depth",
    scroll_percent: 25,
    time_to_scroll: 5.2
  }
]

Using Google Tag Manager Preview:

If using GTM integration:

  1. Open Google Tag Manager
  2. Click Preview button
  3. Enter your website URL
  4. GTM preview panel opens
  5. Navigate your site
  6. Events appear in real-time

Verify:

  • Tags fire correctly
  • Triggers activate as expected
  • Variables populate with data
  • No tag errors shown

Using GA4 DebugView:

If using GA4 Measurement Protocol:

  1. Open Google Analytics 4
  2. Navigate to: Admin → DebugView
  3. Visit your website
  4. Events appear within seconds

Verify:

  • Events show correct names
  • Parameters populate correctly
  • Event count increments
  • No error events

Step 3: Test Key Features

Test each enabled feature:

Page Views:

  • Visit multiple pages
  • Each should fire page_view event
  • page_location and page_title should update

Scroll Depth:

  • Scroll to 25% → event fires
  • Continue to 50%, 75%, 100%
  • Each fires separate event

Active Time:

  • Stay on page with activity
  • Every 30 seconds → active_time event
  • Verify cumulative time increases

Forms:

  • Click into form field → form_start fires
  • Complete and submit → form_submit fires
  • Check form_name parameter matches

E-commerce (if enabled):

  • View product → view_item fires
  • Add to cart → add_to_cart fires
  • Complete checkout → purchase fires

Video (if enabled):

  • Play video → video_start fires
  • Watch to milestones → video_progress fires
  • Complete video → video_complete fires

Common Installation Issues

Issue: Plugin Won’t Activate

Possible causes:

  • PHP version too old
  • WordPress version too old
  • File permissions incorrect
  • Conflicting plugin

Solutions:

Check requirements:

  • PHP 7.4+ required (check in hosting dashboard)
  • WordPress 5.0+ required
  • Update if needed

Check file permissions:

Directories: 755
Files: 644

Check for conflicts:

  • Deactivate all other plugins
  • Try activating ADT
  • If successful, reactivate plugins one by one
  • Identify conflicting plugin

Issue: Settings Page Missing

Possible causes:

  • Plugin not fully activated
  • User permissions insufficient
  • WordPress menu cache issue

Solutions:

Verify activation:

  1. Plugins → Installed Plugins
  2. ADT should show “Deactivate” link (not “Activate”)

Check user permissions:

  • Must be Administrator role
  • Must have manage_options capability

Clear WordPress cache:

  1. If using caching plugin, clear cache
  2. Hard refresh browser: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
  3. Try different browser

Issue: Events Not Firing

Possible causes:

  • Features not enabled
  • JavaScript errors on page
  • Consent blocking events
  • GTM not installed (if using GTM)

Solutions:

Enable features:

  1. Settings → Advanced DataLayer → Core Settings
  2. Verify toggles are ON for desired features
  3. Save changes
  4. Reload website page

Check for JavaScript errors:

  1. Open browser console (F12)
  2. Look for red error messages
  3. Resolve conflicts
  4. Common culprits: theme JS, other plugins

Check consent:

  1. If using CMP, grant all consents for testing
  2. Or temporarily disable consent requirements
  3. Verify events fire with full consent

Verify GTM installed:

  1. View page source
  2. Search for “GTM-“
  3. Should find container ID in code
  4. If missing, install GTM snippet

Issue: Duplicate Events

Possible causes:

  • Multiple tracking plugins active
  • GTM installed multiple times
  • Theme includes tracking code

Solutions:

Check for duplicate plugins:

  • Deactivate other GA4/GTM plugins
  • Test if duplicates stop
  • Use only one tracking solution

Check GTM installations:

  1. View page source
  2. Count instances of “GTM-“
  3. Should appear exactly twice (head + body)
  4. Remove duplicates from theme if found

Check theme code:

  • Review theme’s header.php
  • Look for hardcoded analytics
  • Remove or disable

Issue: Database Errors

Possible causes:

  • Database connection issue
  • Table creation failed
  • Insufficient permissions

Solutions:

Check error logs:

  1. Enable WordPress debugging
  2. Add to wp-config.php:
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
  1. Check /wp-content/debug.log
  2. Look for ADT-related errors

Manual table creation: If automatic table creation failed, contact support for manual SQL scripts.

Post-Installation Checklist

Use this checklist to ensure complete setup:

Installation:

  • [ ] Plugin installed via one of the three methods
  • [ ] Plugin activated successfully
  • [ ] No error messages displayed
  • [ ] Settings page accessible

Configuration:

  • [ ] Core features enabled (page views, sessions, engagement)
  • [ ] Integration method chosen and configured
  • [ ] Consent management configured (if using CMP)
  • [ ] Advanced settings reviewed

Feature Activation:

  • [ ] Essential features enabled (active_time, scroll, forms)
  • [ ] E-commerce enabled (if using WooCommerce)
  • [ ] Video tracking enabled (if using videos)
  • [ ] UTM tracking enabled

Verification:

  • [ ] Debug overlay opens and shows events
  • [ ] dataLayer populates correctly
  • [ ] GTM preview shows events (if using GTM)
  • [ ] GA4 DebugView shows events (if using GA4)
  • [ ] Key features tested and working

Testing:

  • [ ] Page views fire on all page types
  • [ ] Scroll events fire at correct percentages
  • [ ] Forms track start and submit
  • [ ] No JavaScript errors in console
  • [ ] No PHP errors in WordPress

Documentation:

  • [ ] Quick Start Guide reviewed
  • [ ] First Event Guide completed
  • [ ] Team trained on debug tools
  • [ ] Integration guides bookmarked

Next Steps

You’ve successfully installed and configured Advanced DataLayer Tracker. Here’s what to do next:

Immediate (Today)

Verify tracking is working:

  • Visit multiple pages on your site
  • Test all enabled features
  • Check data in GTM/GA4
  • Resolve any issues found

Explore the Debug Overlay:

  • Learn keyboard shortcuts
  • Review event parameters
  • Monitor session data
  • Export test data

Guide: First Successful Event Guide

This Week

Enable advanced features:

  • Video tracking (if applicable)
  • Field-level form tracking
  • Advanced e-commerce events
  • Attribution tracking

Set up analytics:

  • Create GA4 custom reports
  • Configure GTM tags for other platforms
  • Build audience segments
  • Set up conversion goals

Guide: Complete Event Guide

This Month

Optimize based on data:

  • Review form abandonment rates
  • Analyze content engagement (active_time)
  • Identify high-quality traffic sources
  • Optimize low-performing pages

Implement advanced tracking:

  • Session quality scoring
  • Content intelligence
  • Multi-touch attribution
  • Custom events

Guide: Engagement Tracking Guide

Ongoing

Monitor and maintain:

  • Review weekly analytics
  • Update tracking as site changes
  • Add new events for new features
  • Train team on new capabilities

Optimize continuously:

  • A/B test based on insights
  • Refine audience segments
  • Improve conversion funnels
  • Enhance user experience

Additional Resources

Documentation

Getting Started:

Feature Guides:

Integration Guides:

Reference:

Support

Before contacting support:

  1. Check this Installation Guide
  2. Review relevant feature guides
  3. Test with Debug Overlay
  4. Check browser console for errors
  5. Verify all requirements met

When contacting support, include:

  • WordPress version
  • PHP version
  • Plugin version
  • List of active plugins
  • Description of issue
  • Steps to reproduce
  • Screenshots of errors
  • Console error messages

Troubleshooting Resources

Debug Overlay:

  • Real-time event monitoring
  • Session data inspection
  • Export capabilities
  • Performance metrics

Browser Console:

  • JavaScript error detection
  • dataLayer inspection
  • Network request monitoring
  • Debug logging

GTM Preview Mode:

  • Tag firing verification
  • Trigger testing
  • Variable inspection
  • Container debugging

GA4 DebugView:

  • Event verification
  • Parameter checking
  • Real-time monitoring
  • Error detection

Best Practices

During Installation:

  • Test on staging site first (if available)
  • Back up your site before installing
  • Keep other plugins updated
  • Document any customizations

After Installation:

  • Enable features gradually
  • Test each feature individually
  • Monitor performance impact
  • Review data quality regularly

Ongoing Maintenance:

  • Keep plugin updated
  • Review release notes
  • Test after WordPress updates
  • Monitor for conflicts

Data Quality:

  • Use Debug Overlay during setup
  • Verify events in multiple tools
  • Cross-check data sources
  • Audit configuration quarterly

Security Considerations

Data Privacy:

  • Configure consent management properly
  • Respect user privacy choices
  • Document data collection practices
  • Comply with applicable regulations (GDPR, CCPA, etc.)

Access Control:

  • Limit plugin settings access to administrators
  • Review user capabilities
  • Secure API credentials
  • Use strong passwords

Performance:

  • Monitor page load impact
  • Enable event queue batching
  • Optimize for mobile devices
  • Test with performance tools

Success Metrics

Track these metrics to measure successful installation:

Day 1:

  • Plugin activated without errors
  • Settings page accessible
  • Debug overlay showing events
  • No JavaScript conflicts

Week 1:

  • All core events firing correctly
  • Data flowing to analytics platform
  • No duplicate events
  • Team trained on basics

Month 1:

  • Advanced features enabled
  • Data-driven insights emerging
  • First optimizations implemented
  • Positive ROI tracking

Congratulations! You’ve successfully installed Advanced DataLayer Tracker. You now have enterprise-level tracking on your WordPress site with zero coding required.

Start with core events, verify they work, then gradually enable advanced features as needed. The plugin grows with your requirements.

Version: 1.0
Last Updated: October 2025
Plugin: Advanced DataLayer Tracker

Was this article helpful?

Related Articles