Update readme

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://www.buckaroo.nl/media/3478/magento2_googleanalytics_icon.png" width="200px" position="center">
+  <img src="https://www.buckaroo.nl/media/osphsp1u/magento2_googleanalytics_icon.png" width="200px" position="center">
 </p>
 
 # Buckaroo Magento2 Analytics extension
@@ -22,36 +22,194 @@ php bin/magento module:enable Buckaroo_Magento2Analytics
 php bin/magento setup:upgrade
 php bin/magento setup:static-content:deploy
 ```
+
+**Prerequisites:**
+- This module requires the main [Buckaroo Magento2](https://github.com/buckaroo-it/Magento2) payment module to be installed and enabled
+- The module integrates directly with Buckaroo's payment redirect flow
+
+**How the integration works:**
+- The Analytics module extends `Buckaroo\Magento2\Controller\Redirect\Process` to add URL parameters to the success redirect
+- It hooks into `Buckaroo\Magento2\Gateway\Http\TransactionBuilder\AbstractTransactionBuilder` via a plugin to modify return URLs
+- Cookie values are automatically captured during checkout and appended to the redirect URL after payment
 ### Usage
 #### General information
 
 GA Tracking does not allocate properly the conversion source when the transaction happens cross-browser or cross-device. Visitor lands on the website from an ad campaign, goes through the order process, but the payment process takes place on a different device or browser and success page is also displayed in a different device
 In order to handle this situation, we track the Google Client ID against the order and we can trigger an enriched version of the tracking code in the success page, by adding the clientId parameter.
 
+**How it works:**
+1. During checkout, the module captures the `_ga` cookie (Google Analytics Client ID) via the `checkout_submit_all_after` event
+2. The clientId is stored in the database associated with the quote_id
+3. When Buckaroo redirects back after payment, the module automatically appends cookie values (including clientId) as URL parameters to the success page
+4. The success page URL will contain parameters like: `/checkout/onepage/success/?clientId=1234567890.0987654321&gclid=xxx&msclkid=yyy`
+5. You can then extract these values and use them in your analytics implementation (GA/UA/GTM/GA4)
+
 ### Javascript / GTM
 
-`clientId` value is passed as a parameter in the URL of the success page, part of the redirect process. This can be extracted and used in the javascript code that triggers the GA/UA/GTM/other event for the conversion.
-Standard structure of the URL is the following:
-`/checkout/onepage/success/?clientId=****/`
+The module automatically appends cookie values as URL parameters to the success page during Buckaroo's payment redirect process. The `clientId` value (and other configured parameters) are passed in the URL and can be extracted for use in your analytics tracking.
 
-**and the clientId can be extracted:**
-```
-    try{
-        currentPageUrl = window.location.href;
-        myClientId = currentPageUrl.split('clientId=')[1].split('/')[0];
-    } catch(error) {
-        myClientId = '';
-    }
+Standard structure of the URL:
+`/checkout/onepage/success/?clientId=1234567890.0987654321&gclid=xxx&msclkid=yyy`
+
+**Note:** The actual parameters depend on your configuration in the Buckaroo Analytics settings. By default, the module tracks:
+- `clientId` (from `_ga` cookie)
+- `gclid` (from `_gcl_aw` cookie - Google Ads)
+- `msclkid` (from `_uetmsclkid` cookie - Microsoft Ads)
+- `sqzllocal` (custom tracking)
+
+**Extracting the clientId from URL:**
+```javascript
+try {
+    currentPageUrl = window.location.href;
+    myClientId = currentPageUrl.split('clientId=')[1].split('/')[0];
+} catch(error) {
+    myClientId = '';
+}
 ```
 
-**and sent to GA/UA part of the tracking code:**
+#### Implementation Options:
+
+**Option 1: Universal Analytics (GA/UA) - Direct Implementation**
 
+If you're using the traditional Universal Analytics `ga()` function:
+
+```javascript
+ga('create', 'UA-XXXXX-Y', {
+    'storage': 'none',
+    'clientId': myClientId
+});
 ```
