> ## Documentation Index > Fetch the complete documentation index at: https://docs.affelios.com/llms.txt > Use this file to discover all available pages before exploring further. # How attribution works > Technical guide for implementing Affelios tracking on your website - ClickKey handling, attribution setup, and backend integration This guide is specifically for **program operators** who need to implement Affelios tracking on their websites. If you're an affiliate looking to understand how tracking works, see [How Tracking Links Work](/knowledge-base/affiliates/tracking-links). ## Technical Implementation Overview As an operator, you need to integrate Affelios tracking into your website to properly attribute sales to affiliates and process commission payments. This involves handling ClickKeys, storing attribution data, and sending transaction information to Affelios. ### Integration Architecture Configure your website to receive and capture ClickKeys from affiliate tracking links when customers arrive at your site. Store ClickKey data in your backend system, associating it with customer sessions or accounts for future attribution. Send revenue and transaction data to Affelios along with stored ClickKeys to generate affiliate commissions. Affelios processes the transaction data and calculates commissions based on your configured commission plans. *** ## ClickKey Parameter Implementation When setting up your brands in Affelios, you specify how ClickKeys are passed to your website through URL parameters. ### Common Parameter Configurations **Most Common Implementations:** ``` https://yoursite.com/product?clickId=[ClickKey] https://yoursite.com/product?referral=[ClickKey] https://yoursite.com/product?utm_source=affiliate&clickId=[ClickKey] ``` **Parameter Name Options:** * `clickId` - Most common and recommended * `gclid` - Google-style parameter for familiarity * `btag` - Custom brand tag * `referral` - Simple referral parameter * `affiliate_id` - Descriptive parameter name * `tracking_code` - Alternative descriptive name **Product-Specific Landing:** ``` https://yourstore.com/products/widget-pro?clickId=abc123def456 ``` **Category Landing:** ``` https://yourstore.com/category/electronics?referral=xyz789uvw012 ``` **Homepage with UTM:** ``` https://yourstore.com/?utm_source=affiliate&utm_medium=link&clickId=mno345pqr678 ``` **Custom Landing Pages:** ``` https://yourstore.com/special-offer?btag=stu901vwx234&campaign=summer2024 ``` **Combining Parameters:** ``` https://yoursite.com/product?clickId=abc123&utm_source=affiliate&utm_campaign=summer ``` **Fallback Parameters:** * Primary: `clickId` * Secondary: `gclid` (for Google Ads compatibility) * Tertiary: `referral` (for general referral tracking) **Implementation Logic:** ```javascript theme={null} function getClickKey() { const urlParams = new URLSearchParams(window.location.search); return urlParams.get('clickId') || urlParams.get('gclid') || urlParams.get('referral') || null; } ``` *** ## Backend ClickKey Storage Proper ClickKey storage is critical for accurate commission attribution. You need to capture and maintain ClickKey data throughout the customer journey. ### Storage Implementation Strategies **Implementation Approach:** * Store ClickKey in server-side sessions * Maintain throughout customer browsing session * Associate with customer actions and eventual purchases **Example (Node.js/Express):** ```javascript theme={null} // Capture ClickKey on landing app.get('*', (req, res, next) => { const clickKey = req.query.clickId || req.query.gclid || req.query.referral; if (clickKey) { req.session.clickKey = clickKey; req.session.clickTimestamp = new Date(); } next(); }); // Use during checkout app.post('/checkout', (req, res) => { const order = processOrder(req.body); if (req.session.clickKey) { order.affiliateClickKey = req.session.clickKey; order.clickTimestamp = req.session.clickTimestamp; } // Process order and send to Affelios }); ``` **Pros:** * Simple implementation * Reliable for same-session purchases * No client-side storage issues **Cons:** * Lost if session expires * Doesn't work across devices * Limited attribution window **Implementation Approach:** * Store ClickKey in persistent cookies * Configure appropriate expiration time * Maintain across multiple sessions and visits **Example (JavaScript):** ```javascript theme={null} // Set ClickKey cookie on landing function setClickKeyCookie() { const urlParams = new URLSearchParams(window.location.search); const clickKey = urlParams.get('clickId') || urlParams.get('gclid'); if (clickKey) { // Set cookie for 30 days const expirationDate = new Date(); expirationDate.setDate(expirationDate.getDate() + 30); document.cookie = `clickKey=${clickKey}; expires=${expirationDate.toUTCString()}; path=/; SameSite=Lax`; document.cookie = `clickTimestamp=${Date.now()}; expires=${expirationDate.toUTCString()}; path=/; SameSite=Lax`; } } // Retrieve during checkout function getClickKeyFromCookie() { const cookies = document.cookie.split(';'); const clickKeyCookie = cookies.find(cookie => cookie.trim().startsWith('clickKey=')); return clickKeyCookie ? clickKeyCookie.split('=')[1] : null; } ``` **Cookie Configuration Best Practices:** * Set appropriate expiration (30-90 days typical) * Use `SameSite=Lax` for cross-site compatibility * Consider `Secure` flag for HTTPS sites * Implement cookie consent compliance **Pros:** * Persists across sessions * Works for return customers * Client-side implementation possible **Cons:** * Subject to cookie blocking * Privacy concerns * May be cleared by users *** ## Transaction Reporting to Affelios Once you have ClickKey data stored and a customer completes a purchase, you need to send transaction information to Affelios to generate affiliate commissions. **Complete Attribution Flow:** The optimal approach follows a clear progression from initial capture to permanent storage and reporting. **Step-by-Step Flow:** 1. **Initial Capture** - Store in temporary locations for immediate tracking 2. **User Registration** - Transfer to permanent user record when they sign up 3. **Purchase Event** - Associate with transaction and report to Affelios **Implementation Approach:** * **Frontend**: Capture ClickKeys in session storage and cookies for persistence * **Backend**: Transfer attribution data to permanent database storage during registration * **Purchase Flow**: Retrieve ClickKey from user account or temporary storage, then report to Affelios **Integration Points:** * User registration endpoint receives and stores ClickKey data * Order creation endpoint handles attribution lookup and reporting * Fallback logic ensures attribution works for both registered and anonymous users **Benefits of This Flow:** * **Immediate capture** - No attribution loss from page navigation * **Progressive enhancement** - Upgrades from temporary to permanent storage * **Reliable reporting** - Multiple fallback sources ensure attribution * **Clean architecture** - Clear separation of capture, storage, and reporting *** ## Commission Plan Configuration Configure how commissions are calculated and attributed to affiliates based on your business requirements. ### Commission Plan Hierarchy **Commission Plan Evaluation Order:**\ Affelios evaluates commission plans in order of specificity, using the most specific match available: 1. **Affiliate + Brand + Product + Tracker** (Most specific) 2. **Affiliate + Brand + Tracker** 3. **Affiliate + Tracker** 4. **Affiliate + Product** 5. **Affiliate + Brand** 6. **Affiliate only** (Least specific affiliate plan) 7. **Default Product Plan** (Brand + Product) 8. **Default Brand Plan** 9. **Fully Default Plan** (System-wide fallback) **Implementation Considerations:** * Create specific plans for high-value affiliates * Set product-specific rates for different margin items * Use tracker-specific plans for performance incentives * Always have default plans as fallbacks *** ## Testing and Validation Ensure your tracking implementation is working correctly before going live with affiliate programs. ### Testing Procedures **Test URL Parameter Handling:** 1. Create test affiliate links with ClickKeys 2. Visit your site using these test links 3. Verify ClickKeys are captured and stored correctly 4. Test different parameter names and URL structures 5. Confirm storage persistence across page navigation **Test Complete Customer Journey:** 1. Click test affiliate link 2. Browse your site normally 3. Add products to cart 4. Complete checkout process 5. Verify ClickKey is included in transaction data 6. Confirm transaction is sent to Affelios correctly **Validate API Communication:** 1. Test transaction submission endpoints 2. Verify authentication is working 3. Test error handling and retry logic 4. Validate data format and required fields 5. Test both individual and batch submissions **Confirm Commission Attribution:** 1. Submit test transactions through API 2. Check Affelios dashboard for commission records 3. Verify commission amounts match expected rates 4. Test different commission plan scenarios 5. Validate attribution timing and processing ### Common Implementation Issues **Symptoms:** * Affiliate links working but no attribution * Missing ClickKey data in transaction submissions * No commissions being generated **Troubleshooting:** * Verify URL parameter configuration matches affiliate links * Check JavaScript console for errors * Test with different browsers and privacy settings * Ensure proper parameter parsing and storage * Validate server-side parameter handling **Symptoms:** * ClickKeys captured but lost during customer journey * Partial attribution for some transactions * Inconsistent commission attribution **Solutions:** * Implement multiple storage methods (session, cookie, database) * Increase cookie expiration times * Add ClickKey persistence across customer login * Test cross-device and return customer scenarios * Implement backup attribution methods **Symptoms:** * Transactions not appearing in Affelios * API errors or authentication failures * Delayed or missing commission processing **Resolution:** * Verify API endpoint URLs and authentication tokens * Check API response status codes and error messages * Implement proper error handling and retry logic * Validate JSON data format and required fields * Test with Affelios sandbox environment first *** ## Security and Compliance Implement proper security measures to protect customer data and ensure compliance with privacy regulations. ### Data Security Requirements **Security Measures:** * Store ClickKeys securely in your database * Use encrypted connections (HTTPS) for all tracking * Implement access controls for attribution data * Regular security audits of tracking implementation * Secure API token management **Data Retention:** * Define retention policies for attribution data * Implement data purging for expired attributions * Comply with customer data deletion requests * Maintain audit logs for attribution activities **GDPR Compliance:** * Obtain proper consent for tracking cookies * Provide clear privacy notices about affiliate tracking * Support customer data deletion requests * Implement data portability for attribution data **Privacy-First Alternatives:** * Server-side attribution storage * Account-based attribution for logged-in users * First-party cookie implementation * Consent-based tracking activation **Authentication Security:** * Use strong API tokens and rotate regularly * Implement IP whitelisting for API access * Use HTTPS for all API communications * Monitor API usage for suspicious activity **Data Transmission Security:** * Encrypt sensitive data in API payloads * Implement request signing for data integrity * Use secure token storage and management * Regular security audits of API integration *** ## Performance Optimization Optimize your tracking implementation for performance and scalability as your affiliate program grows. ### Performance Best Practices **Minimize Page Load Impact:** * Load tracking scripts asynchronously * Use lightweight ClickKey capture methods * Implement lazy loading for non-critical tracking * Optimize cookie and storage operations **Database Performance:** * Index ClickKey and customer ID columns * Implement efficient attribution lookup queries * Use database connection pooling * Consider read replicas for reporting queries **API Performance:** * Implement batch transaction submissions * Use asynchronous API calls where possible * Implement request queuing for high volume * Add monitoring and alerting for API performance **High-Volume Considerations:** * Plan for batch processing of transactions * Implement queue systems for API submissions * Design for horizontal scaling of tracking infrastructure * Monitor performance metrics and bottlenecks **Infrastructure Scaling:** * Load balancing for tracking endpoints * Database sharding for large attribution datasets * Auto-scaling for transaction processing * Monitoring and alerting for system health *** ## Next Steps and Resources Ready to implement Affelios tracking on your website? Use these resources to ensure a successful integration. **Technical Documentation:** * 📚 **API reference:** API Reference - Complete API documentation and endpoints * 🔐 **Authentication:** API Authentication - API authentication setup and security * 🧩 **Platform integrations:** Shopify Integration - E-commerce platform integration examples * 🔗 **Tracking setup:** PPC Tracking with GTM - Advanced tracking implementations **Testing & Support:** * 🧪 **Testing guide:** Testing Guide - Comprehensive testing procedures and tools * 🔧 **Troubleshooting:** Tracking Issues - Common problems and solutions * ⚡ **Best practices:** Best Practices - Integration guidelines and optimization tips * 📊 **Analytics:** Reporting & Analytics - Monitor your tracking implementation performance Start with a simple implementation using session-based ClickKey storage and immediate API submission. You can add more sophisticated features like database storage and batch processing as your program scales.