Admin Tools Guide

Comprehensive Reference for Plugin Management & Troubleshooting

Table of Contents

1. Overview
2. Accessing Admin Tools
3. Field Mapping Debug Tool
4. Diagnostic & Settings Tools
5. Danger Zone – Reset Settings
6. Cache Management
7. Export History Management
8. Admin Bar CMP Status Monitor
9. Troubleshooting Guide
10. Best Practices

Overview

The Advanced DataLayer Tracker Admin Tools provide essential utilities for:

• Debugging field mappings for form vendors (Marketo, HubSpot, etc.)
• Diagnosing settings issues and orphaned fields
• Resetting configurations when needed
• Managing cache across popular plugins
• Tracking export history for GTM containers
• Monitoring consent management integration

These tools are available in the WordPress admin area under Settings → Advanced DataLayer → Admin Tools Tab.

Accessing Admin Tools

Location

WordPress Admin → Settings → Advanced DataLayer

Required Permissions

• User Role: Administrator
• Capability: manage_options

Navigation

The Admin Tools section is organized into collapsible panels (postboxes) for:

1. Field Mapping Debug Tool
2. Settings Diagnostic Tool
3. Danger Zone (Reset to Defaults)

Field Mapping Debug Tool

Purpose

Verifies that form field mappings for marketing automation platforms are correctly registered in the plugin architecture.

Supported Platforms

• Marketo (Munchkin)
• HubSpot Forms
• Formidable Forms
• Gravity Forms
• Contact Form 7
• WPForms
• Other form plugins

How to Use

Step 1: Open the Tool

1. Navigate to Settings → Advanced DataLayer → Admin Tools tab
2. Find the “Field Mapping Debug Tool” postbox
3. Click to expand if closed

Step 2: Run the Debug

1. Click the “Run Field Debug” button
2. The tool will display a comprehensive report

Debug Report Contents

1. Orphaned Fields Warning

If the tool detects orphaned fields (fields in database but not in current plugin architecture):

⚠️ Orphaned Fields Detected

These fields exist in your database but are not defined in the current 
plugin architecture. They are safe to remove:

• deprecated_field_1
• old_tracking_option
• unused_feature_toggle

[🗑️ Clean Up Orphaned Fields] (5 field(s) will be removed)

What Are Orphaned Fields?

• Settings keys that exist in wp_options table under adt_settings
• No longer defined in the current $field_map structure
• Typically from:
  • Previous plugin versions
  • Disabled features
  • Development/testing artifacts

Are They Harmful? No, but they:

• Clutter the database
• Can cause confusion during debugging
• May interfere with fresh installs

How to Clean Them

1. Click the “Clean Up Orphaned Fields” button
2. Confirm the action (cannot be undone)
3. Orphaned fields are permanently removed
4. Success message displays count removed

2. Field Map Structure by Section

Displays all registered fields organized by their configuration section:

📋 Field Map Structure by Section

▼ general (15 fields)
   Key: debug_mode
   Type: checkbox
   Default: 1
   Label: Enable Debug Mode
   Description: Show detailed logging in browser console
   
   Key: enable_debug_overlay
   Type: checkbox
   Default: 1
   Label: Enable Debug Overlay
   Premium: Yes
   
   [... more fields ...]

▼ ecommerce (8 fields)
   [... fields ...]

▼ forms (12 fields)
   [... fields ...]

Key Information Displayed:

• Section Name: The configuration group (general, ecommerce, forms, etc.)
• Field Count: Number of fields in each section
• Field Key: The database/code identifier
• Type: checkbox, text, select, textarea, number
• Default Value: What value is used on fresh install
• Label: Human-readable name shown in settings
• Description: Help text explaining the field
• Premium: Whether feature requires Pro license

3. Backend Saved Settings

Shows actual values stored in the WordPress database:

⚙️ Flat Settings with Default Comparison

Key                           | Section    | Type     | Saved  | Default | Status
-----------------------------------------------------------------------------------------
debug_mode                    | general    | checkbox | 1      | 1       | ✅ Matches
enable_debug_overlay          | general    | checkbox | 1      | 1       | ✅ Matches  
deprecated_old_field          | ⚠️ orphaned | unknown  | 0      | —       | 🧹 Orphaned
include_page_type             | core       | checkbox | 1      | 1       | ✅ Matches
custom_tracking_id            | ⚙️ safety-net | text   | ABC123 | —       | ℹ️ Safety-net