-    ga('create', 'UA-XXXXX-Y', {
-        'storage': 'none',
+
+**Option 2: Google Tag Manager (GTM) - Recommended Approach**
+
+For GTM implementations, you have two main approaches:
+
+**A) Using GTM Data Layer (Recommended)**
+
+Push the clientId to the dataLayer before your purchase event:
+
+```javascript
+// Extract clientId from URL
+try {
+    var currentPageUrl = window.location.href;
+    var myClientId = currentPageUrl.split('clientId=')[1].split('/')[0];
+
+    // Push to dataLayer
+    window.dataLayer = window.dataLayer || [];
+    window.dataLayer.push({
         'clientId': myClientId
     });
+} catch(error) {
+    console.error('Error extracting clientId:', error);
+}
 ```
+
+Then in GTM:
+1. **Create a Data Layer Variable:**
+   - Variables → New → Data Layer Variable
+   - Name: `DLV - Client ID`
+   - Data Layer Variable Name: `clientId`
+
+2. **Add to GA4 Configuration Tag:**
+   - Go to your GA4 Configuration tag
+   - Under "Fields to Set", add:
+     - Field Name: `client_id`
+     - Value: `{{DLV - Client ID}}`
+
+3. **OR Add to Purchase Event Tag:**
+   - Go to your GA4 Event tag (purchase/conversion)
+   - Under "Event Parameters", add:
+     - Parameter Name: `client_id`
+     - Value: `{{DLV - Client ID}}`
+
+**B) Using GTM Custom JavaScript Variable**
+
+1. **Create a Custom JavaScript Variable in GTM:**
+   - Variables → New → Custom JavaScript
+   - Name: `JS - Extract Client ID from URL`
+   - Code:
+   ```javascript
+   function() {
+       try {
+           var currentPageUrl = window.location.href;
+           var clientId = currentPageUrl.split('clientId=')[1].split('/')[0];
+           return clientId;
+       } catch(error) {
+           return '';
+       }
+   }
+   ```
+
+2. **Use in GA4 Tags:**
+   - In your GA4 Configuration or Event tag
+   - Add Field/Parameter:
+     - Name: `client_id`
+     - Value: `{{JS - Extract Client ID from URL}}`
+
+**Option 3: Google Analytics 4 (GA4) - Direct Implementation**
+
+If you're using gtag.js directly:
+
+```javascript
+// Extract clientId from URL
+try {
+    var currentPageUrl = window.location.href;
+    var myClientId = currentPageUrl.split('clientId=')[1].split('/')[0];
+
+    // Send to GA4
+    gtag('config', 'G-XXXXXXXXXX', {
+        'client_id': myClientId
+    });
+} catch(error) {
+    console.error('Error extracting clientId:', error);
+}
+```
+
+**Important Notes for GTM Users:**
+- The clientId should be set **before** your purchase/conversion event fires
+- For cross-device tracking, ensure the clientId is passed to both your Configuration tag AND your Purchase event
+- Test your implementation using GTM Preview mode to verify the clientId is being captured correctly
+- You can view the clientId value in GA4's DebugView to confirm it's being sent
+
+---
+
+### Technical Implementation Details
+
+#### How the Module Works with Buckaroo Magento2
+
+This module integrates seamlessly with the main Buckaroo Magento2 payment module through several key components:
+
+**1. Event Observer (`checkout_submit_all_after`):**
+- Captures the `_ga` cookie during checkout
+- Stores the clientId in the database with the associated quote_id
+- File: `Buckaroo\Magento2Analytics\Observer\Analytics`
+
+**2. Plugin on Return URL Builder:**
+- Intercepts the return URL generated by Buckaroo's payment gateway
+- Appends configured cookie values as URL parameters
+- File: `Buckaroo\Magento2Analytics\Plugin\AbstractTransactionBuilderAfterGetUrl`
+- Target: `Buckaroo\Magento2\Gateway\Http\TransactionBuilder\AbstractTransactionBuilder`
+
+**3. Controller Override:**
+- Extends Buckaroo's redirect controller
+- Ensures URL parameters are preserved during the success redirect
+- File: `Buckaroo\Magento2Analytics\Controller\Redirect\Process`
+- Extends: `Buckaroo\Magento2\Controller\Redirect\Process`
+
+**4. Cookie Parameter Service:**
+- Reads configured cookie/parameter pairs from admin settings
+- Extracts values from cookies and applies regex transformations
+- Builds the query string for the success URL
+- File: `Buckaroo\Magento2Analytics\Service\CookieParamService`
+
+**Flow:**
+```
+Checkout → Observer captures cookies → Payment redirect → 
+Plugin adds params to return URL → Buckaroo processes payment → 
+Controller redirects to success page with parameters
+```
+
+
 ### Serverside
 
 The information related to clientId is also stored in the database. And this can be used on the server side level, via the Model repository `Buckaroo\Magento2Analytics\Model\AnalyticsRepository` using the `quoteId`: