Table of Contents


Troubleshooting Referral Links and Attribution

This comprehensive troubleshooting guide addresses common issues, questions, and solutions for the Referral Links and Attribution module. Use this resource to quickly diagnose problems, understand system behavior, and resolve attribution issues affecting partner credit assignment and referral tracking accuracy.

Attribution and Tracking Issues

No Partner Attribution on Leads

Problem: CRM leads created from form submissions do not have Partner Contact field populated, resulting in no partner attribution despite prospects clicking referral links.

Possible Causes:

  • Hidden Partner Contact field not configured on form layout
  • Field ID mismatch between form integration code and actual form field
  • Partner Contact field mapped to incorrect CRM field
  • PartnerTrack.js script not loading before form submission
  • Form integration code not calling mgxPartnerTrack.getPartnerKey() method

Solutions:

  1. Verify Hidden Field Configuration: Open the form layout and confirm a hidden field exists that maps to the Partner Contact lookup field. For Salesforce, verify mapping to MagentrixOne__PartnerContact_mgtrx__c. For native Magentrix, verify mapping to PartnerContactId field.

  2. Check Field ID Consistency: Review form integration code and ensure the HTML ID used in getElementById() matches the actual hidden field ID. Common mistake: using "partnerContact" in code but field has different ID like "PartnerContact__c".

  3. Test Partner Key Retrieval: Add console logging to form integration code to verify getPartnerKey() returns expected Partner Contact ID. Open browser console and check for logged partner ID value when testing with referral links.

  4. Verify Script Load Order: Ensure PartnerTrack.js script loads in page <head> before form integration code executes. Check browser network tab to confirm script loads successfully without 404 or CORS errors.

  5. Test Complete Referral Flow: Use incognito browser, click partner referral link, verify magpk parameter in URL, submit form, check console for tracking confirmation, then verify lead in CRM has Partner Contact populated.

Referral Reports Empty

Problem: Referral Reports show no data despite partners sharing referral links and prospects submitting forms.

Possible Causes:

  • onInitPartnerTracker() callback function not implemented or not firing
  • Form submit button selector incorrect in integration code
  • trackSignup() method not called when forms submit
  • Attribution model or cookie-less tracking changed without script redeployment
  • Domain not included in Whitelisted URLs

Solutions:

  1. Verify Callback Implementation: Confirm onInitPartnerTracker() function exists in page code and is properly formatted. Add console.log() inside callback to verify function executes when page loads.

  2. Test Button Selector: Verify form submit button ID or class matches selector in addEventListener() code. Use browser inspector to identify actual button element and adjust selector accordingly. Common mistake: using "btnSubmit" but button has ID "submitButton".

  3. Confirm trackSignup() Execution: Add console logging before trackSignup() call to verify method executes when button clicked. Check browser console for confirmation when testing form submission.

  4. Check Script Configuration: Navigate to Referral Settings and verify current attribution model and cookie-less tracking settings match your intended configuration. If changed recently, regenerate and redeploy PartnerTrack.js script to all pages.

  5. Verify Domain Whitelisting: Navigate to Setup → Security → Whitelisted URLs and confirm landing page domain is included in whitelist. Add missing domains and test again with incognito browser session.

magpk and magkey Parameters Missing from URLs

Problem: Landing page URLs do not include magpk (Partner Contact ID) and magkey (session identifier) parameters when prospects click referral links.

Possible Causes:

  • Using direct destination URLs instead of partner referral links
  • Referral link redirect functionality not operating correctly
  • URL parameter stripping by intermediate systems or proxies
  • Referral link format incorrect or corrupted

Solutions:

  1. Verify Referral Link Format: Confirm partners are using referral links in format /referral/refer/{id} generated from Pipeline → Referral Links → Get Referral Link. Direct destination URLs will not append attribution parameters.

  2. Test Referral Redirect: Manually click referral link in incognito browser and observe redirect behavior. Confirm browser redirects from /referral/refer/{id} to destination URL with parameters appended.

  3. Check Intermediate Systems: If using link shorteners, email security scanners, or proxy services, verify these systems do not strip URL parameters during redirect or scanning processes.

  4. Regenerate Referral Link: If link appears corrupted or malformed, generate fresh referral link from Pipeline interface and test with new link to confirm parameters append correctly.

  5. Monitor Magentrix Service Status: If redirect functionality fails consistently across multiple links, check Magentrix service status or contact support to verify platform redirect services operate normally.