Status Indicators:

• ✅ Matches: Saved value equals default (expected)
• ⚠️ Custom: User has changed from default (normal)
• 🧹 Orphaned: Field not in current architecture (consider cleanup)
• ℹ️ Safety-net: Allowed field not in $field_map (whitelisted)

Safety-Net Fields Some fields are intentionally excluded from $field_map but are still valid:

$allowed_safety_fields = [
    'ga4_measurement_id',
    'gtm_container_id', 
    'pixel_event_map_json',
    'custom_events_json',
    'fb_pixel_id',
    'tiktok_pixel_id',
    'pinterest_pixel_id',
    'snapchat_pixel_id',
    'reddit_pixel_id',
    'twitter_pixel_id'
];

These are typically:

• Dynamic configuration data
• JSON-based settings
• External service IDs
• User-specific customizations

Using Debug Output for Troubleshooting

Scenario 1: Field Not Saving

Problem: You enable a checkbox in settings, click save, but it reverts to unchecked.

Diagnosis:

1. Run Field Debug
2. Search for your field key in the report
3. Check if it appears in $field_map structure
4. If missing → field is not registered (plugin bug or version mismatch)
5. If present → check default value and validation logic

Scenario 2: Unknown Fields in Database

Problem: You see strange settings keys in your database export.

Diagnosis:

1. Run Field Debug
2. Look for orphaned fields section
3. If field is orphaned:
   • From old plugin version → safe to remove
   • From another plugin → don’t remove (wrong adt_settings option)
   • Unknown origin → investigate before removing

Scenario 3: Premium Feature Not Working

Problem: Premium feature enabled but not functioning.

Diagnosis:

1. Run Field Debug
2. Find the feature’s field in structure report
3. Check if marked Premium: Yes
4. Verify your license status in plugin
5. If licensed but marked premium → license check may be failing

Diagnostic & Settings Tools

Settings Diagnostic Display

Located above the Field Mapping Debug Tool, this section shows:

🔍 Settings Diagnostic Information

=== ADT SETTINGS DIAGNOSTIC ===

Settings exist in DB: YES
Settings count: 127

First 10 settings:
  debug_mode = 1
  include_page_type = 1
  enable_debug_overlay = 1
  [...]

=== FUNCTION SOURCE ===
File: /wp-content/plugins/advanced-datalayer-tracker/includes/adt-settings-register.php
Line: 45

Sample from function:
include_page_type = 1
include_post_id = 1
debug_mode = 1

When to Use:

• Settings not loading correctly
• Blank settings page
• Investigating function execution path
• Verifying default values source

Settings Restoration

If settings become corrupted:

// Force restore defaults (temporary diagnostic code)
$correct_defaults = adt_get_default_settings();
update_option('adt_settings', $correct_defaults);

Success Message:

✅ Settings have been restored! All checkboxes should now show correctly.

Danger Zone – Reset Settings

Purpose

Completely reset all ADT settings to factory defaults.

⚠️ WARNING

This action:

• ✅ Resets ALL plugin settings to defaults
• ❌ Cannot be undone
• ❌ Removes all custom configurations
• ❌ Clears all custom field mappings
• ❌ Removes all enabled feature selections
• ✅ Resets notice dismissals (welcome notice will show again)
• ✅ Clears cache across supported plugins

When to Use

• Plugin malfunction after bad configuration
• Settings completely broken/corrupted
• Fresh start needed for testing
• Preparing plugin for new setup
• Resolving persistent bugs caused by settings

How to Reset

Step 1: Access Danger Zone

1. Navigate to Settings → Advanced DataLayer → Admin Tools tab
2. Scroll to ⚠️ Danger Zone section (red header)
3. Section is only visible to administrators

Step 2: Understand the Impact

Read the confirmation message carefully:

⚠️ WARNING: This will reset ALL settings to defaults!

• All custom configurations will be lost
• All enabled features will be reset  
• All custom field mappings will be cleared
• Orphaned fields will be removed

This action cannot be undone.

Are you absolutely sure you want to continue?

Step 3: Confirm Reset

1. Click the red “Reset All Settings to Defaults” button
2. JavaScript confirmation dialog appears (double-check)
3. Click OK to proceed, Cancel to abort

Step 4: Automatic Actions

Upon confirmation, the plugin:

1. Loads Fresh Defaults $defaults = adt_get_default_settings();
2. Replaces Database Settings update_option('adt_settings', $defaults);
3. Resets All Notice Dismissals delete_option('adt_welcome_dismissed'); delete_option('adt_notice_dismissed_welcome'); delete_option('adt_notice_dismissed_dual_pixel'); delete_user_meta($user_id, 'adt_cmp_notice_dismissed_at');
4. Resets Activation Timestamp update_option('adt_activation_timestamp', time()); This makes the welcome notice appear again
5. Clears WordPress Core Cache wp_cache_delete('adt_settings', 'options'); wp_cache_delete('alloptions', 'options');
6. Logs the Action adt_debug_log('Settings reset to defaults by user ' . get_current_user_id());
7. Redirects with Success Message wp_redirect(add_query_arg([ 'page' => 'adt-settings', 'tab' => 'admin_tools', 'reset' => 'success' ], admin_url('admin.php')));

Step 5: Verify Reset

After redirect, you’ll see:

✅ Settings reset to defaults successfully.

Verify by checking:

• All checkboxes match default state (mostly enabled)
• Custom text fields are cleared
• Welcome notice appears again
• Debug overlay settings reset
• All premium features locked if not licensed

What Does NOT Reset

• Export History: Stored per-user, not in adt_settings
• Plugin Activation: Plugin remains active
• GTM Container Files: Previously exported files not deleted
• WooCommerce Data: Order history, customer data untouched
• Form Submissions: Historical form data preserved
• Google Analytics Data: External data not affected

Recovery After Reset

If you accidentally reset and want to restore previous configuration:

Option 1: Import Previous Settings (if exported)

Settings → Advanced DataLayer → Import/Export tab
→ Import Settings → Choose JSON file → Import

Option 2: Reconfigure Manually

• Review your notes or screenshots
• Re-enable desired features
• Re-enter custom field mappings
• Re-configure integrations

Option 3: Restore from Database Backup

If you have a database backup:

-- Find previous adt_settings value in backup
SELECT option_value FROM wp_options WHERE option_name = 'adt_settings';

-- Restore manually or via phpMyAdmin

Cache Management

Automatic Cache Clearing

The plugin automatically clears caches when:

• Settings are updated
• Plugin is reset to defaults
• Orphaned fields are cleaned up

Supported Cache Plugins

1. WP Rocket

if (function_exists('rocket_clean_domain')) {
    rocket_clean_domain();
    if (function_exists('rocket_clean_minify')) {
        rocket_clean_minify('css');
        rocket_clean_minify('js');
    }
}

Clears:

• Page cache
• Minified CSS
• Minified JavaScript

2. W3 Total Cache

if (function_exists('w3tc_flush_all')) {
    w3tc_flush_all();
}

Clears:

• All cache types
• Database cache
• Object cache
• Browser cache

3. WP Super Cache

if (function_exists('wp_cache_clear_cache')) {
    wp_cache_clear_cache();
}

Clears:

• Supercache files
• Cached pages

4. LiteSpeed Cache

if (class_exists('LiteSpeed_Cache_API')) {
    LiteSpeed_Cache_API::purge_all();
}

Clears:

• Page cache
• Object cache
• CDN cache

5. Autoptimize

if (class_exists('autoptimizeCache')) {
    autoptimizeCache::clearall();
}

Clears:

• Minified CSS/JS
• Aggregated files

6. SG Optimizer (SiteGround)

if (function_exists('sg_cachepress_purge_cache')) {
    sg_cachepress_purge_cache();
}

Clears:

• Dynamic cache
• Memcached

7. WP Fastest Cache

if (function_exists('wpfc_clear_all_cache')) {
    wpfc_clear_all_cache(true);
}

Clears:

• All cached files
• Minified resources

WordPress Core Cache

wp_cache_delete('adt_settings', 'options');
wp_cache_delete('adt_field_map', 'adt');
wp_cache_delete('adt_default_settings', 'adt');
wp_cache_flush(); // Nuclear option

Transients

delete_transient('adt_settings_fresh');
set_transient('adt_settings_fresh', true, 30); // 30 seconds

Asset Versioning

update_option('adt_cache_buster', time(), false);

Used to force browser reload of CSS/JS files.

Conditional Page Cache Bypass

For premium users with debug overlay enabled:

add_action('send_headers', function() {
    if (!is_user_logged_in()) return;
    
    $settings = get_option('adt_settings', []);
    
    // Check both that overlay is enabled AND user wants to see it
    if (empty($settings['enable_debug_overlay'])) return;
    if (empty($settings['show_debug_overlay'])) return;
    
    $min_role = $settings['overlay_min_role'] ?? 'administrator';
    
    if (adt_user_has_min_role($min_role)) {
        // Bypass page cache for this request
        define('DONOTCACHEPAGE', true);
        define('DONOTCACHEDB', true);
        define('DONOTMINIFY', true);
        define('DONOTCDN', true);
    }
});

Why This Matters:

• Debug overlay shows real-time data
• Cache would serve stale overlay HTML
• Only affects logged-in users with permission
• Doesn’t impact regular visitors

Manual Cache Clear

If automatic clearing fails:

Via WordPress Admin

1. Go to your cache plugin’s settings
2. Find “Clear All Cache” or “Purge Cache” button
3. Click to manually clear

Via Server (SSH)

# Clear WP Object Cache
wp cache flush

# Clear Transients
wp transient delete --all

# WP Rocket
wp rocket clean --confirm

# Clear LiteSpeed
wp litespeed-purge all

Via Database

-- Clear all transients
DELETE FROM wp_options 
WHERE option_name LIKE '%_transient_%';

-- Clear ADT-specific cache
DELETE FROM wp_options 
WHERE option_name LIKE 'adt_%cache%';

Export History Management

Purpose

Track all GTM container exports for version control and rollback capability.

Data Stored Per Export

{
  exportId: 'exp_k3j9d82f',
  timestamp: 1698765432,
  user: 'admin',
  features: [
    'page_view',
    'click_tracking',
    'scroll_tracking',
    'form_tracking'
  ],
  mode: 'full',
  canUsePremium: true,
  debug: false,
  pluginVersion: '2.0.5'
}

Storage Location

• Database Table: wp_usermeta
• Meta Key: adt_export_history
• Scope: Per-user (each admin has their own history)
• Limit: Last 50 exports

Accessing Export History

Location

Settings → Advanced DataLayer → GTM Export Tab
→ Scroll to "Export History" section

Display Format

📋 Your Recent Exports (Last 10)

exp_a7b3c2d1  |  Oct 22, 2025 3:45 PM  |  admin
Features: Page View, Click Tracking, Scroll Tracking, Form Tracking
Mode: Full Export  |  Premium: Yes  |  Debug: No

exp_x9y8z7w6  |  Oct 20, 2025 11:22 AM  |  admin  
Features: Page View, E-Commerce, Customer Type
Mode: Selected Features  |  Premium: Yes  |  Debug: No

[View Full History (50)]  [Clear History]

Export History Actions

1. View Full History

• Shows all 50 stored exports
• Sortable by date, features, or mode
• Searchable by export ID

2. Clear History

// Frontend JS call
ADTExportHistory.clear();

// Triggers AJAX request to:
// wp-admin/admin-ajax.php?action=adt_clear_export_history

// Backend PHP handler:
delete_user_meta(get_current_user_id(), 'adt_export_history');

Effect:

• Permanently removes export history
• Cannot be undone
• Does NOT delete actual exported JSON files
• Only affects current user’s history

3. Export History as JSON

ADTExportHistory.export();

Downloads: adt-export-history-YYYY-MM-DD.json

Use Cases:

• Backup before major changes
• Share with team members
• Audit trail for compliance
• Debugging export issues

AJAX Endpoints

Get Export History

jQuery.post(ajaxurl, {
  action: 'adt_get_export_history',
  security: ADTData.nonce
}, function(response) {
  if (response.success) {
    console.log(response.data); // Array of exports
  }
});

Save Export History

