WordPress.org
Get WordPress

Plugin Directory

Changeset 3397381


Ignore:
Timestamp:
11/17/2025 04:12:43 PM (3 months ago)
Author:
samsonovteamwork
Message:

Ver 1.1.0

Location:
form-attribution-tracking/trunk
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • form-attribution-tracking/trunk/attribution-tracking.php

    r3397162 r3397381  
    22/**
    33 * Plugin Name: Form Attribution Tracking
    4  * Plugin URI: https://wordpress.org/plugin/form-referral-source
     4 * Plugin URI: https://wordpress.org/plugins/form-attribution-tracking/
    55 * Description: Automatically adds permanent hidden referral source fields to forms from Formidable and Fluent Forms
    6  * Version: 1.0.2
     6 * Version: 1.1.0
    77 * Author: Ryan Howard
    88 * Author URI: https://www.ryanhoward.dev
    … …  
    2323
    2424// Define plugin constants
    25 define('ATTRIBUTION_TRACKING_VERSION', '1.0.2');
     25define('ATTRIBUTION_TRACKING_VERSION', '1.1.0');
    2626define('ATTRIBUTION_TRACKING_PLUGIN_FILE', __FILE__);
    2727define('ATTRIBUTION_TRACKING_PLUGIN_DIR', plugin_dir_path(__FILE__));

  • form-attribution-tracking/trunk/readme.md

    r3397162 r3397381  
    44Tags: attribution, tracking, referral, forms
    55Requires at least: 6.0
    6 Tested up to: 6.8.3
     6Tested up to: 6.8
    77Requires PHP: 8.0
    8 Stable tag: 1.0.2
     8Stable tag: 1.1.0
    99License: GPLv2 or later
    1010License URI: https://www.gnu.org/licenses/gpl-2.0.html
    1111
    12 A WordPress plugin that automatically adds permanent hidden fields for referral source tracking to forms from Formidable Forms and Fluent Forms.
    13 
    14 ## Features
    15 
    16 - **Automatic Referral Source Detection**: Intelligently detects visitor sources including:
    17   - UTM parameters (utm_source, utm_medium, utm_campaign)
    18   - Social media platforms (Facebook, Twitter, LinkedIn, etc.)
    19   - Search engines (Google, Bing, Yahoo, etc.)
    20   - Direct traffic
    21   - Custom referrers
    22 
    23 - **Multiple Form Plugin Support**:
    24   - Formidable Forms integration
    25   - Fluent Forms integration
    26   - Modular architecture for easy extension to other form plugins
    27 
    28 - **Smart Persistence**: Uses cookies to maintain original referral source across multiple page visits
    29 
    30 - **Auto-Integration**: Automatically adds referral source fields to new forms
    31 
    32 - **Flexible Configuration**: Customizable field names, cookie duration, and debug options
     12Track the complete customer journey from first click to conversion with comprehensive Google Ads attribution data captured automatically in your WordPress forms.
     13
     14## Overview
     15
     16Form Attribution Tracking is a WordPress plugin that automatically captures and stores complete attribution data from Google Ads campaigns (and other traffic sources) directly in form submissions. This enables you to connect specific leads back to their originating campaigns, keywords, and ads in Google Ads for accurate conversion tracking and ROI measurement.
     17
     18The plugin uses first-touch attribution, meaning it captures the visitor's original traffic source on their first visit and maintains that data through their entire journey until they convert via a form submission.
     19
     20## Key Features
     21
     22### Complete Google Ads Attribution Data
     23
     24Automatically captures 8 attribution fields for every form submission:
     25
     26- **Attribution Source** - Traffic source (google, facebook, direct, etc.)
     27- **Attribution Medium** - Traffic medium (cpc, organic, referral, etc.)
     28- **Attribution Campaign** - Campaign name from utm_campaign
     29- **Attribution Term** - Keyword from utm_term
     30- **Attribution Content** - Ad variation from utm_content
     31- **Google Click ID (GCLID)** - Direct link to the specific Google Ads click
     32- **Landing Page** - The first page the visitor landed on
     33- **First Click Timestamp** - When the visitor first arrived
     34
     35### Google Ads Conversion Tracking
     36
     37The Google Click ID (GCLID) field enables you to:
     38- Import conversions directly back into Google Ads
     39- Connect form submissions to specific ad clicks
     40- Measure true campaign ROI based on actual leads/sales
     41- Track the complete path from ad click to conversion
     42- Attribute conversions to the exact keyword and ad that drove them
     43
     44### Smart Tracking Technology
     45
     46- **First-Touch Attribution** - Captures original source, not last-click
     47- **Cookie Persistence** - Maintains attribution data across multiple sessions (configurable 1-365 days)
     48- **JavaScript + PHP Fallback** - Dual-layer tracking ensures data capture even if JavaScript is disabled
     49- **Dynamic Form Support** - Mutation observer watches for forms loaded via AJAX
     50- **UTM Parameter Detection** - Automatically parses and stores all UTM parameters
     51- **Intelligent Source Categorization** - Recognizes and categorizes traffic from Google, Facebook, LinkedIn, and 15+ other platforms
     52
     53### Universal Form Plugin Support
     54
     55Works seamlessly with:
     56- **Gravity Forms**
     57- **Fluent Forms**
     58- **Formidable Forms**
     59
     60Modular architecture makes it easy to extend to other form plugins.
     61
     62### Comprehensive Admin Dashboard
     63
     64- **Statistics Dashboard** - View submission counts, attribution source distribution, and recent activity
     65- **Form Management** - See which forms have attribution tracking and bulk-add fields to all forms
     66- **Debug Mode** - Browser console logging for troubleshooting
     67- **Flexible Configuration** - Customize cookie duration and auto-add behavior
    3368
    3469## Installation
    3570
    36 1. Upload the plugin files to `/wp-content/plugins/form-attribution-tracking/`
    37 2. Run `composer install --no-dev` in the plugin directory
    38 3. Activate the plugin through the WordPress admin panel
    39 4. Configure settings at **Settings > Form Referral Source**
    40 
    41 ## Requirements
     71### Requirements
    4272
    4373- WordPress 6.0 or higher
    4474- PHP 8.0 or higher
    45 - At least one supported form plugin:
    46   - Formidable Forms
    47   - Fluent Forms
     75- At least one supported form plugin (Gravity Forms, Fluent Forms, or Formidable Forms)
     76
     77### Setup Steps
     78
     791. Upload the plugin files to `/wp-content/plugins/form-attribution-tracking/`
     802. Run `composer install --no-dev` in the plugin directory (if installing from source)
     813. Activate the plugin through the WordPress admin panel
     824. Navigate to **Form Attribution Tracking** in the WordPress admin menu
     835. Configure your settings (recommended: 30-day cookie duration, auto-add enabled)
     846. The plugin will automatically add attribution fields to new forms, or use the "Manage Forms" tab to add fields to existing forms
     85
     86## How It Works
     87
     88### Data Capture Flow
     89
     901. **Visitor Arrives** - When someone visits your site, the JavaScript tracking code immediately captures:
     91    - All UTM parameters from the URL
     92    - Google Click ID (GCLID) if present
     93    - HTTP referrer to determine traffic source
     94    - Current page URL as landing page
     95    - Current timestamp
     96
     972. **Attribution Stored** - All data is packaged as JSON and stored in a first-party cookie with your configured expiration (default 30 days)
     98
     993. **First-Touch Persistence** - If the visitor returns multiple times before converting, the original attribution data is preserved (not overwritten)
     100
     1014. **Form Submission** - When the visitor fills out a form, the tracking code automatically:
     102    - Reads the stored attribution data
     103    - Populates hidden fields in the form
     104    - Submits with the complete attribution chain
     105
     1065. **PHP Fallback** - If JavaScript fails to populate fields, the PHP integration captures attribution server-side before form processing
     107
     108### Integration with Google Ads
     109
     110To enable conversion imports in Google Ads:
     111
     1121. Forms will capture the GCLID parameter automatically from your ad URLs
     1132. Export your form submissions (including attribution fields) as CSV
     1143. In Google Ads, navigate to Tools → Conversions → Uploads
     1154. Create a conversion action using the GCLID field to match conversions
     1165. Upload your leads with timestamps and GCLIDs
     1176. Google Ads will attribute the conversions to the exact campaigns, ad groups, keywords, and ads that generated them
     118
     119This creates a closed feedback loop between your ad spend and actual business results.
     120
     121## Configuration
     122
     123### Settings
     124
     125Access settings via **Form Attribution Tracking → Settings**:
     126
     127- **Auto-add to new forms** - Automatically adds all 8 attribution fields when new forms are created
     128- **Cookie Duration** - How long to preserve first-touch attribution data (1-365 days, default 30)
     129- **Debug Mode** - Enables detailed logging in browser console for troubleshooting
     130
     131### Managing Existing Forms
     132
     133Use the **Manage Forms** tab to:
     134- View all forms and their attribution tracking status
     135- Bulk-add attribution fields to all existing forms with one click
     136- See which forms already have tracking enabled
     137
     138### Statistics
     139
     140The **Statistics** tab provides:
     141- Total submissions tracked across all forms
     142- Breakdown of traffic sources (Google, Facebook, Direct, etc.)
     143- Recent form submissions with their attribution data
     144- Forms-with-tracking count
    48145
    49146## Usage
    50147
    51 ### Automatic Setup
    52 The plugin automatically adds referral source fields to new forms when enabled in settings.
    53 
    54 ### Manual Setup
    55 1. Go to **Settings > Form Referral Source**
    56 2. Use the "Integrations" tab to add referral source fields to all existing forms
    57 3. Use the "Forms" tab to check which forms have referral source fields
    58 
    59 ### JavaScript API
    60 The plugin exposes a JavaScript API for advanced usage:
     148### For Marketers
     149
     150Once installed and configured, the plugin works automatically. Every form submission will include complete attribution data that you can:
     151
     152- Export to CSV and upload to Google Ads for conversion tracking
     153- Analyze in your CRM to understand which campaigns drive the best leads
     154- Use to calculate true cost-per-lead and ROI by campaign
     155- Review to optimize your landing pages and ad targeting
     156
     157### For Developers
     158
     159#### JavaScript API
     160
     161The plugin exposes a global API for programmatic access:
    61162
    62163```javascript
    63 // Get the current referral source
    64 const source = getReferralSource();
    65 
    66 // Manually populate form fields
    67 populateFormFields();
    68 
    69 // Access the full API
    70 const api = window.FormAttributionTracking;
    71 api.getReferralSource();
    72 api.populateFormFields();
    73 ```
    74 
    75 ## Configuration
    76 
    77 ### Settings Options
    78 
    79 - **Auto-add to new forms**: Automatically add referral source fields to newly created forms
    80 - **Field Name**: Customize the name used for referral source fields
    81 - **Cookie Duration**: How long to store referral source in visitor cookies (1-365 days)
    82 - **Debug Mode**: Enable debug logging in browser console
    83 
    84 ### Source Detection Logic
    85 
    86 1. **UTM Parameters** (highest priority): utm_source, utm_medium, utm_campaign
    87 2. **Stored Cookie**: Previously detected referral source
    88 3. **HTTP Referrer**: Parsed and categorized external referrers
    89 4. **Direct Traffic**: When no referrer is available
    90 
    91 ### Known Source Categories
    92 
    93 The plugin automatically categorizes referrers from popular platforms:
    94 
    95 - **google**: Google search engines
    96 - **facebook**: Facebook and Facebook Messenger
    97 - **twitter**: Twitter/X
    98 - **linkedin**: LinkedIn
    99 - **youtube**: YouTube
    100 - **instagram**: Instagram
    101 - **reddit**: Reddit
    102 - And many more...
    103 
    104 ## Development
    105 
    106 ### Architecture
    107 
    108 The plugin uses a modular architecture with:
    109 
    110 - **Contracts**: Interfaces defining integration requirements
    111 - **Abstracts**: Base classes with common functionality
    112 - **Integrations**: Specific implementations for each form plugin
    113 - **Plugin**: Main orchestration class
    114 
    115 ### Adding New Form Plugin Support
    116 
    117 1. Create a new integration class extending `AbstractFormIntegration`
    118 2. Implement the required interface methods
    119 3. Register the integration in the main Plugin class
    120 
    121 Example:
     164// Get full attribution data object
     165const attribution = window.FormAttributionTracking.getAttributionData();
     166// Returns: { utm_source, utm_medium, utm_campaign, utm_term, utm_content, gclid, landing_page, timestamp }
     167
     168// Get just the traffic source (legacy method)
     169const source = window.FormAttributionTracking.getReferralSource();
     170
     171// Manually trigger form field population
     172window.FormAttributionTracking.populateFormFields();
     173
     174// Access configuration
     175const config = window.FormAttributionTracking.config;
     176```
     177
     178#### JavaScript Events
     179
     180Listen for when attribution data is populated:
     181
     182```javascript
     183window.addEventListener('attributionDataPopulated', function(event) {
     184    console.log('Attribution captured:', event.detail.attribution);
     185    console.log('Fields populated:', event.detail.fieldsCount);
     186});
     187```
     188
     189#### PHP Hooks and Filters
     190
     191Extend or customize the plugin:
     192
     193```php
     194// Add custom form plugin integration
     195add_filter('attribution_tracking_integrations', function($integrations) {
     196    $integrations['CustomForms'] = new CustomFormsIntegration();
     197    return $integrations;
     198});
     199
     200// React to integration initialization
     201add_action('attribution_tracking_integration_initialized', function($integration_name) {
     202    error_log("Attribution tracking initialized for: " . $integration_name);
     203});
     204
     205// Hook into debug logging
     206add_action('form_referral_source_debug_log', function($message, $context, $source) {
     207    error_log("[$source] $message: " . print_r($context, true));
     208}, 10, 3);
     209```
     210
     211## Attribution Field Names
     212
     213The plugin creates these hidden fields in your forms:
     214
     215- `attribution_source` - Traffic source identifier
     216- `attribution_medium` - Marketing medium
     217- `attribution_campaign` - Campaign name
     218- `attribution_term` - Keyword/search term
     219- `attribution_content` - Ad content variation
     220- `attribution_gclid` - Google Ads Click ID
     221- `attribution_landing_page` - First page visited
     222- `attribution_timestamp` - ISO 8601 timestamp of first visit
     223
     224All fields are automatically populated by JavaScript and have PHP fallbacks.
     225
     226## Traffic Source Detection
     227
     228The plugin intelligently categorizes traffic sources:
     229
     230### UTM Parameters (Highest Priority)
     231If UTM parameters are present in the URL, they are captured exactly as provided.
     232
     233### Known Platforms (Automatic Categorization)
     234The plugin recognizes and categorizes referrers from:
     235- Google (google.com, google.co.uk, etc.)
     236- Facebook (facebook.com, fb.com, m.facebook.com)
     237- Twitter/X (twitter.com, x.com, t.co)
     238- LinkedIn (linkedin.com, lnkd.in)
     239- YouTube (youtube.com, youtu.be)
     240- Instagram (instagram.com)
     241- TikTok (tiktok.com)
     242- Pinterest (pinterest.com, pin.it)
     243- Reddit (reddit.com)
     244- Bing (bing.com)
     245- Yahoo (yahoo.com)
     246- DuckDuckGo (duckduckgo.com)
     247
     248### Generic Referrals
     249For unlisted referrers, the clean hostname is stored (e.g., "example.com")
     250
     251### Direct Traffic
     252When no referrer or UTM parameters are present, traffic is marked as "direct"
     253
     254## Troubleshooting
     255
     256### Attribution Data Not Being Captured
     257
     2581. **Enable Debug Mode** in plugin settings
     2592. Open browser console (F12) and check for "[Referral Source]" log messages
     2603. Verify cookies are enabled in the browser
     2614. Check that JavaScript is not being blocked
     262
     263### Fields Not Populating in Forms
     264
     2651. Enable Debug Mode and check console for "Field populated" messages
     2662. Verify the form fields exist (check Manage Forms tab)
     2673. Test with a fresh browser/incognito window
     2684. Check that the form HTML includes the expected hidden field names
     269
     270### Forms Not Showing in Dashboard
     271
     2721. Verify your form plugin (Gravity Forms, Fluent Forms, or Formidable Forms) is active
     2732. Check that you have forms created in that plugin
     2743. Look for PHP errors in debug.log if WP_DEBUG is enabled
     275
     276### GCLID Not Being Captured
     277
     2781. Verify your Google Ads URLs include the {gclid} parameter
     2792. Use Google's Campaign URL Builder to test: https://ga-dev-tools.google/campaign-url-builder/
     2803. Check that cookies are working (GCLID is stored in the attribution cookie)
     2814. Enable Debug Mode to see what parameters are being captured
     282
     283## Extending the Plugin
     284
     285### Adding Support for Other Form Plugins
     286
     287Create a new integration class:
    122288
    123289```php
    124290<?php
    125 
    126291namespace FormAttributionTracking\Integrations;
    127292
    128293use FormAttributionTracking\Abstracts\AbstractFormIntegration;
    129294
    130 class CustomFormIntegration extends AbstractFormIntegration
     295class CustomFormPluginIntegration extends AbstractFormIntegration
    131296{
    132297    public function isAvailable(): bool {
    … …  
    138303    }
    139304   
    140     // Implement other required methods...
     305    public function getVersion(): string {
     306        return '1.0.0';
     307    }
     308   
     309    protected function registerHooks(): void {
     310        // Hook into your form plugin's save/render events
     311        add_action('custom_form_save', [$this, 'onFormSaved'], 10, 2);
     312    }
     313   
     314    public function addReferralSourceField(int $formId): bool {
     315        // Implement logic to add hidden fields to forms
     316    }
     317   
     318    public function removeReferralSourceField(int $formId): bool {
     319        // Implement logic to remove hidden fields
     320    }
     321   
     322    public function hasReferralSourceField(int $formId): bool {
     323        // Check if form has attribution fields
     324    }
     325   
     326    public function getAllForms(): array {
     327        // Return array of all forms
     328    }
    141329}
    142330```
    143331
    144 ### Hooks and Filters
    145 
    146 The plugin provides several hooks for customization:
     332Register your integration:
    147333
    148334```php
    149 // Modify available integrations
    150335add_filter('attribution_tracking_integrations', function($integrations) {
    151     $integrations['Custom'] = new CustomFormIntegration();
     336    $integrations['CustomFormPlugin'] = new CustomFormPluginIntegration();
    152337    return $integrations;
    153338});
    154 
    155 // React to integration initialization
    156 add_action('attribution_tracking_integration_initialized', function($integration_name) {
    157     // Custom logic when integration is initialized
    158 });
    159 ```
    160 
    161 ## JavaScript Events
    162 
    163 The plugin triggers custom events for integration with other scripts:
    164 
    165 ```javascript
    166 // Listen for referral source population
    167 window.addEventListener('referralSourcePopulated', function(event) {
    168     console.log('Referral source populated:', event.detail.source);
    169     console.log('Fields populated:', event.detail.fieldsCount);
    170 });
    171 ```
    172 
    173 ## Troubleshooting
    174 
    175 ### Enable Debug Mode
    176 1. Go to **Settings > Form Referral Source**
    177 2. Enable "Debug Mode"
    178 3. Check browser console for detailed logging
    179 
    180 ### Common Issues
    181 
    182 **Referral source not being captured:**
    183 - Check that JavaScript is enabled
    184 - Verify the field name matches plugin settings
    185 - Ensure cookies are allowed
    186 
    187 **Fields not being populated:**
    188 - Check form HTML for correct field selectors
    189 - Verify timing of form rendering vs. script execution
    190 - Enable debug mode for detailed logging
    191 
    192 **Integration not working:**
    193 - Ensure the form plugin is active and compatible
    194 - Check WordPress error logs for PHP errors
    195 - Verify plugin dependencies are met
    196 
    197 ## Support
    198 
    199 For support, feature requests, or bug reports, please create an issue in the plugin repository or contact the plugin author.
     339```
     340
     341## Architecture
     342
     343The plugin uses a clean, modern PHP 8+ architecture:
     344
     345```
     346src/
     347├── Contracts/
     348│   └── FormIntegrationInterface.php    # Interface all integrations must implement
     349├── Abstracts/
     350│   └── AbstractFormIntegration.php     # Base class with common functionality
     351├── Integrations/
     352│   ├── GravityFormsIntegration.php     # Gravity Forms support
     353│   ├── FluentFormsIntegration.php      # Fluent Forms support
     354│   └── FormidableFormsIntegration.php  # Formidable Forms support
     355├── Views/
     356│   └── admin-page.php                  # Admin dashboard template
     357└── Plugin.php                          # Main plugin orchestration class
     358```
     359
     360## Privacy & Compliance
     361
     362This plugin stores first-party cookies to maintain attribution data. Consider these compliance aspects:
     363
     364- **Cookie Duration**: Configurable 1-365 days (default 30)
     365- **Data Stored**: Marketing attribution data only (no PII)
     366- **First-Party Cookies**: Data stays on your domain
     367- **User Control**: Respects browser cookie settings
     368- **GDPR**: Consider adding cookie consent notices per your requirements
     369- **Data Retention**: Attribution data is only stored in form submissions per your form plugin's data retention policies
     370
     371## Support & Contributing
     372
     373For bug reports, feature requests, or contributions:
     374
     375- Plugin Author: Ryan Howard
     376- Website: https://www.ryanhoward.dev
     377- Text Domain: form-attribution-tracking
    200378
    201379## License
    … …  
    205383## Changelog
    206384
    207 ### 1.0.2
    208 - Verified compatibility with the latest WordPress core release.
    209 - Updated plugin metadata (`Tested up to`) to reflect successful testing on the newest WordPress version.
    210 - Minor internal improvements to maintain stability with future WordPress updates.
    211 
    212 ### 1.0.1
    213 - Fixed a fatal error occurring on Fluent Forms submissions when fallback attribution data was processed as a string instead of an array.
    214 - Improved validation and safety checks for referral source population.
    215 - Enhanced compatibility with Fluent Forms to prevent incorrect data handling.
    216 
     385### 1.1.0
     386- Enhanced documentation with comprehensive Google Ads integration guide
     387- Improved attribution field descriptions and usage examples
     388- Added detailed troubleshooting section
     389- Updated developer API documentation
     390- Added privacy and compliance guidelines
     391- Clarified first-touch attribution methodology
    217392
    218393### 1.0.0
    219394- Initial release
    220 - Formidable Forms integration
    221 - Fluent Forms integration
     395- Support for Gravity Forms, Fluent Forms, and Formidable Forms
     396- Complete Google Ads attribution tracking (8 fields)
     397- GCLID capture for conversion imports
     398- First-touch attribution with cookie persistence
     399- JavaScript + PHP dual-layer tracking
     400- Admin dashboard with statistics
     401- Debug mode for troubleshooting
    222402- Modern PHP 8+ architecture
    223 - Comprehensive admin interface
    224 - Enhanced JavaScript tracking
     403- Mutation observer for dynamic forms
Note: See TracChangeset for help on using the changeset viewer.