Referral Link Returns Page Not Found (404)

Problem: When prospects click a partner referral link, they encounter a "Page Not Found (404)" error instead of being redirected to the intended landing page.

Possible Causes:

  • Partner contact associated with the referral link has been deactivated in the PRM
  • Partner user account has been deactivated in Magentrix
  • Referral link format is malformed or incomplete
  • Marketing link destination URL no longer exists

Solutions:

  1. Verify Partner Contact Status: Check the CRM to confirm the partner contact associated with the referral link is active. Deactivated partner contacts cause their referral links to stop functioning and return 404 errors.

  2. Reactivate Partner Contact: If the partner contact was deactivated in error, reactivate the contact in your CRM. Referral links will resume functioning once the contact status is restored to active.

  3. Generate New Referral Link: If the partner contact cannot be reactivated, assign a new active partner contact to the partner account and have them generate a fresh referral link from Pipeline → Referral Links.

  4. Check Marketing Link Destination: Verify the marketing link destination URL is valid and accessible. If the landing page has been removed or URL changed, update the marketing link with the correct destination.

  5. Test Link Format: Ensure the referral link follows the correct format /referral/refer/{id}. Incomplete or corrupted links will fail to redirect properly.

Cross-Page Attribution Not Persisting

Problem: Attribution works on initial landing page but does not persist when prospects navigate to other pages before submitting forms.

Possible Causes:

  • PartnerTrack.js script not deployed to all pages
  • Different domains used for landing pages and form pages
  • Browser security settings preventing fingerprint storage
  • Attribution context cleared by page reloads or navigation

Solutions:

  1. Deploy Script Comprehensively: Ensure PartnerTrack.js script is deployed in <head> section of all pages prospects may visit including landing pages, form pages, product pages, pricing pages, and resource pages.

  2. Verify Domain Consistency: Confirm all pages are on same domain included in Whitelisted URLs. Attribution does not automatically persist across different domains unless both are properly configured.

  3. Test Cross-Page Navigation: Click referral link in incognito browser, navigate to multiple pages observing console messages, then submit form on different page than initial landing. Verify attribution persists throughout journey.

  4. Check Browser Compatibility: Test attribution persistence across different browsers (Chrome, Firefox, Safari, Edge) to identify browser-specific issues. Some browsers may have stricter privacy settings affecting fingerprint storage.

  5. Monitor Console for Errors: Keep browser console open during cross-page navigation testing. Watch for JavaScript errors, CORS issues, or warnings suggesting problems with fingerprint persistence logic.

Script and Technical Issues

PartnerTrack.js Script Not Loading

Problem: Browser console shows errors indicating PartnerTrack.js script failed to load, preventing attribution tracking functionality.

Possible Causes:

  • Script URL incorrect or inaccessible
  • CORS restrictions blocking script from loading
  • Script deployment location incorrect (not in <head>)
  • Network or firewall blocking Magentrix tracking endpoints
  • Script file corrupted or incomplete during copy/paste

Solutions:

  1. Verify Script Placement: Confirm PartnerTrack.js script is placed in <head> section of HTML before other scripts or integration code. Script must load before onInitPartnerTracker() callback can execute.

  2. Check Script Source: Review script tag and verify src attribute points to correct Magentrix tracking endpoint. Script should reference your specific Magentrix instance domain.

  3. Test Script URL: Copy script URL from src attribute and paste into browser address bar to verify script loads without authentication or access errors. Should return JavaScript content without errors.

  4. Review CORS Errors: If console shows CORS errors, verify domain is included in Whitelisted URLs and that script was generated for current Magentrix instance (not copied from different environment).

  5. Regenerate Script: Return to Referral Settings, regenerate PartnerTrack.js script, and carefully copy complete script without modifications. Redeploy to test environment and verify loading succeeds.