jQuery.post(ajaxurl, {
  action: 'adt_save_export_history',
  security: ADTData.nonce,
  history: JSON.stringify(updatedHistory)
}, function(response) {
  if (response.success) {
    console.log('History saved:', response.data.count);
  }
});

Clear Export History

jQuery.post(ajaxurl, {
  action: 'adt_clear_export_history',
  security: ADTData.nonce
}, function(response) {
  if (response.success) {
    console.log('History cleared');
  }
});

Automatic History Logging

When you export a GTM container:

// In adt-admin-ajax.js
ADTExportHistory.add({
  features: data.featuresIncluded || [],
  mode: data.mode || 'full',
  canUsePremium: data.canUsePremium || false,
  debug: data.debug || false,
  pluginVersion: data.pluginVersion || 'n/a',
  exportId: 'exp_' + Math.random().toString(36).substr(2, 9),
  user: ADTData.currentUser || 'You',
  timestamp: Math.floor(Date.now() / 1000)
});

Skipped in Raw Mode:

• Raw JSON exports (no metadata)
• Malformed payloads
• Debug/test exports

Using History for Rollback

If a recent export causes issues in GTM:

1. Find Previous Export
   • Open Export History
   • Locate the last working export by date
   • Note the features included
2. Re-Export Same Configuration
   • Go to GTM Export tab
   • Select same features as previous export
   • Export again
3. Import to GTM
   • Download the re-export
   • Import to GTM in test workspace
   • Preview and verify
   • Publish when confirmed working
4. Document the Rollback
   • Note which export was problematic
   • Document why rollback was needed
   • Update team on changes

Admin Bar CMP Status Monitor

Purpose

Real-time consent management platform (CMP) status monitoring in the WordPress admin bar.

Display Location

WordPress Admin Bar → ADT CMP Status (top right)

Status Indicators

No CMP Detected

🔍 ADT CMP Status
└─ Platform: No CMP detected
   Checking... (attempts 1/3)

Possible Reasons:

• No CMP plugin installed
• CMP not configured
• CMP JavaScript not loaded yet
• Page loaded too fast (still checking)

CMP Detected – Consent Granted

✅ ADT CMP Status
└─ Platform: OneTrust
   Analytics: Granted ✅
   Marketing: Granted ✅
   ADT Integration: Active ✅

CMP Detected – Consent Denied

⚠️ ADT CMP Status
└─ Platform: Cookiebot
   Analytics: Denied ❌
   Marketing: Denied ❌
   ADT Integration: Blocking Events 🚫

CMP Detected – Partial Consent

ℹ️ ADT CMP Status
└─ Platform: CookieYes
   Analytics: Granted ✅
   Marketing: Denied ❌
   ADT Integration: Partial ⚠️

Technical Details

Detection Method

// Frontend JavaScript check
(function() {
    const infoEl = document.getElementById('adt-cmp-info');
    if (!infoEl) return;
    
    let attempts = 0;
    const maxAttempts = 3;
    
    function checkCMP() {
        attempts++;
        const detected = window.ADTConsent?.detectAllCMPs?.() || ['No CMP detected'];
        
        let html = '<div class="cmp-status">';
        html += '<div class="label">Platform:</div>';
        html += '<div class="value">' + detected[0] + '</div>';
        
        if (detected[0] !== 'No CMP detected') {
            const status = window.ADTConsent?.getConsentStatus?.();
            html += '<div class="label">Analytics:</div>';
            html += '<div class="value">' + (status?.analytics ? '✅ Granted' : '❌ Denied') + '</div>';
            html += '<div class="label">Marketing:</div>';
            html += '<div class="value">' + (status?.marketing ? '✅ Granted' : '❌ Denied') + '</div>';
            
            if (window.ADTData) {
                html += '<div class="label">ADT Integration:</div>';
                const integrationStatus = status?.analytics && status?.marketing ? 'Active ✅' : 
                                         status?.analytics || status?.marketing ? 'Partial ⚠️' : 'Blocking 🚫';
                html += '<div class="value">' + integrationStatus + '</div>';
            }
        }
        
        html += '</div>';
        infoEl.innerHTML = html;
        
        if (detected[0] === 'No CMP detected' && attempts < maxAttempts) {
            setTimeout(checkCMP, 500);
        }
    }
    
    setTimeout(checkCMP, 1000);
})();

Supported CMPs

The monitor detects:

• OneTrust
• Cookiebot
• CookieYes
• Complianz
• Cookie Notice
• GDPR Cookie Consent
• Termly
• iubenda
• Any TCF 2.0 compliant CMP

Configuration

Enable/Disable Monitor

Settings → Advanced DataLayer → Consent tab
→ Show CMP Status in Admin Bar: [✓]

Minimum Role to See Monitor

Settings → Advanced DataLayer → Debug tab
→ Admin Bar CMP Monitor Minimum Role: [Administrator ▼]

Role Options:

• Subscriber (all logged-in users)
• Contributor
• Author
• Editor
• Administrator (default)

Troubleshooting CMP Integration

If monitor shows issues:

Problem: “No CMP detected” but CMP is installed

Solution:

1. Check CMP plugin is active
2. Verify CMP scripts load on frontend
3. Check browser console for CMP object: console.log(window.OneTrust);console.log(window.Cookiebot);
4. Ensure CMP initializes before ADT

Problem: “Consent Denied” but you accepted cookies

Solution:

1. Clear browser cookies
2. Reload page
3. Accept consent again
4. Check if consent persists across pageloads

Problem: ADT events still blocked despite consent

Solution:

1. Check Settings → Consent configuration
2. Verify CMP platform selected correctly: Preferred CMP: [Auto-detect ▼]
3. Enable debug mode to see consent checks: console.log('Consent Status:', window.ADTConsent.getConsentStatus());console.log('Should Block:', window.dataLayerBlocked);

Troubleshooting Guide

Common Issues & Solutions

Issue 1: Settings Not Saving

Symptoms:

• Click “Save Changes” but values don’t persist
• Checkboxes revert to previous state
• Error message: “Failed to save settings”

Diagnosis:

1. Check browser console for JavaScript errors
2. Look for AJAX errors (403 Forbidden, 500 Internal Server Error)
3. Verify nonce is present in form: console.log(document.querySelector('input[name="_wpnonce"]').value);

Solutions:

1. Nonce expired:
   • Refresh the settings page
   • Save again immediately
2. Permission issue:
   • Verify you’re logged in as Administrator
   • Check: current_user_can('manage_options')
3. Validation failing:
   • Enable debug mode
   • Check PHP error log for validation messages
   • Look for rejected values in adt_validate_settings()
4. Database locked:
   • Check hosting resource limits
   • Verify MySQL is not hitting connection limits
   • Temporarily disable other plugins that write heavily

Issue 2: Orphaned Fields Won’t Go Away

Symptoms:

• Clean up orphaned fields
• Success message appears
• Run debug again, same fields reappear

Diagnosis:

1. Run Field Debug Tool
2. Check if field is in “safety-net” whitelist
3. Search codebase for field name: grep -r "field_name" /wp-content/plugins/advanced-datalayer-tracker/

Solutions:

1. Field in adt_get_default_settings():
   • File: includes/adt-settings-register.php
   • Remove from defaults array
2. Field in validation function:
   • File: admin/adt-settings-functions.php
   • Function: adt_validate_settings()
   • Remove logic that re-adds the field
3. Field hardcoded in frontend:
   • File: includes/adt-frontend-config.php
   • Remove references
4. Field in $field_map:
   • File: admin/adt-settings-fields.php
   • Remove from appropriate section

Complete Removal Checklist:

• [ ] Remove from $field_map
• [ ] Remove from adt_get_default_settings()
• [ ] Remove from adt-frontend-config.php
• [ ] Remove from validation function
• [ ] Run cleanup tool
• [ ] Verify removal in Field Debug

Issue 3: Debug Overlay Not Showing

Symptoms:

• “Enable Debug Overlay” is checked
• Premium license active
• Overlay doesn’t appear on frontend

Diagnosis:

1. Check settings: Settings → General → Enable Debug Overlay: [✓] Settings → General → Show Debug Overlay to Me: [✓]
2. Verify user role meets minimum: Settings → Debug → Debug Overlay Minimum Role: [Administrator ▼]
3. Check browser console: console.log(window.ADTDebugOverlay);

Solutions:

1. Page cache interfering:
   • Overlay uses dynamic content
   • Cache serves static HTML without overlay
   • Solution: Plugin automatically bypasses cache for admins
   • Verify: Check for DONOTCACHEPAGE constant
2. JavaScript not loading:
   • Check Network tab for 404 errors
   • Verify file exists: /assets/js/adt-debug-overlay-core.js
   • Clear browser cache (Ctrl+Shift+R)
3. CSS conflict:
   • Overlay has z-index: 999999
   • Another element may be blocking it
   • Inspect element and look for higher z-index
   • Temporarily add: .adt-debug-overlay { z-index: 9999999 !important; }
4. Premium check failing:
   • Run: echo user_is_premium() ? 'Yes' : 'No';
   • If “No” despite license, contact support
   • Check Freemius connection

Issue 4: Export History Not Recording

Symptoms:

• Export GTM container successfully
• Check Export History
• No new entry appears

Diagnosis:

1. Check if export was in “raw mode” (history skipped for raw)
2. Look for JavaScript errors in browser console
3. Verify AJAX endpoint responding: jQuery.post(ajaxurl, { action: 'adt_get_export_history', security: ADTData.nonce}, console.log);

Solutions:

1. Raw mode export:
   • By design, raw exports don’t log to history
   • Use “Full Export” or “Selected Features” mode instead
2. AJAX blocked:
   • Check for CORS errors
   • Verify ajaxurl is defined: console.log(typeof ajaxurl);
   • Check server firewall rules
3. Storage limit reached:
   • History stores max 50 exports per user
   • Oldest automatically removed
   • Clear history and try again
4. User meta not saving:
   • Check database permissions
   • Verify: SELECT * FROM wp_usermeta WHERE meta_key = 'adt_export_history';
   • If empty, database write issue

Issue 5: Cache Not Clearing After Settings Save

Symptoms:

• Change settings, click save
• Frontend still shows old behavior
• Refresh multiple times, no change

Diagnosis:

1. Check which cache plugin is active
2. Verify plugin function exists: var_dump(function_exists('rocket_clean_domain'));
3. Check if cache actually cleared:
   • Visit your cache plugin’s settings
   • Look for “Last Cleared” timestamp

Solutions:

1. Unsupported cache plugin:
   • Manually clear cache from plugin settings
   • Request support for your cache plugin
   • Use alternative cache plugin
2. Server-level cache:
   • Varnish, Nginx FastCGI cache
   • Plugin can’t clear server cache
   • Must clear manually or via hosting panel
3. CDN cache:
   • Cloudflare, Sucuri, etc.
   • CDN serves cached files
   • Must purge CDN separately:
     • Cloudflare: Dashboard → Caching → Purge Everything
     • Sucuri: Dashboard → Firewall → Clear Cache
4. Object cache persistent:
   • Redis, Memcached
   • May require server restart
   • Or: wp cache flush via WP-CLI

Nuclear Option:

// Add to wp-config.php temporarily
define('WP_CACHE', false);

Reload page, then re-enable after testing.

Best Practices

1. Regular Maintenance

Monthly Tasks

• [ ] Review orphaned fields
• [ ] Clean up if any found
• [ ] Check export history for unusual patterns
• [ ] Verify cache clearing works after settings changes

Quarterly Tasks

• [ ] Export settings as backup JSON
• [ ] Review Field Debug report for inconsistencies
• [ ] Update documentation with any custom fields added
• [ ] Audit enabled features vs. actual usage

Before Major Updates

• [ ] Export current settings
• [ ] Document current configuration
• [ ] Note any customizations
• [ ] Run full Field Debug report
• [ ] Save Export History as JSON

2. Documentation Standards

Keep an internal document with:

## ADT Configuration - [Your Site Name]

### Enabled Features
- Page View Tracking: ✓
- E-Commerce Tracking: ✓
- Form Tracking: ✓
- Video Tracking: ✗

### Custom Fields Added
- `custom_tracking_id`: For legacy analytics ID
- `old_pixel_id`: Deprecated, remove after Q2 2025

### Known Issues
- Debug overlay flickers on mobile Safari (investigating)
- WP Rocket cache requires manual clear occasionally

### Contact
- Primary Admin: john@example.com
- Backup Admin: sarah@example.com
- Last Updated: 2025-10-22

3. Safe Configuration Changes

When modifying settings:

1. Always export first: Settings → Import/Export → Export Settings
2. Test in staging if available:
   • Apply changes to staging site
   • Test for 24-48 hours
   • Monitor for errors
   • Deploy to production
3. Change one thing at a time:
   • Don’t change 10 settings simultaneously
   • If issues arise, hard to diagnose
4. Document the change:
   • What was changed
   • Why it was changed
   • Expected outcome
   • Actual outcome
5. Monitor after changes:
   • Check browser console for errors
   • Verify events still firing (GTM Preview)
   • Review GA4 real-time reports
   • Confirm no broken functionality

4. Troubleshooting Workflow

When issues occur:

1. Identify the problem
   ↓
2. Run Field Debug Tool
   ↓
3. Check Settings Diagnostic
   ↓
4. Review browser console
   ↓
5. Check PHP error log
   ↓
6. Attempt solution
   ↓
7. Test and verify
   ↓
8. Document for future

5. Security Practices

Admin Access

• Only grant manage_options capability to trusted users
• Use strong passwords
• Enable 2FA on WordPress accounts
• Regularly review user list

Sensitive Data

• Don’t store API keys in settings if avoidable
• Use environment variables for credentials
• Regularly rotate access tokens
• Audit who has admin access

Backup Strategy

• Export settings monthly
• Keep last 3 exports
• Store off-site (Google Drive, Dropbox)
• Test restoration process annually

6. Performance Optimization

Minimize Database Queries

• Don’t call adt_get_settings() repeatedly in loops
• Cache results in variables
• Use transients for expensive operations

Asset Loading

• Only load debug overlay JS for admins
• Lazy load heavy features
• Use conditional script enqueuing

Cache Strategy

• Test different cache plugins for compatibility
• Use object caching (Redis) if available
• Set appropriate cache TTLs

7. Working with Developers

When requesting developer help:

Always provide:

1. Export of current settings
2. Field Debug report output
3. Browser console errors (screenshot)
4. PHP error log entries
5. Description of what you expected vs. what happened

Example Request:

Subject: Debug Overlay Not Appearing

Environment:
- WordPress: 6.4.2
- ADT Plugin: 2.0.5
- License: Premium
- Cache: WP Rocket 3.15

Issue:
Debug overlay not showing on frontend despite being enabled.

Steps Taken:
1. Verified "Enable Debug Overlay" checked
2. Verified "Show Debug Overlay" checked
3. Cleared WP Rocket cache
4. Tested in incognito mode
5. Checked browser console - no errors

Attachments:
- settings-export.json
- field-debug-report.txt
- console-screenshot.png

8. Staying Updated

Monitor Plugin Updates

• Subscribe to plugin changelog
• Read update notes before upgrading
• Test updates in staging first

Follow Best Practices Evolution

• Check plugin docs quarterly
• Join user community/forum
• Share your learnings with others

Summary

The Advanced DataLayer Tracker Admin Tools provide powerful utilities for:

✅ Debugging field mappings to ensure form integrations work correctly
✅ Diagnosing settings issues with detailed reports and orphaned field detection
✅ Resetting configurations safely when needed with comprehensive cache clearing
✅ Managing export history for version control and rollback capability
✅ Monitoring consent status in real-time via the admin bar

Key Takeaways:

1. Run Field Debug regularly to catch orphaned fields early
2. Only use Reset to Defaults when truly necessary – it cannot be undone
3. Keep export history for rollback capability
4. Document your configuration before major changes
5. Clear cache properly to ensure settings take effect
6. Monitor CMP status to ensure compliance and proper tracking

When to Use Each Tool:

Tool	Use When	Frequency
Field Debug	After plugin updates, troubleshooting forms	Monthly or as needed
Settings Diagnostic	Settings page blank or not loading	Troubleshooting only
Reset to Defaults	Settings corrupted, starting fresh	Rarely (emergency)
Clean Orphaned Fields	Orphaned fields detected	As needed
Export History	Checking past configurations	Before major changes
CMP Status Monitor	Verifying consent integration	Ongoing (automatic)

Support Resources:

• Plugin Documentation:
• Support Forum:
• Priority Support:
• GitHub Issues:

Last Updated: October 22, 2025 Plugin Version: 2.0+ Document Version: 1.0