> ## Documentation Index > Fetch the complete documentation index at: https://docs.lomadee.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Global Pixel > Complete guide to implement Lomadee Global Pixel for advanced conversion tracking # Lomadee Global Pixel The Lomadee Global Pixel is a complete tracking solution that offers advanced functionality for conversion tracking, events, and real-time user data collection. ## When to Use Global Pixel **Use Global Pixel when:** * You need automatic event tracking (clicks, pageviews) * You want to send detailed customer and product data * Your platform supports advanced JavaScript * You need features like custom metadata **Use [PNG Pixel](/docs/pixel/png) when:** * You want a simpler implementation * Your platform has JavaScript limitations * You only need basic conversion tracking ## How It Works The Global Pixel is an asynchronous script that automatically: 1. **Captures parameters** from URLs coming from Lomadee shortened links 2. **Tracks events** like page views and clicks 3. **Processes conversions** when you call the `sendOrder()` method 4. **Sends data** asynchronously to Lomadee servers ## Installation ### Step 1: Initialize the Pixel Add this code to your site's ``, **before the closing `` tag**: ```html theme={null} ``` `window.lomadeePixel` is always a Promise in this installation model. It can be used before or after the external script finishes loading. The initialized instance is also available as `window.lomadeePixelInstance` after the Promise resolves. Do not use `window.load` or `DOMContentLoaded` to determine whether the pixel is ready. These events describe the page lifecycle, not the asynchronous loading state of `pixel.js`. ### Step 2: Google Tag Manager Implementation (Optional) If you use GTM: 1. Create a new **Custom HTML** tag. 2. Paste the initialization code from Step 1. 3. Set the trigger to **Initialization – All Pages**. 4. Configure the tag to fire once per page. 5. Publish the container version. Existing installations that assign an instance directly to `window.lomadeePixel` remain supported and do not need to be migrated. The Promise-based contract documented here applies to new installations. ## Sending Conversions ### When to Send Call the `sendOrder()` method **only on the purchase confirmation page**, after payment is approved. **Important:** Do not send on checkout or cart pages. ### Basic Implementation On your success/confirmation page, add the conversion code: ```html theme={null} ``` ### Multiple Products Example ```javascript theme={null} window.lomadeePixel .then(function (pixel) { return pixel.sendOrder({ orderId: "ORDER-789012", customer: { id: "CUST_456", firstName: "Mary", lastName: "Johnson", email: "mary@email.com", document: "98765432100", phone: "11888888888", documentType: "CPF", }, items: [ { id: "SKU001", name: "Dell Inspiron Laptop", imageUrl: "https://store.com/laptop-dell.jpg", price: 249900, // $2,499.00 listPrice: 299900, // $2,999.00 quantity: 1, categories: [{ id: "computers", name: "Computers" }], }, { id: "SKU002", name: "Wireless Mouse", imageUrl: "https://store.com/mouse.jpg", price: 4990, // $49.90 listPrice: 5990, // $59.90 quantity: 2, categories: [{ id: "accessories", name: "Accessories" }], }, ], subItems: [ { key: "Items", value: 259880, // Total: (249900 * 1) + (4990 * 2) }, { key: "Shipping", value: 0, // Free shipping }, { key: "Discounts", value: -5000, // $50.00 general discount }, ], value: 244880, // Total order value: 259880 + 0 - 5000 }); }) .then(function (success) { console.log("Conversion result:", success); }) .catch(function (error) { console.error("Error sending conversion:", error); }); ``` ## Data Structure Unique identifier for the order Customer's first name Customer's last name Customer's email address Customer's document number Type of customer's document Customer's phone number Additional customer data Product ID Product name Product image URL Final product price in *cents* Original product price in *cents* Product quantity Product categories Category ID Category name Additional category data Additional product data Field name Field data Array containing main order values Object containing total product value Fixed key "Items" Total product value in *cents* Object containing shipping value Fixed key "Shipping" Shipping value in *cents* Object containing total discount value Fixed key "Discounts" Total discount value in *cents* Total order value in *cents*. This is the sum of all subItems values (Items + Shipping + Discounts + other fees) Additional order data Field name Field data ### SubItems The `subItems` object stores order information such as shipping, items, discounts, and other values not directly related to products. Important notes: * The total value of `Items` must reflect the final price of each product after applying discounts * Discounts applied directly to products should be reflected in each item's `price` * General order discounts (such as coupons or payment method discounts) should be included in `subItems` using the `Discounts` key * Any other type of discount, such as fees, cashback, etc., should be included in `subItems` using a key with the discount name and value Usage example: ```javascript theme={null} window.lomadeePixel.then(function (pixel) { return pixel.sendOrder({ // ... other fields ... items: [ { id: "SKU123", name: "Smartphone XYZ", price: 18999, // Final price after $100 discount listPrice: 19999, // Original price quantity: 1, // ... other item fields }, ], subItems: [ { key: "Items", value: 18999, // Total sum of items (final prices) }, { key: "Shipping", value: 1590, // Shipping in cents }, { key: "Discount", value: -1000, // General order discount in cents }, ], value: 19589, // Total order value: 18999 + 1590 - 1000 }); }); ``` #### Important Notes About Discounts 1. **Product-Specific Discounts**: These should be reflected in each product's `price` field. For example, if a product has a 10% discount, the `price` should be 90% of the `listPrice`. 2. **General Discounts**: Discounts applied at checkout (such as coupons or payment method discounts) should be included in `subItems` with the key "Discount". This discount should also be applied to the final product value. For example, if a 5% discount is applied for using a specific payment method, it should be applied to the final price of each product in the order. 3. **Commissioning**: Lomadee's commissioning algorithm considers the final value of each product (`price`), not the total order value after general discounts, for commission calculation. Therefore, it's crucial that product-specific discounts are correctly reflected in each item's `price`. For example, if a 5% discount is applied for using a specific payment method, it should be applied to each item's `price`. ### Metadata The `metadata` field is an array that allows sending custom information for specific contexts. It can be used at different levels of the order structure: 1. **Order level** (`order.metadata`) 2. **Customer level** (`customer.metadata`) 3. **Product level** (`items[].metadata`) 4. **Category level** (`items[].categories[].metadata`) Each item in the `metadata` array must follow the `key` and `value` structure: ```javascript theme={null} metadata: [ { key: "FIELD_NAME", value: "FIELD_VALUE", }, ]; ``` #### Usage Examples 1. **At order level**: ```javascript theme={null} { orderId: "123456", metadata: [ { key: "SalesChannel", value: "Physical Store" }, { key: "DeliveryType", value: "Pickup" } ] } ``` 2. **At customer level**: ```javascript theme={null} { customer: { id: "CUSTOMER_ID", metadata: [ { key: "LoyaltyPlan", value: "Premium" }, { key: "Birthday", value: "05/15" } ] } } ``` 3. **At product level**: ```javascript theme={null} { items: [ { id: "SKU123", metadata: [ { key: "Warranty", value: "12 months", }, { key: "Manufacturer", value: "XYZ", }, ], }, ]; } ``` 4. **At category level**: ```javascript theme={null} { categories: [ { id: "CATEGORY_ID", name: "Electronics", metadata: [ { key: "Type", value: "Department", }, ], }, ]; } ``` #### Important Notes * Keys must be strings and are case-sensitive * Values can be strings, numbers, or booleans * `metadata` is optional at all levels * Use this field to send additional information that may be useful for specific analyses or integrations ### Google Tag Manager Implementation If you're using GTM, you can implement the conversion tracking using GTM variables and triggers: #### Step 1: Create GTM Variables First, create these variables in GTM: **Built-in Variables:** * Enable "Enhanced Ecommerce" variables * Enable "Page URL" and "Page Path" **Custom Variables:** ```javascript theme={null} // Variable: Order ID {{Transaction ID}} or {{purchase.transaction_id}} // Variable: Customer Email {{customer_email}} or {{purchase.customer.email}} // Variable: Customer First Name {{customer_first_name}} or {{purchase.customer.first_name}} // Variable: Customer Last Name {{customer_last_name}} or {{purchase.customer.last_name}} ``` #### Step 2: Create Conversion Tag Create a new Custom HTML tag with this code: ```html theme={null} ``` #### Step 3: Configure Trigger Create a trigger that fires on purchase confirmation: **Trigger Type:** Custom Event **Conditions:** * Custom Event equals your confirmed purchase event, such as `purchase` * Fire the tag once per order #### Step 4: DataLayer Configuration For better integration, configure your dataLayer on the confirmation page: ```javascript theme={null} // Push purchase data to dataLayer dataLayer.push({ event: "purchase_completed", purchase: { transaction_id: "ORDER-123456", customer: { id: "CUST_789", email: "john@email.com", first_name: "John", last_name: "Smith", document: "12345678901", phone: "11999999999", }, shipping: 15.9, // In dollars discount: 30.0, // In dollars items: [ { item_id: "SKU001", item_name: "Smartphone Galaxy S23", price: 1599.0, // In dollars list_price: 1899.0, // In dollars quantity: 1, item_category: "Electronics", }, ], }, }); ``` #### Step 5: Advanced GTM Variables Create these custom JavaScript variables for more complex scenarios: **Variable Name:** Lomadee Items Array ```javascript theme={null} function() { var ecommerceItems = {{Enhanced Ecommerce Items}} || []; if (!ecommerceItems.length) return []; return ecommerceItems.map(function(item) { return { id: item.item_id || item.sku, name: item.item_name || item.name, imageUrl: item.image_url || 'https://example.com/default.jpg', price: Math.round((parseFloat(item.price) || 0) * 100), listPrice: Math.round((parseFloat(item.list_price || item.price) || 0) * 100), quantity: parseInt(item.quantity || 1), categories: [{ id: (item.item_category || 'general').toLowerCase(), name: item.item_category || 'General' }] }; }); } ``` **Variable Name:** Lomadee SubItems Array ```javascript theme={null} function() { var purchase = {{DLV - purchase}} || {}; var items = {{Lomadee Items Array}} || []; var itemsTotal = items.reduce(function(sum, item) { return sum + (item.price * item.quantity); }, 0); var shippingValue = Math.round((parseFloat(purchase.shipping) || 0) * 100); var discountValue = -Math.round((parseFloat(purchase.discount) || 0) * 100); return [ { key: "Items", value: itemsTotal }, { key: "Shipping", value: shippingValue }, { key: "Discounts", value: discountValue } ]; } ``` #### Step 6: Testing in GTM Use GTM Preview mode to test: 1. **Enable Preview Mode** in GTM 2. **Navigate to confirmation page** with test purchase 3. **Check Console** for success/error messages 4. **Verify in Network tab** that Lomadee requests are sent 5. **Check GTM Debug panel** for variable values #### GTM Best Practices **Variable Fallbacks:** Always provide fallback values for GTM variables to prevent errors when data is missing. **Data Format:** Ensure prices are converted from dollars to cents (multiply by 100) before sending to Lomadee. **Testing:** Use GTM's preview mode extensively to test all scenarios before publishing. ## Validation and Testing ### How to Verify It's Working 1. **Open DevTools (F12)** on the page where you implemented the pixel 2. **Go to Console tab** and check for errors 3. **Go to Network tab** and look for: * Script loading: `pixel.js` * Requests to Lomadee domains after calling `sendOrder()` ### Implementation Checklist **Basic Installation:** * [ ] Script included in page `` * [ ] Pixel initialized correctly * [ ] No errors in browser console **Conversion Implementation:** * [ ] `sendOrder()` called ONLY on confirmation page * [ ] `orderId` is unique for each order * [ ] Prices are in cents (e.g., 9990 for \$99.90) * [ ] All required fields are filled **Product Data:** * [ ] `price` represents final value after discounts * [ ] `listPrice` is original price without discount * [ ] `quantity` is an integer * [ ] Categories are filled correctly **SubItems:** * [ ] "Items" contains sum of all final products * [ ] "Shipping" contains shipping value * [ ] "Discounts" contains general discounts (negative value) * [ ] "value" contains total order value (sum of all subItems) ### Development Environment Testing ```javascript theme={null} // Function to test pixel in development function testLomadeePixel() { if (!window.lomadeePixel || typeof window.lomadeePixel.then !== "function") { console.error("Pixel initialization was not configured"); return Promise.resolve(false); } // Test data const testData = { orderId: `TEST-${Date.now()}`, // Unique ID for testing customer: { id: "TEST_CUSTOMER", firstName: "John", lastName: "Test", email: "test@example.com", document: "12345678901", phone: "11999999999", documentType: "CPF", }, items: [ { id: "TEST_SKU", name: "Test Product", imageUrl: "https://example.com/test.jpg", price: 9990, listPrice: 12990, quantity: 1, categories: [{ id: "test", name: "Test" }], }, ], subItems: [ { key: "Items", value: 9990 }, { key: "Shipping", value: 1000 }, { key: "Discounts", value: -500 }, ], value: 10490, // Total: 9990 + 1000 - 500 = 10490 }; return window.lomadeePixel .then(function (pixel) { return pixel.sendOrder(testData); }) .then(function (success) { console.log("Test result:", success, testData); return success; }) .catch(function (error) { console.error("Test error:", error); return false; }); } // Run test // testLomadeePixel(); ``` ## Error Handling ### Robust Implementation ```javascript theme={null} function sendSecureConversion(orderData) { // Validate required data if (!orderData.orderId) { console.error("Error: orderId is required"); return Promise.resolve(false); } if (!orderData.items || orderData.items.length === 0) { console.error("Error: at least one item is required"); return Promise.resolve(false); } if (!window.lomadeePixel || typeof window.lomadeePixel.then !== "function") { return Promise.reject( new Error("Lomadee Pixel initialization was not configured"), ); } return window.lomadeePixel .then(function (pixel) { return pixel.sendOrder(orderData); }) .then(function (success) { if (!success) { throw new Error("The conversion was not accepted by the pixel"); } console.log("Lomadee conversion sent:", orderData.orderId); // Optional: send event to analytics if (typeof gtag !== "undefined") { gtag("event", "lomadee_conversion_sent", { order_id: orderData.orderId, }); } return true; }) .catch(function (error) { console.error("Error sending Lomadee conversion:", error); // Optional: report error to monitoring service if (typeof Sentry !== "undefined") { Sentry.captureException(error); } return false; }); } ``` ## Troubleshooting ### Common Issues **Symptoms:** * "lomadeePixel is not defined" error in console * Script doesn't appear in Network tab **Solutions:** 1. Check if script is in page `` 2. Check if ad blockers are active 3. Check if CDN is accessible 4. Try loading script without `async` temporarily ```html theme={null} ``` **Symptoms:** * `sendOrder()` doesn't generate Network requests * No success logs in console **Solutions:** 1. Check if calling `sendOrder()` on correct page 2. Check if all required fields are filled 3. Check if prices are in cents 4. Check if there are no JavaScript errors on page **Symptoms:** * Commissions not being calculated correctly * Products don't appear in reports **Solutions:** 1. Check if `price` has final value after discounts 2. Check if `subItems.Items` is sum of all products 3. Check if not sending same `orderId` multiple times 4. Check if categories are in correct format ### Advanced Debug ```javascript theme={null} // Function for complete pixel debug function debugLomadeePixel() { console.group("Debug Lomadee Pixel"); // Check if script was loaded const script = document.querySelector('script[src*="pixel.js"]'); console.log("Script in DOM:", !!script); // Check if class is available console.log( "LomadeeGlobalPixel available:", typeof window.LomadeeGlobalPixel ); // Check the Promise contract and resolved instance console.log( "lomadeePixel Promise configured:", !!window.lomadeePixel && typeof window.lomadeePixel.then === "function", ); console.log( "lomadeePixelInstance available:", !!window.lomadeePixelInstance, ); // Check URL parameters const urlParams = new URLSearchParams(window.location.search); const hasLomadeeParams = urlParams.has("utm_source") && urlParams.get("utm_source") === "lomadee"; console.log("Lomadee parameters in URL:", hasLomadeeParams); // Check localStorage for Lomadee data const lomadeeData = localStorage.getItem("lomadeeTracking"); console.log("Lomadee data in localStorage:", !!lomadeeData); console.groupEnd(); } // Run debug // debugLomadeePixel(); ``` ## Important Considerations **Don't Duplicate Conversions:** Make sure to call `sendOrder()` only ONCE per order. Implement checks to avoid multiple sends of the same `orderId`. **Price Format:** All monetary values must be in cents. \$99.90 = 9990 cents. **Performance:** The pixel is asynchronous and doesn't block page loading. Conversion is sent in background. ## Platform Integration ### WordPress/WooCommerce ```php theme={null} // functions.php function lomadee_pixel_checkout_success() { if (is_order_received_page()) { global $wp; $order_id = absint($wp->query_vars['order-received']); $order = wc_get_order($order_id); if ($order) { // Generate order data for pixel $order_data = [ 'orderId' => $order->get_order_number(), // ... other data ]; ?> window.lomadeePixel .then(function(pixel) { return pixel.sendOrder({ orderId: "{{ checkout.order_number }}", customer: { id: "{{ checkout.customer.id }}", firstName: "{{ checkout.customer.first_name }}", lastName: "{{ checkout.customer.last_name }}", email: "{{ checkout.customer.email }}" }, items: [ {% for item in checkout.line_items %} { id: "{{ item.sku }}", name: "{{ item.title }}", price: {{ item.final_price }}, listPrice: {{ item.original_price }}, quantity: {{ item.quantity }} }{% unless forloop.last %},{% endunless %} {% endfor %} ], subItems: [ { key: "Items", value: {{ checkout.total_price | minus: checkout.shipping_price | minus: checkout.tax_price }} }, { key: "Shipping", value: {{ checkout.shipping_price }} }, { key: "Taxes", value: {{ checkout.tax_price }} } ], value: {{ checkout.total_price }} }); }) .catch(function(error) { console.error("Lomadee conversion error:", error); }); {% endif %} ``` ## Support For questions or issues: 1. **Technical documentation:** Check this complete documentation 2. **Technical support:** [Lomadee Help Center](https://suporte.lomadee.com) 3. **Direct contact:** Contact our technical team ### Useful Information for Support When contacting support, have on hand: * URL of page where pixel is implemented * Example of data being sent in `sendOrder()` * Screenshots of console errors (if any) * Browser and version being used