CORS or 403 Forbidden Errors

Problem: Browser console displays CORS (Cross-Origin Resource Sharing) errors or 403 Forbidden errors when PartnerTrack.js attempts to communicate with Magentrix tracking endpoints.

Possible Causes:

  • Landing page domain not included in Whitelisted URLs
  • Script copied from different Magentrix environment (sandbox vs. production)
  • Corporate firewall or security software blocking Magentrix endpoints
  • Browser extensions (ad blockers, privacy tools) interfering with tracking

Solutions:

  1. Add Domain to Whitelist: Navigate to Setup → Security → Whitelisted URLs and add landing page domain including protocol and subdomain. For example, add both "yourcompany.com" and "www.yourcompany.com" if both are used.

  2. Verify Environment Match: Ensure PartnerTrack.js script was generated from same Magentrix environment where attribution data should be recorded. Scripts from sandbox environments cannot write to production environments.

  3. Test Without Extensions: Open incognito/private browsing window and disable browser extensions, then test attribution. If works without extensions, identify conflicting extension and add Magentrix domains to extension whitelist.

  4. Check Corporate Firewall: Work with IT security team to verify corporate firewalls or security appliances do not block Magentrix tracking endpoints. May need to whitelist specific Magentrix domains in security policies.

  5. Review Browser Console Details: Examine complete error messages in browser console including specific URLs, error codes, and request headers to identify exact cause of CORS or 403 errors.

Script Initialization Timing Issues

Problem: Form integration code attempts to use mgxPartnerTrack object before PartnerTrack.js completes initialization, resulting in "undefined" errors.

Possible Causes:

  • Integration code executes before PartnerTrack.js loads
  • onInitPartnerTracker() callback not implemented correctly
  • Race condition between script loading and integration code execution
  • Multiple scripts competing for initialization timing

Solutions:

  1. Use Callback Pattern: Ensure form integration code is placed inside onInitPartnerTracker(tracker) callback function rather than executing immediately on page load. Callback guarantees PartnerTrack.js is ready.

  2. Check Script Order: Verify PartnerTrack.js script tag appears before integration code in page HTML. Scripts execute in order they appear, so tracking script must load first.

  3. Add Initialization Check: Before using mgxPartnerTrack object, add conditional check: if (window.mgxPartnerTrack && mgxPartnerTrack.getPartnerKey) to verify object exists and method available.

  4. Implement Retry Logic: For complex pages with dynamic content loading, implement retry logic that attempts to access mgxPartnerTrack with delay if initially undefined. Use setTimeout() to retry after 100-200ms.

  5. Test Across Browsers: Timing issues may manifest differently across browsers. Test in Chrome, Firefox, Safari, and Edge to identify browser-specific timing problems requiring adjusted initialization approach.

Form Integration Issues

HubSpot Form Integration Not Working

Problem: HubSpot forms submit successfully but do not trigger PartnerTrack attribution tracking or populate partner attribution data.

Possible Causes:

  • Form field selectors incorrect (HubSpot randomizes element IDs)
  • Integration code attempts to access form before HubSpot renders it
  • Form embedded in iframe preventing direct DOM access
  • Event listener not binding to HubSpot form submit event correctly

Solutions:

  1. Use Name Attribute Selectors: Access HubSpot form fields using name attribute rather than ID: document.querySelector('input[name="email"]') instead of document.getElementById('email'). Name attributes remain consistent.

  2. Implement Delayed Binding: Add setTimeout() delay before attempting to bind to HubSpot form to ensure form fully renders before integration code executes. Start with 2000ms delay and adjust if needed.

  3. Check for iFrame Embed: If HubSpot form is in iframe, integration approach requires modification. Either deploy PartnerTrack.js inside iframe context or use HubSpot Forms API for cross-frame communication.

  4. Verify Form Class Name: Ensure form selector uses correct HubSpot form class: document.getElementsByClassName('hs-form')[0]. Verify class name matches actual rendered form in browser inspector.

  5. Test with console Logging: Add extensive console.log() statements throughout HubSpot integration code to track execution flow, form element discovery, and event binding success. Console output reveals exact integration failure point.

