Attribution Tracking System¶

Overview¶

The BoastPress AB Testing plugin uses an attribution system to track which content variants users have seen and to associate conversions with these variants. This document explains how the attribution system works and how the plugin integrates with the attribution-tracker.js library.

Attribution Cookie System¶

How Attribution Cookies Work¶

The plugin tracks which test variants a visitor has seen through a single attribution cookie:

1. Configurable Cookie Name:

   • The plugin uses a single cookie to store all attribution data
   • By default, this cookie is named attribution_data
   • You can customize this name in the plugin settings at A/B Tests > Settings

2. Test Attribution Format:

   • Inside the cookie, each test's attribution is tracked using a key derived from the test name
   • For example, a test named "Homepage Test" would use the key ab_homepage_test

3. Cookie Security and Persistence:

   • The cookie uses secure settings when SSL is available
   • Attribution data persists for 30 days by default
   • The plugin handles cookie management automatically

Viewing Attribution Data¶

You can view the attribution data stored in your browser:

1. Open your browser's developer tools (F12 in most browsers)
2. Navigate to the Application or Storage tab
3. Select Cookies and find your site
4. Look for the cookie named attribution_data (or your custom name)

The cookie content is stored in JSON format and might look something like this:

{"ab_homepage_test":"variant_a","ab_pricing_test":"control"}

Conversion Tracking¶

The plugin tracks conversions when users who have been exposed to a test variant visit your designated conversion pages:

1. Setting Conversion Pages:

   • When creating or editing a test, specify the URL path of your conversion page(s)
   • For example, /thank-you or /checkout/confirmation

2. How Conversion Tracking Works:

   • When a user visits a conversion page, the plugin checks the attribution cookie
   • If the user has seen a test variant, the conversion is attributed to that variant
   • The plugin automatically increments conversion counters in your dashboard

3. Viewing Conversion Data:

   • Navigate to A/B Tests > [Your Test] to view impressions and conversions
   • The system calculates conversion rates and statistical significance

Integration with attribution-tracker.js¶

The plugin is designed to work seamlessly with attribution-tracker.js, providing enhanced tracking capabilities.

Custom Events for Analytics Integration¶

The plugin dispatches custom JavaScript events that can be captured by attribution-tracker.js or other analytics tools:

1. The abTestingLoaded Event:

   • Triggered when a test variant is displayed to a user
   • Contains data about which test and variant was shown
   • Useful for integrating with analytics platforms

2. Listening for Events: This example shows how to capture test data with any analytics system:

   document.addEventListener('abTestingLoaded', function(e) {
       const testData = e.detail;
       console.log(`Test: ${testData.testName}, Variant: ${testData.versionName}`);
   
       // Send to your analytics platform
       // Example: Google Analytics 4
       if (typeof gtag === 'function') {
           gtag('event', 'ab_test_impression', {
               'test_name': testData.testName,
               'variant': testData.versionName
           });
       }
   });
   

Using with attribution-tracker.js¶

To leverage the full capabilities of attribution-tracker.js:

1. Installation:

   • Include the attribution-tracker.js script in your theme or via a custom plugin
   • Configure it to use the same cookie name as configured in the AB Testing plugin

2. Simple Integration Example:

   // Initialize attribution tracker with the same cookie name
   window.attributionTracker = new AttributionTracker({
       cookieName: 'attribution_data', // Match your plugin setting
       trackerEndpoint: '/api/track-attribution' // Optional tracking endpoint
   });
   
   // Listen for AB testing events
   document.addEventListener('abTestingLoaded', function(e) {
       if (window.attributionTracker) {
           window.attributionTracker.trackEvent('ab_test_view', {
               test: e.detail.testName,
               variant: e.detail.versionName
           });
       }
   });
   

Common Questions¶

Do I need to implement attribution-tracker.js to use this plugin?¶

No, the plugin functions fully without attribution-tracker.js. The integration is optional and provides enhanced capabilities for marketing attribution.

Can I use multiple analytics platforms simultaneously?¶

Yes, you can listen for the abTestingLoaded event multiple times to send data to different analytics platforms.

How does the plugin handle users with cookies disabled?¶

For users who have disabled cookies, the plugin will still show content variants, but it won't be able to maintain consistency across page loads or track conversions for those users.

Does the plugin work with GDPR cookie consent systems?¶

Yes, but you may need to configure your cookie consent system to include the attribution cookie as a "functional" or "analytics" cookie depending on your privacy policy and compliance needs.

Troubleshooting¶

If you're experiencing issues with attribution tracking, check these common problems and solutions:

1. No conversions recorded¶

• Check conversion page URLs: Ensure your conversion page URL matches exactly what's configured in the test (including trailing slashes)
• Verify cookie functionality:
  • Check that cookies are not being blocked by browser settings
  • Ensure consent management tools aren't preventing the attribution cookie
  • Inspect the cookie in your browser developer tools to confirm it exists
• Test configuration:
  • Verify the test is active and properly implemented
  • Check that the test hasn't reached its end date or visitor limit

2. Inconsistent test variants¶

• Cookie issues: Clear your browser cookies and revisit the test page to see if the problem persists
• Caching problems:
  • For cached sites, ensure AJAX mode is enabled for tests
  • Check server-side caching configurations that might be serving pre-rendered content
• Multiple devices: Remember that different devices have separate cookie storage; inconsistency across devices is expected behavior

3. Analytics integration not working¶

• Check event implementation:
  • Verify your event listeners are properly set up
  • Use browser console to confirm events are firing (console.log within event listeners)
• Debug browser issues:
  • Check browser console for JavaScript errors that might prevent execution
  • Test in multiple browsers to isolate browser-specific problems
• Script loading order:
  • Ensure your analytics code loads before your AB testing event listeners
  • Consider using event delegation or deferred listeners if timing is an issue

If problems persist after trying these solutions, please check our support forums or contact our technical team.

Next Steps¶

Now that you understand how attribution works, you may want to explore:

• Advanced Topics - For integration with Google Analytics and other platforms