This is the value of utm_campaign: ${cmp_value}
` jQuery('.dynamic_content_class').html(my_html) } ``` # Differentiate whether Paid / Organic / Direct / Referral As of v3.0.36, there is a new cookie named `traffic_source`. Even if you do not use any query arguments (e.g., utm\_ params) in your link, we can accurately identify the traffic source based on various signals. This cookie enables you to capture the source of traffic, whether it's paid, organic, direct, referral, or other forms. - Paid: Traffic originating from Google or Facebook ads. - Social: Traffic originating from social platforms such as Facebook, Twitter, Instagram, Snapchat, YouTube, Pinterest, LinkedIn, and Tumblr organically. - Organic: Traffic originating from a search using Google or Bing. - Direct: Traffic coming directly from a bookmark or the address bar. - Referral: All other referrals not captured above. - Other: Any other traffic not categorized by the rules above. In order to capture `traffic_source` information in your forms, you may have to add `traffic_source` as custom parameters in UTM. See [How to add custom parameters?](https://docs.utmgrabber.com/books/102-getting-started-for-handl-utm-grabber-v3/chapter/how-to-add-custom-parameters) `traffic_source` is a last-touch attribute. If you want the first-touch version of this parameter, use `first_traffic_source`. # What is the difference between all the handl params? ``` [handl_original_ref] - original referral - first touch! [handl_landing_page] - landing page - first touch! [handl_ref] - last touch referral [handl_url] - last touch url ``` Let's say you have a link to your website from google.com to domain.com/page1 And user click from Google, he/she lands on page1 and after that they go to page2 to convert So it is like Google -> Page1 -> Page2 (Conversion) The params will populate the following data: handl\_original\_ref = Google.com handl\_landing\_page = domain.com/page1 handl\_ref = domain.com/page1 handl\_url = domain.com/page2 # Can't activate the license - Not Found If you encounter an error like this: [](https://docs.utmgrabber.com/uploads/images/gallery/2023-11/image-1699492564547.png) And have WPCodeBox 2 installed, please try disabling that plugin and then reactivate the license. [](https://docs.utmgrabber.com/uploads/images/gallery/2023-11/image-1699492588430.png) # Facebook Conversion API (FB CAPI) As of HandL UTM Grabber v3.1, we have started supporting the Facebook Conversion API on the following plugins. Please bookmark this page as we add new support every day. ### Send Events from WooCommerce to Facebook Ads We currently send AddToCart, InitiateCheckout, AddPaymentInfo, and Purchase events. Please refer to [these instructions](https://docs.utmgrabber.com/books/woocommerce-integration/page/woocommerce-to-facebook-conversion-api-fb-capi-v31) for setup details. ### Send Lead Events from Gravity Forms to Facebook Ads ### Send Lead Events from Contact Form 7 to Facebook Ads ### Send Lead Events from Ninja Forms to Facebook Ads # Tracking conversion start time, end time, and duration Using our custom version, you can track the start time, end time, and duration of your conversions. Please request the custom version via chat, and we'll provide it to you. After you activate the custom version, you will have three additional cookies (parameters) added: 1. **Tracking conversion start time, end time, and duration:** - **handl\_journey\_start:** This is an [epoch](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/now) timestamp in milliseconds indicating when the user started the journey for the first time. - **handl\_journey\_end:** This is an [epoch](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/now) timestamp in milliseconds indicating when the user ended the journey for the first time. - **handl\_journey\_duration\_hrs:** This is the duration of the conversion in hours (rounded). Please let us know if you have any further questions. # No License Key Field Appears in WP Admin > Plugins When you click "License" and no license field appears, or if you see the console log print a "javascript:void()" error message, follow these steps in your browser to make the field visible: 1. Navigate to WP Admin > Plugins > HandL UTM Grabber v3. 2. Right-click on "License" and select "Inspect Element." 3. Once you are there, locate the class shown in the image and remove "display: none." 4. This action will make the license field appear.  # Define Your Own Custom Logic ## Introduction The "Define Your Own" feature in HandL UTM Grabber v3 allows you to create custom logic for tracking and manipulating UTM parameters and other tracked fields. This powerful tool enables you to define conditional rules that create new parameters based on existing ones, giving you more control over your tracking and marketing efforts. ## When to Use This Feature Use the "Define Your Own" feature when you need to: 1. Create new parameters based on existing UTM parameters or tracked fields. 2. Implement complex tracking logic specific to your marketing campaigns. 3. Customize parameter values based on certain conditions. 4. Enhance your analytics by creating more detailed or specific tracking parameters. ## How to Access the Feature 1. Log in to your WordPress admin panel. 2. Navigate to the HandL UTM Grabber settings. 3. Click on the "Define Your Own" tab in the settings menu. ## Features and Functionality ### Creating Custom Logic The "Define Your Own" tab allows you to create multiple custom logic rules. Each rule consists of: 1. A condition based on an existing parameter 2. A new parameter to be created when the condition is met ### Available Fields The feature uses all fields generated by HandL UTM Grabber These fields include [standard UTM parameters and additional tracked](https://docs.utmgrabber.com/books/102-getting-started-for-handl-utm-grabber-v3/page/native-wp-shortcodes) fields provided by the HandL UTM Grabber plugin. [](https://docs.utmgrabber.com/uploads/images/gallery/2024-10/image-1728054965180.png) ### Operators You can use various operators to define your conditions: [](https://docs.utmgrabber.com/uploads/images/gallery/2024-10/image-1728054999789.png) These operators allow for precise control over when your custom logic should be applied. ## How to Use the Feature - In the "Define Your Own" tab, you'll see a table where you can add custom logic rules. 2. For each rule, follow these steps: a. Select the parameter you want to base your condition on from the first dropdown. b. Choose an operator from the second dropdown to define how you want to compare the parameter's value. c. Enter the value you want to compare against in the text field. d. In the "Then set" section, enter a name for your new parameter. e. Enter the value you want to assign to this new parameter when the condition is met. - You can add multiple rules by filling out additional rows in the table. - Click the "Save Changes" button to apply your custom logic rules. [](https://docs.utmgrabber.com/uploads/images/gallery/2024-10/image-1728055039749.png) ## Examples 1. **Campaign Source Tracking:** - If `utm_source` equals "facebook" - Then set "social\_campaign" = "fb\_promo" or - If `utm_source` equals "facebook" - Then set "phone\_number" = "999-99-99" 2. **Content Type Flagging:** - If `utm_content` contains "video" - Then set "content\_type" = "video\_ad" 3. **Specific Campaign Tracking:** - If `utm_campaign` starts\_with "summer2023" - Then set "seasonal\_campaign" = "summer\_promo" 4. **Excluding Certain Traffic:** - If `referrer` not\_contains "ourpartner.com" - Then set "non\_partner\_traffic" = "true" 5. **Advanced Regex Matching:** - If `utm_term` matches regex "^(red|blue|green)product$" - Then set "color\_category" = "primary\_colors" ## How It Works When a visitor comes to your site, the HandL UTM Grabber plugin checks these custom logic rules. If a condition is met, it creates a new cookie with the specified parameter name and value. This information is then available for your analytics tools and can be used in your marketing workflows. ## Best Practices 1. Use meaningful names for your new parameters to ensure they're easily understood in your analytics. 2. Be cautious with regex operations, as they can be more resource-intensive. 3. Regularly review your custom logic to ensure it's still relevant to your current marketing strategies. 4. Test your logic thoroughly to make sure it's working as expected. ## Limitations - The custom logic is evaluated when the page loads, so it won't react to changes in UTM parameters without a page refresh. - Be mindful of creating too many custom parameters, as this can lead to cookie bloat and potentially impact site performance. ## Troubleshooting If your custom logic isn't working as expected: - Check that the parameter you're basing your condition on is being correctly set. - Verify that your condition values are correct and watch for typos. - Use your browser's developer tools to check if the new cookies are being set correctly. - Ensure that your site visitors have consented to cookies if you're using GDPR compliance features. By leveraging the "Define Your Own" feature, you can create a more tailored and powerful tracking solution that meets your specific marketing and analytics needs. This flexibility allows you to extract more value from your UTM parameters and other tracked fields, leading to more insightful data for your marketing decisions. # Enforce Consent From 3rd Party (e.g. GTM) ## Overview The "Enforce Consent From 3rd Party" feature allows HandL UTM Grabber to respect consent decisions made through third-party consent management platforms, such as Google Tag Manager (GTM). When enabled, this feature ensures that HandL UTM Grabber only collects and stores data after receiving proper consent from the user, as determined by the third-party consent management system. ## Enabling the Feature To enable this feature: - Navigate to your WordPress admin panel. - Go to the HandL UTM Grabber settings page. - Find the "Require Third-Party Consent" option. - Check the box next to "Require consent from third-party services (e.g., Google Tag Manager) before tracking". - Save your changes. The relevant setting can be found here: [](https://docs.utmgrabber.com/uploads/images/gallery/2024-10/image-1728225846990.png) ## How It Works Once enabled, HandL UTM Grabber will: - Monitor the dataLayer for consent update events. - Check the consent status before running its tracking functions. - Remove HandL cookies if consent is denied. The main logic for this feature is implemented in the following JavaScript functions: ```javascript isConsentDenied(); removeHandLCookies(); ``` You may use these functions as you see fit in your project. The `isConsentDenied()` function returns a Boolean value indicating whether consent is denied. The `removeHandLCookies()` function removes all HandL-related cookies (e.g., when consent is denied). ### Consent Status Check The plugin checks for consent using the `getConsentStatus()` and `isConsentDenied()` functions. These functions look for consent information in the `dataLayer` object, which is commonly used by consent management platforms. ### Handling Consent Changes When a consent update is detected, the `handleConsentStatus()` function is called. This function either runs HandL UTM Grabber's tracking (if consent is granted) or removes HandL cookies (if consent is denied). ## Integration with Google Tag Manager (GTM) To use this feature with Google Tag Manager: - Set up your consent management platform in GTM. You can use any 3rd party tool (CookieHub, Cookiebot etc) - Ensure that your consent management platform is updating the dataLayer with consent information. (According to GTM's best practises) - HandL UTM Grabber will automatically detect these updates and act accordingly. ## Compatibility This feature is designed to work with various consent management platforms that use the dataLayer to communicate consent status. It has been tested with Google Tag Manager but should be compatible with other similar systems. ## Troubleshooting If you're experiencing issues with this feature: - Ensure that your consent management platform is correctly updating the dataLayer. - Check your browser's console for any error messages related to HandL UTM Grabber. - Verify that the "Require Third-Party Consent" option is enabled in the HandL UTM Grabber settings. ## Important Notes - This feature relies on the presence and proper configuration of a third-party consent management system. - If no consent information is found in the dataLayer, HandL UTM Grabber will default to its standard behavior. - Enabling this feature may impact data collection if users do not provide consent. By implementing this feature, you're taking an important step towards respecting user privacy and complying with data protection regulations. # Full Tracking Mode ## Overview The Full Tracking Mode is a powerful feature of the HandL UTM Grabber plugin that allows you to track detailed user journeys across your website. When enabled, it captures data on every page visit for each session, providing insights similar to Google Analytics 4 (GA4). ## Enabling Full Tracking Mode 1. Navigate to the HandL UTM Grabber settings in your WordPress admin panel. 2. Look for the "Full Tracking Mode Settings" section. 3. Check the box labeled "Enable Full Tracking Mode". 4. Save your changes. [](https://docs.utmgrabber.com/uploads/images/gallery/2024-10/image-1729135618669.png) ## What Data is Collected When Full Tracking Mode is enabled, the plugin collects the following data for each page visit: - Session ID - Timestamp - Page URL - Referrer URL - UTM parameters (source, medium, campaign, content, term) This data is stored in three main tables in your WordPress database: - `handl_sessions`: Stores unique session information - `handl_utm_sets`: Stores unique combinations of UTM parameters - `handl_page_views`: Stores individual page view data ## Viewing Reports ### To access the Full Tracking Mode reports: 1. Go to the HandL UTM Grabber menu in your WordPress admin panel. 2. Click on the "Full Tracking Report" tab. The report page offers several features: #### Filters You can filter the data by: - Date range - Page URL - Session ID [](https://docs.utmgrabber.com/uploads/images/gallery/2024-10/image-1729135652920.png) #### Session Counts by Page This section shows: - Page URL - Number of unique sessions - Total visits You can drill down into each page to see a breakdown of UTM parameters and referrers. [](https://docs.utmgrabber.com/uploads/images/gallery/2024-10/image-1729135687779.png) #### User Journey This section displays: - Session ID - Number of unique sessions - Total visits You can drill down into each session to see detailed information about the pages visited and UTM parameters used. [](https://docs.utmgrabber.com/uploads/images/gallery/2024-10/image-1729135721731.png) #### Exporting Data You can export the collected data to a CSV file for further analysis: 1. Apply any desired filters. 2. Click the "Export to CSV" button. ## Database Management As Full Tracking Mode collects a significant amount of data, it's important to manage your database effectively: ### Viewing Database Statistics The "Danger Zone" section of the report page shows the current number of rows in each tracking table. ### Resetting Tracking Data If the database becomes overwhelming or you need to start fresh: 1. Scroll to the "Danger Zone" section at the bottom of the report page. 2. Click the "Remove Tracking Tables" button. 3. Confirm your action in the popup dialog. This action will delete all collected tracking data and cannot be undone. [](https://docs.utmgrabber.com/uploads/images/gallery/2024-10/image-1729135758078.png) ## Important Considerations 1. **Database Size:** Full Tracking Mode will increase your database size. Monitor your database usage regularly. 2. **Performance:** While designed to be efficient, tracking every page visit may have a slight impact on site performance. Monitor your site's performance after enabling this feature. 3. **Privacy:** Ensure that your privacy policy reflects the additional data being collected when Full Tracking Mode is enabled. 4. **Compliance:** Make sure you're compliant with relevant data protection regulations (e.g., GDPR, CCPA) when using this feature. ## Conclusion Full Tracking Mode transforms HandL UTM Grabber into a powerful analytics tool, providing detailed insights into user behavior on your website. Use this data to optimize your marketing strategies, improve user experience, and drive conversions. # Auto-Populate Source/Medium Documentation ## Overview The Auto-Populate Source/Medium feature automatically sets utm\_source and utm\_medium parameters based on the detected traffic source and organic source string. This is particularly useful for tracking organic and referral traffic without manually setting UTM parameters. ## How It Works ### Server-Side Tracking When enabled, the plugin will: Set utm\_source to the value of organic\_source\_str cookie Set utm\_medium to the value of traffic\_source cookie ### Client-Side Tracking The traffic source is determined as follows: Paid: When fbclid, gclid, or msclkid parameters are present Organic: Traffic from search engines (Google, Bing, Yahoo, DuckDuckGo) Social: Traffic from social media platforms (Facebook, Twitter, Instagram, etc.) Direct: When no referrer is present or internal traffic Referral: All other external traffic sources ## Configuration ### Admin Settings The feature can be enabled/disabled through the HandL UTM Grabber settings page under the "Options" tab. [](https://docs.utmgrabber.com/uploads/images/gallery/2024-10/image-1730250436629.png) ### Value Mapping Traffic sources are mapped as follows: utm\_medium will be set to one of: Paid Organic Social Direct Referral Other utm\_source will be set to the specific source: Google Bing Yahoo Facebook Twitter Instagram Direct Internal etc. ## Usage Examples ### Tracking Organic Search Traffic When a visitor comes from Google search: utm\_medium = "Organic" utm\_source = "Google" ### Tracking Social Media Traffic When a visitor comes from Facebook: utm\_medium = "Social" utm\_source = "Facebook" ### Tracking Referral Traffic When a visitor comes from a blog that linked to your site: utm\_medium = "Referral" utm\_source = \[referring domain\] ## Important Notes The feature only sets UTM parameters if they're not already present Values are stored in cookies for consistent tracking across sessions Respects GDPR settings and cookie consent Works with both server-side and client-side tracking Compatible with the plugin's custom parameter feature ## Troubleshooting If UTM parameters are not being set: Verify the feature is enabled in settings Check if cookie consent is required and granted Verify no conflicting UTM parameters are present in URLs # Implementing Custom Consent Management with HandL UTM Grabber Plugin To integrate your custom consent management system with the HandL UTM Grabber plugin, follow these steps: 1. Check for Consent Status: Determine if the user has given consent. 2. Run HandL UTM Grabber: If consent is given, call the RunHandL() function. 3. Remove Cookies: If consent is not given, call the removeAllHandLCookies() function. Here is an example implementation using JavaScript: ``` window.addEventListener('ConsentUpdated', function() { if (typeof ConsentTool !== 'undefined') { const consentString = Cookies.get('CookiesForConsentData'); // Assuming consent data is available in cookies or as an event const consentData = parseConsentString(consentString); if (consentData.good2go === 1) { RunHandL(); } else { removeAllHandLCookies(); } } }); function parseConsentString(consentString) { // Parse the consent string to extract consent data // This is a placeholder function, implement the actual parsing logic as needed return { good2go: consentString.includes('good2go=1') ? 1 : 0 }; } ``` ### Explanation 1. Event Listener: The window.addEventListener listens for a custom event CustomConsentUpdated which is triggered by your consent management system. 2. Check Consent Management System: Ensure that the custom consent management system is available. 3. Get Consent Status: Retrieve the consent status from event or cookies. 4. Run or Remove Cookies: Depending on the consent status, either run the RunHandL() function or call removeAllHandLCookies() to remove all cookies # Enable Session Cookies ## Overview The Enable Session Cookies feature allows you to control how long cookies persist in users' browsers. When enabled, cookies will expire when the browser session ends instead of after a set number of days. ## Location This setting can be found in the HandL UTM Grabber settings page under the "HandL Options" tab. [](https://docs.utmgrabber.com/uploads/images/gallery/2025-01/image-1737602486773.png) ### Options - Enable Session Cookies: When checked, all cookies will be set as session cookies - Cookie Duration: This field becomes disabled when session cookies are enabled ## Behavior ### When Disabled (Default) - Cookies persist for the number of days specified in the "Cookie Duration" field - Default duration is 30 days if not specified - Cookie Duration field is enabled and editable ### When Enabled - Cookies expire when the browser session ends - Cookie Duration field is automatically disabled - A notice appears explaining that cookies will expire with the browser session ## Use Cases - Compliance Requirements - Some privacy regulations require session-only cookies - Useful for sites needing stricter cookie policies - Testing and Development - Helps debug tracking issues by clearing cookies on browser close - Useful for testing first-visit vs returning visitor scenarios - User Privacy - Provides users with enhanced privacy by not storing long-term cookies - Cookies are automatically cleared when browser closes ## Compatibility The session cookies feature works with all major plugin features including: - UTM parameter tracking - Form field population - GDPR compliance features - Integration with other tracking systems ## Notes - This setting affects all cookies set by the plugin - The setting can be changed at any time without affecting existing cookies - Existing cookies will retain their original expiration until they are updated - Works in conjunction with GDPR compliance features if enabled # Disable Server Side Tracking The "Disable Server Side Tracking" feature allows users to disable server-side tracking if they believe it is adversely impacting their tracking due to server-side caching. This feature ensures that tracking relies solely on client-side tracking. Clicking the checkbox will disable the server side tracking [](https://docs.utmgrabber.com/uploads/images/gallery/2025-02/image-1738796517904.png) # Phone Tracking (to boost Call Rail etc) ## Overview The Phone Tracking feature allows you to track all phone number clicks (tel: links) on your website along with UTM parameters and other tracking data. This helps you understand which marketing campaigns are driving phone calls to your business. ## Installation The feature is automatically installed as part of the HandL UTM Grabber premium version. The necessary database table is created automatically when the plugin is activated. ## Configuration - Navigate to WordPress Admin → UTM → Phone Tracking 2\. Check the "Enable Phone Tracking" checkbox - Click "Save Changes" [](https://docs.utmgrabber.com/uploads/images/gallery/2025-02/image-1740427860517.png) ## Features ### Phone Click Tracking - Automatically tracks clicks on any phone number link (tel:) across your website - Captures all UTM parameters and tracking data at the time of click - Records timestamp and phone number for each click - Works with any phone number format using tel: protocol ### Reporting Interface - View all phone clicks in a tabulated format - See key UTM parameters (source, medium, campaign) - View original referrer information - Access detailed tracking data for each click [](https://docs.utmgrabber.com/uploads/images/gallery/2025-02/image-1740447795137.png) ### Search and Filter - Search by phone number - Filter by date range - Results update in real-time - Pagination for large datasets ### Data Export - Export all tracking data to CSV - Includes timestamp, phone number, and all tracking parameters - Compatible with spreadsheet software ### Data Management - Clear all tracking data with one click - Confirmation prompt before deletion - Maintains data integrity with proper database operations ## Technical Details ### Tracked Parameters - UTM Source - UTM Medium - UTM Campaign - Original Referrer - Landing Page - All other UTM parameters - Custom tracking parameters ## Usage Tips - Enable the feature before starting any phone campaign - Use tel: links for all phone numbers you want to track 3\. Export data regularly for backup and analysis - Clear old data periodically to maintain performance - Use date filters for campaign-specific analysis ## Troubleshooting If phone clicks aren't being tracked: - Verify the feature is enabled - Ensure phone numbers use tel: protocol - Check browser console for JavaScript errors - Verify WordPress AJAX URL is accessible - Confirm user permissions are correct ## Best Practices - Use consistent phone number formats - Implement regular data exports - Clean up old data periodically - Monitor tracking data size - Use UTM parameters consistently for better analysis ## Support For additional support or feature requests, contact HandL UTM Grabber support team through the official channels. # GDPR Implementation Guide for HandL UTM Grabber Plugin This documentation provides developers with the necessary information to implement GDPR compliance for the HandL UTM Grabber plugin. ## Overview The HandL UTM Grabber plugin provides two main functions for GDPR compliance: - `RunHandL()` - Starts tracking when consent is given - `RemoveHandLCookies()` - Removes tracking cookies when consent is denied ## Core Functions ### RunHandL() Initiates UTM tracking and cookie setting when user consent is obtained. ```javascript function RunHandL() { // Sets up UTM tracking, cookies, and form field population // Only call this when user has given consent } ``` ### RemoveHandLCookies() Removes all HandL tracking cookies when consent is denied. ```javascript function RemoveHandLCookies() { console.log('Removing HandL cookies'); handl_utm_all_params.forEach(param => { Cookies.remove(param, { path: '/', domain: getDomainName() }); }); } ``` ## Consent Detection Methods The plugin supports multiple consent management platforms and methods: ### 1. Google Tag Manager (GTM) Consent Mode ```javascript function getConsentStatus() { if (!window.dataLayer) { console.warn('dataLayer is not defined.'); return null; } let consent = null; // Iterate through dataLayer in reverse to find the latest consent event for (let i = window.dataLayer.length - 1; i >= 0; i--) { if (window.dataLayer[i][0] === 'consent' && window.dataLayer[i][1] === 'update') { consent = window.dataLayer[i][2]; break; } else if (typeof window.dataLayer[i] === 'object' && window.dataLayer[i].value && window.dataLayer[i].value.event && window.dataLayer[i].value.event.includes('consent')) { consent = window.dataLayer[i].value; break; } } return consent; } function isConsentDenied() { const consentStatus = getConsentStatus(); return consentStatus && (consentStatus.ad_user_data === 'denied' && (consentStatus.analytics_storage === 'denied' || !consentStatus.analytics_storage)); } function handleConsentStatus() { if (isConsentDenied()) { RemoveHandLCookies(); } else { RunHandL(); } } ``` ### 2. Borlabs Cookie ```javascript // Check Borlabs cookie on page load const borlabsCookie = Cookies.get('borlabs-cookie'); if (borlabsCookie) { try { const cookieData = JSON.parse(borlabsCookie); if (cookieData.consents.marketing.includes('handl-utm-grabber')) { console.log("handl-utm-grabber checked by Borlabs.. RunHandL..."); RunHandL(); } else { console.log("handl-utm-grabber not checked by Borlabs"); } } catch (e) { console.error('Error parsing JSON:', e); } } // Listen for Borlabs consent changes window.addEventListener('borlabs-cookie-consent-saved', () => { if (window.BorlabsCookie.Consents.hasConsent('handl-utm-grabber')) { RunHandL(); } }); ``` ### 3. Cookiebot ```javascript window.addEventListener('CookiebotOnAccept', function (e) { if (Cookiebot.consent.marketing) { RunHandL(); } }, false); ``` ### 4. Complianz ```javascript document.addEventListener("cmplz_enable_category", function(consentData) { var category = consentData.detail.category; if (category === 'marketing') { RunHandL(); } }); ``` ### 5. Custom GDPR Implementation For custom consent implementations, you can use the built-in GDPR notice: ```javascript // Set consent cookie Cookies.set("gdprConsent", 1); // 1 for accept, 0 for deny // The plugin will automatically check this cookie and call appropriate functions ``` ## Implementation Examples ### Basic Implementation ```javascript // Check if consent is required if (typeof handl_ajax.require_third_party_consent !== 'undefined' && handl_ajax.require_third_party_consent) { // Monitor dataLayer for consent changes if (!window.dataLayer) { window.dataLayer = []; } const originalPush = window.dataLayer.push; window.dataLayer.push = function(...args) { args.forEach(entry => { if ( (Array.isArray(entry) && entry[0] === 'consent' && entry[1] === 'update') || (entry.event && entry.event.includes('consent')) || (entry.value && entry.value.event && entry.value.event.includes('consent')) ) { handleConsentStatus(); } }); return originalPush.apply(this, args); }; } ``` ### Custom Consent Manager Integration ```javascript // Example for a custom consent manager function checkCustomConsent() { // Your consent checking logic here const hasConsent = yourConsentManager.hasMarketingConsent(); if (hasConsent) { RunHandL(); } else { RemoveHandLCookies(); } } // Call on page load checkCustomConsent(); // Listen for consent changes yourConsentManager.onConsentChange(function(consent) { if (consent.marketing) { RunHandL(); } else { RemoveHandLCookies(); } }); ``` ## Server-Side PHP Integration The plugin also provides server-side consent checking: ```php // Check if consent is given function HandLCookieConsented() { $good2go = apply_filters('is_ok_to_capture_utms', array('good2go' => 1)); return $good2go["good2go"]; } // Use in your code if (HandLCookieConsented()) { // User has given consent, proceed with tracking // Your tracking code here } ``` ## Configuration Options ### WordPress Admin Settings 1. **Enable GDPR**: Shows HandL's built-in consent notice 2. **Require Third-Party Consent**: Requires consent from third-party services (e.g., GTM) before tracking ### JavaScript Variables - `handl_ajax.require_third_party_consent`: Boolean indicating if third-party consent is required - `handl_utm_all_params`: Array of all UTM parameters that will be tracked - `handl_utm_cookie_duration`: Cookie expiration settings ## Best Practices 1. **Always check consent before calling `RunHandL()`** 2. **Call `RemoveHandLCookies()` when consent is denied** 3. **Listen for consent changes and update accordingly** 4. **Test with different consent management platforms** 5. **Ensure your implementation works with the plugin's built-in GDPR features** ## Testing To test your GDPR implementation: 1. Clear all cookies 2. Load the page without consent 3. Verify that `RunHandL()` is not called 4. Give consent through your consent manager 5. Verify that `RunHandL()` is called and cookies are set 6. Revoke consent 7. Verify that `RemoveHandLCookies()` is called and cookies are removed ## Troubleshooting ### Common Issues 1. **Consent not detected**: Ensure your consent manager is properly integrated and firing the correct events 2. **Cookies not removed**: Check that `getDomainName()` returns the correct domain 3. **Multiple consent managers**: Ensure only one consent manager is active to avoid conflicts ### Debug Mode Enable console logging to debug consent issues: ```javascript console.log('Consent status:', getConsentStatus()); console.log('Is consent denied:', isConsentDenied()); console.log('HandL cookies:', handl_utm_all_params); ``` ## Support For additional support or questions about GDPR implementation, refer to the plugin documentation or contact the development team. # MCP (Model Context Protocol) for UTMGrabber Reports ## Overview The MCP feature allows you to connect your WordPress site to AI assistants like **Claude Desktop**, **Cursor**, and **Codex** using the [Model Context Protocol](https://modelcontextprotocol.io/). Once connected, you can query your UTMGrabber reports using natural language directly from any MCP-compatible client. > **Disclaimer:** AI-generated results may be inaccurate or incomplete. Always review before acting on them. For example, you can ask questions like: - "What are the top UTM sources in my submissions?" - "How many leads came from organic traffic?" - "Which campaigns drove the most form submissions?" ## Requirements - HandL UTM Grabber V3 (premium) with an active license key - Starter plus or premium utmgrabber subscription ## Setup ### Step 1: Navigate to the MCP Tab 1. Go to **WordPress Admin > UTM > MCP** You will see the MCP setup screen: [](https://docs.utmgrabber.com/uploads/images/gallery/2026-03/mcp-setup-screen.png) ### Step 2: Connect to MCP 1. Click the **Connect to MCP** button 2. The plugin will automatically register your site using your license key 3. Once connected, you will see your unique MCP URL [](https://docs.utmgrabber.com/uploads/images/gallery/2026-03/mcp-connected.png) ### Step 3: Copy Your MCP URL 1. Your unique MCP URL will be displayed on screen (partially truncated for security) 2. Click the **copy icon** next to the URL to copy the full URL to your clipboard 3. You will see a confirmation toast when the URL is copied > **Important:** This URL contains your secret access code. Treat it like a password. Do not share it publicly or commit it to version control. ### Step 4: Add to Your MCP Client Use the copied URL in your preferred MCP-compatible client: #### Claude Desktop Add to your Claude Desktop configuration file (`claude_desktop_config.json`): ```json { "mcpServers": { "utmgrabber": { "url": "YOUR_MCP_URL_HERE" } } } ``` #### Cursor Add to your Cursor MCP settings (`.cursor/mcp.json`): ```json { "mcpServers": { "utmgrabber": { "url": "YOUR_MCP_URL_HERE" } } } ``` ## Features ### Query UTM Reports with Natural Language Once connected, you can ask your AI assistant questions about your UTMGrabber data. The MCP server exposes the following capabilities: - **Available form plugins** - See which form plugins are detected on your site (e.g. Gravity Forms, WPForms, Fluent Forms) - **List forms** - Browse all forms from a specific plugin - **Get entries** - Fetch form submission entries with UTM data, filtered by date range, form, and plugin ### Secure Communication All communication between the MCP server and your WordPress site is secured using HMAC-SHA256 signed requests. Your site secret is never transmitted after the initial setup. Only the MCP server and your WordPress plugin know the shared secret. ## Managing Your Connection ### Reconnecting If you need to regenerate your MCP credentials (e.g. you suspect the URL was compromised): 1. Click the **Reconnect** button 2. A confirmation dialog will appear warning that this will invalidate your current URL [](https://docs.utmgrabber.com/uploads/images/gallery/2026-03/mcp-reconnect-confirm.png) 3. Click **Reconnect** to confirm 4. A new MCP URL will be generated 5. Update all your MCP clients with the new URL ### Disconnecting To completely revoke MCP access for your site: 1. Click the **Disconnect** button (shown in red) 2. A confirmation dialog will appear [](https://docs.utmgrabber.com/uploads/images/gallery/2026-03/mcp-disconnect-confirm.png) 3. Click **Disconnect** to confirm 4. Your MCP credentials will be revoked immediately 5. Any MCP clients using the old URL will stop working 6. You can reconnect later, but a new URL will be generated ## Troubleshooting ### "Failed to connect to MCP server" - Verify your license key is active and valid - Check that your site URL is accessible from the internet - Ensure your WordPress site is not behind a firewall that blocks outgoing requests ### MCP client can't connect after setup - Make sure you copied the **full** MCP URL (click the copy button, don't copy the truncated text) - Verify the URL is correctly pasted in your MCP client configuration - Restart your MCP client after adding the configuration ### Data is not showing in AI responses - Ensure you have form plugins installed and active (e.g. Gravity Forms, WPForms) - Verify that form submissions exist in the date range you're querying - Check that the form plugin is supported by UTMGrabber ### Connection was working but stopped - Your MCP credentials may have been invalidated. Try clicking **Reconnect** to generate new credentials - Check that your WordPress site is still accessible and the plugin is active ## Best Practices - **Keep your MCP URL secret** - treat it like a password - **Do not share the URL publicly** or commit it to version control - **Reconnect if compromised** - if you suspect your URL has been exposed, click Reconnect immediately to invalidate the old credentials