Marketo Form Integration Not Working

Problem: Marketo forms submit successfully but partner attribution tracking does not fire or record referral data.

Possible Causes:

  • MktoForms2.loadForm() executes before PartnerTrack.js loads
  • Form field names incorrect in form.vals() access
  • onSubmit handler not returning true, blocking form submission
  • PartnerTrack.js script not accessible in Marketo form context

Solutions:

  1. Ensure Script Load Order: Place PartnerTrack.js script before Marketo form embedding code to guarantee tracking script loads first. Marketo form loading should occur after PartnerTrack initialization confirms.

  2. Verify Field Names: Use form.vals() to retrieve all form values and add console.log(form.vals()) to see actual field names Marketo uses. Adjust integration code to use correct field names (case-sensitive).

  3. Return True from onSubmit: Confirm form.onSubmit() handler includes return true; statement at end allowing Marketo to proceed with form submission after tracking fires.

  4. Use Global mgxPartnerTrack Object: Access tracking functionality through window.mgxPartnerTrack rather than tracker parameter if callback timing issues occur with Marketo form loading sequence.

  5. Test Marketo Form Independently: Create simple test page with only Marketo form and PartnerTrack.js to isolate integration issues from other page complexity or script conflicts.

Magentrix Form Integration Not Working

Problem: Magentrix Lead forms submit successfully but Partner Contact field remains unpopulated or tracking events do not fire.

Possible Causes:

  • Hidden Partner Contact field ID incorrect in integration code
  • Field mapping incorrect (wrong CRM lookup field)
  • Script attempts to populate field before DOM ready
  • Button selector does not match actual submit button element

Solutions:

  1. Verify Field ID Match: Check form layout in Layout Designer to confirm hidden field HTML ID, then verify integration code uses exact matching ID in getElementById() call.

  2. Confirm CRM Field Mapping: Open field configuration and verify field maps to correct CRM lookup: Salesforce = MagentrixOne__PartnerContact_mgtrx__c, Native = PartnerContactId. Incorrect mapping results in empty field even if populated in browser.

  3. Check Submit Button Selector: Use browser inspector to identify submit button element and verify selector in addEventListener() matches. Try both ID-based and class-based selectors: document.getElementById("btnSubmit") or document.querySelector(".btn-primary").

  4. Test Field Population: Add console logging to verify getPartnerKey() returns partner ID and that field.value assignment succeeds. Log both partner ID and field element to confirm both exist before assignment.

  5. Validate Complete Integration: Review complete Magentrix form integration example from Developer Guide and compare line-by-line with your implementation to identify any missing components or syntax errors.

Lead Creation and CRM Issues

Duplicate Leads Created

Problem: Single form submission results in duplicate lead records in CRM, causing data quality issues and partner confusion about attribution.

Possible Causes:

  • Both "Create a lead when a referral is submitted" enabled in Referral Settings AND external form system creating leads
  • Form system creating leads while Magentrix also configured to create leads
  • Multiple form submissions from same prospect due to integration errors
  • Form handler calling trackSignup() multiple times per submission

Solutions:

  1. Choose Single Lead Creation Path: Determine whether Magentrix or external form system should create leads. If using external forms (HubSpot, Marketo, HTML), disable "Create a lead when a referral is submitted" in Referral Settings.

  2. Review Integration Code: Ensure trackSignup() method is called only once per form submission. Avoid binding to both button click AND form submit events which causes double firing.

  3. Implement Submission Guards: Add flag variable preventing multiple trackSignup() calls: if (submitted) return; submitted = true; trackSignup(...); at start of form handler.

  4. Monitor Referral Reports: Check Referral Reports for duplicate entries with same email and timestamp suggesting integration calling tracking multiple times. Fix integration code to eliminate duplicate calls.

  5. Clean Up Duplicate Leads: Work with CRM administrators to identify and merge duplicate leads. Implement lead deduplication processes to handle any future duplicates resulting from integration issues.

Lead Source Not Populated

Problem: CRM leads have Partner Contact attribution but Lead Source field is empty or incorrect rather than showing "Partner Referral" as expected.

Possible Causes:

  • trackSignup() call missing LeadSource parameter
  • LeadSource value does not match CRM picklist values
  • CRM validation rules blocking Lead Source update
  • Field mapping incorrect between Magentrix and CRM

Solutions:

  1. Add LeadSource Parameter: Ensure trackSignup() method includes LeadSource: "Partner Referral" in data object passed to method. Parameter is optional but strongly recommended for proper lead routing.

  2. Verify Picklist Values: Check CRM Lead Source picklist configuration and confirm "Partner Referral" is valid value. If not, either add to picklist or adjust trackSignup() to use existing valid value.

  3. Check Validation Rules: Review CRM validation rules on Lead object to ensure no rules prevent Lead Source from being set during lead creation or update processes.

  4. Test with Different Values: Try using different Lead Source value in trackSignup() to determine if specific value causes issues or if field mapping problem affects all values.

  5. Review CRM Integration Logs: Check Magentrix CRM connector logs for errors or warnings related to Lead Source field updates. Logs may reveal field mapping issues or data type mismatches.

Campaign Association Not Working

Problem: Leads created from referrals do not associate with CRM campaigns despite utm_campaign parameter included in marketing links.

Possible Causes:

  • utm_campaign value does not exactly match CRM campaign name or ID
  • Campaign name matching is case-sensitive in CRM system
  • HubSpot campaign mapping not supported (Salesforce limitation)
  • CRM does not have campaign with matching name/ID

Solutions:

  1. Verify Exact Name Match: Compare utm_campaign parameter value with actual campaign name in CRM. Match must be exact including case, spaces, and special characters.

  2. Test with Campaign ID: If name matching fails, try using campaign ID in utm_campaign parameter instead of campaign name. Campaign ID matching is more reliable than name-based matching.

  3. Check CRM Platform: Understand that HubSpot campaign mapping has limitations compared to Salesforce. For HubSpot environments, campaign association may require alternative implementation.

  4. Create Missing Campaigns: If campaigns do not exist in CRM matching utm_campaign values, create campaigns first before expecting automatic association to function.

  5. Review Campaign Settings: Verify CRM campaigns are active and not archived. Some CRM systems prevent association with inactive campaigns even when names match correctly.

Attribution Persistence and Session Issues

Attribution Resets Unexpectedly

Problem: Partner attribution works initially but resets or disappears before prospects convert, resulting in attribution loss and partner credit issues.

Possible Causes:

  • Prospects clearing browser data between referral click and conversion
  • Prospects using private/incognito browsing mode
  • Prospects switching devices or browsers during journey
  • PartnerTrack.js script redeployed with configuration changes
  • Landing page moved to domain not in Whitelisted URLs

Solutions:

  1. Understand Normal Reset Scenarios: Educate stakeholders that attribution naturally resets when prospects clear browser data, use private browsing, or switch devices. This is expected behavior of fingerprint-based tracking.

  2. Monitor Session Duration: Analyze time between referral clicks and conversions in Referral Reports to understand typical session duration. Very long durations increase likelihood of attribution loss due to browser data clearing.

  3. Avoid Unnecessary Script Changes: Do not redeploy PartnerTrack.js unless attribution or cookie-less settings require changes. Script redeployment invalidates existing fingerprints requiring prospects to click referral links again.

  4. Verify Domain Configuration: Confirm all domains prospects may visit remain in Whitelisted URLs. Domain changes or site migrations require updating whitelist to maintain attribution across domain updates.

  5. Communicate Limitations: Set realistic expectations with partners about attribution persistence limitations related to browser data clearing and device switching rather than positioning tracking as infallible.

Attribution Model Switching Issues

Problem: After changing attribution model from First-Click to Last-Click (or vice versa), attribution behavior appears inconsistent or incorrect.

Possible Causes:

  • PartnerTrack.js script not regenerated after model change
  • Script not redeployed to all web properties after regeneration
  • Existing device fingerprints still using old attribution logic
  • Testing with browser sessions that predate model change

Solutions:

  1. Regenerate Script: After changing attribution model in Referral Settings, regenerate PartnerTrack.js script by copying fresh script from Get Embed Code modal.

  2. Redeploy Comprehensively: Deploy regenerated script to all pages where PartnerTrack.js was previously deployed. Incomplete redeployment results in inconsistent behavior across pages.

  3. Clear Test Browser Data: When testing new attribution model, use fresh incognito session or clear browser data completely to ensure test operates under new model without legacy fingerprint influence.

  4. Allow Transition Period: Understand that existing device fingerprints will continue using previous attribution logic until prospects click new referral links under updated script. Attribution behavior gradually transitions rather than changing immediately.

  5. Document Model Change: Record attribution model change date and communicate to partners explaining transition period and how credit assignment may vary during transition as new model phases in.

Performance and Data Quality Issues

Slow Form Submission Performance

Problem: Forms with PartnerTrack.js integration submit slowly or hang briefly during submission, creating poor user experience.

Possible Causes:

  • Integration code includes synchronous operations blocking submission
  • trackSignup() call includes excessive data causing slow network requests
  • Form validation errors retrying submission multiple times
  • Network latency to Magentrix tracking endpoints

Solutions:

  1. Verify Asynchronous Operation: Confirm trackSignup() method executes asynchronously without blocking form submission. Method should fire-and-forget allowing form to proceed immediately.

  2. Minimize Data Payload: Only include required and essential fields in trackSignup() data object. Excessive custom fields or large data values slow tracking requests unnecessarily.

  3. Optimize Integration Code: Remove unnecessary operations from form submit handler. Keep code minimal focusing only on extracting form values and calling trackSignup() without additional processing.

  4. Test Network Performance: Use browser developer tools Network tab to measure actual trackSignup() request timing. Typical tracking requests complete in 50-100ms and should not noticeably impact submission.

  5. Consider Async Form Handlers: For AJAX form submissions, ensure tracking call does not block AJAX request. Fire trackSignup() independently without waiting for completion before submitting form data.

Suspicious Referral Patterns Detected

Problem: Referral Reports show patterns suggesting fraudulent or manipulated referral activity such as repeated submissions with same fingerprints or obviously fake data.

Possible Causes:

  • Partners attempting to artificially inflate referral counts
  • Automated bot submissions targeting forms
  • Testing activity not isolated from production reporting
  • Legitimate user repeatedly testing forms during evaluation

Solutions:

  1. Review Fingerprint Patterns: Analyze Referral Reports for duplicate fingerprint IDs with multiple submissions. Legitimate prospects rarely submit multiple times from same device unless testing or encountering form errors.

  2. Validate Lead Data: Cross-reference suspicious referrals with CRM lead records to verify prospect information appears legitimate. Fake emails, missing phone numbers, or nonsensical company names indicate fraud.

  3. Engage Partners Directly: Contact partners associated with suspicious referral patterns to discuss activity. Legitimate testing or technical issues may explain patterns that initially appear fraudulent.

  4. Implement Test Environment: Establish separate test environment with distinct Referral Settings and script preventing test activity from appearing in production reports. Communicate test environment to partners for legitimate testing needs.

  5. Document Fraud Policies: Establish clear policies defining acceptable referral practices and consequences for fraudulent activity. Communicate policies to partners and enforce consistently when violations occur.

Troubleshooting Referral Links and Attribution provides comprehensive diagnostic guidance for resolving common issues affecting partner attribution accuracy, referral tracking functionality, and program operations, enabling administrators and developers to quickly identify and resolve problems maintaining consistent attribution quality across the entire referral lifecycle.

Jump to Referral Links and Attribution Checklist

<< Referral Link Management Best Practices


Privacy & Security StatementTerms & Conditions
Copyright © 2025 by Magentrix Corporation - All rights reserved.
Powered by Magentrix