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 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:

Captures parameters from URLs coming from Lomadee shortened links
Tracks events like page views and clicks
Processes conversions when you call the sendOrder() method
Sends data asynchronously to Lomadee servers

Installation

Step 1: Include the Script

Add the script to your site’s <head> section, before the closing </head> tag:

<!DOCTYPE html>
<html>
  <head>
    <!-- Your other scripts and metas -->

    <!-- Lomadee Global Pixel - Add before </head> -->
    <script src="https://assets.lomadee.com/global/pixel.js" async></script>
  </head>
  <body>
    <!-- Page content -->
  </body>
</html>

Step 2: Initialize the Pixel

Initialize the pixel after page load. Add this code before the </body> tag:

<script>
  // Wait for the script to load completely
  window.addEventListener("load", function () {
    if (window.LomadeeGlobalPixel) {
      window.lomadeePixel = new LomadeeGlobalPixel();
      console.log("Lomadee Global Pixel initialized successfully");
    } else {
      console.error("Error: Lomadee Global Pixel failed to load");
    }
  });
</script>

Step 3: Google Tag Manager Implementation (Optional)

If you use GTM, configure it like this:

Create a new Custom HTML tag
Paste the pixel code:

<script src="https://assets.lomadee.com/global/pixel.js" async></script>
<script>
  window.addEventListener("load", function () {
    if (window.LomadeeGlobalPixel) {
      window.lomadeePixel = new LomadeeGlobalPixel();
    }
  });
</script>

Configure trigger: All Pages
Publish the container version

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:

<!-- Purchase confirmation page -->
<script>
  function sendLomadeeConversion() {
    // Check if pixel was initialized
    if (!window.lomadeePixel) {
      console.error("Lomadee Global Pixel was not initialized");
      return;
    }

    try {
      window.lomadeePixel.sendOrder({
        orderId: "ORDER-123456", // Unique order ID
        customer: {
          id: "CUST_789",
          firstName: "John",
          lastName: "Smith",
          email: "john@email.com",
          document: "12345678901",
          phone: "11999999999",
          documentType: "CPF",
        },
        items: [
          {
            id: "SKU001",
            name: "Smartphone Galaxy S23",
            imageUrl: "https://store.com/images/galaxy-s23.jpg",
            price: 159900, // $1,599.00 in cents
            listPrice: 189900, // $1,899.00 in cents (original price)
            quantity: 1,
            categories: [
              {
                id: "electronics",
                name: "Electronics",
              },
            ],
          },
        ],
        subItems: [
          {
            key: "Items",
            value: 159900, // Total product value
          },
          {
            key: "Shipping",
            value: 1590, // $15.90 in cents
          },
          {
            key: "Discounts",
            value: -3000, // $30.00 discount in cents (negative value)
          },
        ],
      });

      console.log("Conversion sent successfully!");
    } catch (error) {
      console.error("Error sending conversion:", error);
    }
  }

  // Send conversion when page loads
  window.addEventListener("load", sendLomadeeConversion);
</script>

Multiple Products Example

lomadeePixel.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
    },
  ],
});

Data Structure

orderId

string

required

Unique identifier for the order

customer

object

Show properties

firstName

string

Customer’s first name

lastName

string

Customer’s last name

string

Customer’s email address

document

string

Customer’s document number

documentType

string

Type of customer’s document

phone

string

Customer’s phone number

metadata

array

Additional customer data

items

object

required

Show properties

string

required

Product ID

name

string

required

Product name

imageUrl

string

required

Product image URL

price

number

required

Final product price in cents

listPrice

number

required

Original product price in cents

quantity

number

required

Product quantity

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:

lomadeePixel.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
    },
  ],
});

Important Notes About Discounts

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.
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.
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:

Order level (order.metadata)
Customer level (customer.metadata)
Product level (items[].metadata)
Category level (items[].categories[].metadata)

Each item in the metadata array must follow the key and value structure:

metadata: [
  {
    key: "FIELD_NAME",
    value: "FIELD_VALUE",
  },
];

Usage Examples

At order level:

{
  orderId: "123456",
  metadata: [
    {
      key: "SalesChannel",
      value: "Physical Store"
    },
    {
      key: "DeliveryType",
      value: "Pickup"
    }
  ]
}

At customer level:

{
  customer: {
    id: "CUSTOMER_ID",
    metadata: [
      {
        key: "LoyaltyPlan",
        value: "Premium"
      },
      {
        key: "Birthday",
        value: "05/15"
      }
    ]
  }
}

At product level:

{
  items: [
    {
      id: "SKU123",
      metadata: [
        {
          key: "Warranty",
          value: "12 months",
        },
        {
          key: "Manufacturer",
          value: "XYZ",
        },
      ],
    },
  ];
}

At category level:

{
  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:

// 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:

<script>
  function sendGTMLomadeeConversion() {
    // Check if pixel is loaded
    if (!window.lomadeePixel) {
      console.error("Lomadee Pixel not initialized");
      return;
    }

    // Get order data from GTM variables
    var orderId = {{Transaction ID}} || {{DLV - purchase.transaction_id}} || 'ORDER-' + Date.now();
    var customerEmail = {{DLV - customer.email}} || '';
    var customerFirstName = {{DLV - customer.first_name}} || '';
    var customerLastName = {{DLV - customer.last_name}} || '';

    // Get Enhanced Ecommerce items
    var ecommerceItems = {{Enhanced Ecommerce Items}} || [];
    var items = [];

    // Convert ecommerce items to Lomadee format
    if (ecommerceItems && ecommerceItems.length > 0) {
      items = ecommerceItems.map(function(item) {
        return {
          id: item.item_id || item.sku,
          name: item.item_name || item.name,
          imageUrl: item.image_url || '',
          price: Math.round((item.price || 0) * 100), // Convert to cents
          listPrice: Math.round((item.list_price || item.price || 0) * 100),
          quantity: parseInt(item.quantity || 1),
          categories: [{
            id: item.item_category || 'general',
            name: item.item_category || 'General'
          }]
        };
      });
    }

    // Calculate totals
    var itemsTotal = items.reduce(function(sum, item) {
      return sum + (item.price * item.quantity);
    }, 0);

    var shippingValue = Math.round(({{DLV - purchase.shipping}} || 0) * 100);
    var discountValue = -Math.round(({{DLV - purchase.discount}} || 0) * 100);

    // Send conversion
    try {
      window.lomadeePixel.sendOrder({
        orderId: orderId,
        customer: {
          id: {{DLV - customer.id}} || 'GUEST',
          firstName: customerFirstName,
          lastName: customerLastName,
          email: customerEmail,
          document: {{DLV - customer.document}} || '',
          phone: {{DLV - customer.phone}} || '',
          documentType: 'CPF'
        },
        items: items,
        subItems: [
          {
            key: "Items",
            value: itemsTotal
          },
          {
            key: "Shipping",
            value: shippingValue
          },
          {
            key: "Discounts",
            value: discountValue
          }
        ]
      });

      console.log('Lomadee conversion sent via GTM:', orderId);
    } catch (error) {
      console.error('Error sending Lomadee conversion via GTM:', error);
    }
  }

  // Execute when page loads
  if (document.readyState === 'loading') {
    document.addEventListener('DOMContentLoaded', sendGTMLomadeeConversion);
  } else {
    sendGTMLomadeeConversion();
  }
</script>

Step 3: Configure Trigger

Create a trigger that fires on purchase confirmation: Trigger Type: Custom Event or Page View Conditions:

Page URL contains “success” OR “confirmation” OR “thank-you”
OR Custom Event equals “purchase”

Step 4: DataLayer Configuration

For better integration, configure your dataLayer on the confirmation page:

// 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

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

function() {
  var purchase = {{DLV - purchase}} || {};
  var items = {{Lomadee Items Array}} || [];

  var itemsTotal = items.reduce(function(sum, item) {
    return sum + (item.price * item.quantity);
  }, 0);

  return [
    {
      key: "Items",
      value: itemsTotal
    },
    {
      key: "Shipping",
      value: Math.round((parseFloat(purchase.shipping) || 0) * 100)
    },
    {
      key: "Discounts",
      value: -Math.round((parseFloat(purchase.discount) || 0) * 100)
    }
  ];
}

Step 6: Testing in GTM

Use GTM Preview mode to test:

Enable Preview Mode in GTM
Navigate to confirmation page with test purchase
Check Console for success/error messages
Verify in Network tab that Lomadee requests are sent
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

Open DevTools (F12) on the page where you implemented the pixel
Go to Console tab and check for errors
Go to Network tab and look for:
- Script loading: pixel.js
- Requests to Lomadee domains after calling sendOrder()

Implementation Checklist

Complete Verification List

Development Environment Testing

// Function to test pixel in development
function testLomadeePixel() {
  if (!window.lomadeePixel) {
    console.error("Pixel was not initialized");
    return 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 },
    ],
  };

  try {
    window.lomadeePixel.sendOrder(testData);
    console.log("Test sent successfully!", testData);
    return true;
  } catch (error) {
    console.error("Test error:", error);
    return false;
  }
}

// Run test
// testLomadeePixel();

Error Handling

Robust Implementation

function sendSecureConversion(orderData) {
  // Validate if pixel is available
  if (typeof window.lomadeePixel === "undefined") {
    console.warn("Lomadee Pixel not loaded yet. Retrying...");

    // Retry after 2 seconds
    setTimeout(() => sendSecureConversion(orderData), 2000);
    return;
  }

  // Validate required data
  if (!orderData.orderId) {
    console.error("Error: orderId is required");
    return;
  }

  if (!orderData.items || orderData.items.length === 0) {
    console.error("Error: at least one item is required");
    return;
  }

  try {
    window.lomadeePixel.sendOrder(orderData);
    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,
      });
    }
  } catch (error) {
    console.error("Error sending Lomadee conversion:", error);

    // Optional: report error to monitoring service
    if (typeof Sentry !== "undefined") {
      Sentry.captureException(error);
    }
  }
}

Troubleshooting

Common Issues

Pixel not initializing

Symptoms:

“lomadeePixel is not defined” error in console
Script doesn’t appear in Network tab

Solutions:

Check if script is in page <head>
Check if ad blockers are active
Check if CDN is accessible
Try loading script without async temporarily

<!-- Test without async -->
<script src="https://assets.lomadee.com/global/pixel.js"></script>

Conversions not being sent

Incorrect data being sent

Advanced Debug

// 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 if pixel was initialized
  console.log("lomadeePixel initialized:", typeof window.lomadeePixel);

  // 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

// 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
            ];
            ?>
            <script>
                window.addEventListener('load', function() {
                    if (window.lomadeePixel) {
                        window.lomadeePixel.sendOrder(<?php echo json_encode($order_data); ?>);
                    }
                });
            </script>
            <?php
        }
    }
}
add_action('wp_footer', 'lomadee_pixel_checkout_success');

Shopify

// On checkout success page (checkout.liquid)
{% if checkout %}
<script>
window.addEventListener('load', function() {
    if (window.lomadeePixel) {
        window.lomadeePixel.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 %}
            ]
        });
    }
});
</script>
{% endif %}

Support

For questions or issues:

Technical documentation: Check this complete documentation
Technical support: Lomadee Help Center
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

Introduction

Implementations

​Lomadee Global Pixel

​When to Use Global Pixel

​How It Works

​Installation

​Step 1: Include the Script

​Step 2: Initialize the Pixel

​Step 3: Google Tag Manager Implementation (Optional)

​Sending Conversions

​When to Send

​Basic Implementation

​Multiple Products Example

​Data Structure

​SubItems

​Important Notes About Discounts

​Metadata

​Usage Examples

​Important Notes

​Google Tag Manager Implementation

​Step 1: Create GTM Variables

​Step 2: Create Conversion Tag

​Step 3: Configure Trigger

​Step 4: DataLayer Configuration

​Step 5: Advanced GTM Variables

​Step 6: Testing in GTM

​GTM Best Practices

​Validation and Testing

​How to Verify It’s Working

​Implementation Checklist

​Development Environment Testing

​Error Handling

​Robust Implementation

​Troubleshooting

​Common Issues

​Advanced Debug

​Important Considerations

​Platform Integration

​WordPress/WooCommerce

​Shopify

​Support

​Useful Information for Support

Lomadee Global Pixel

When to Use Global Pixel

How It Works

Installation

Step 1: Include the Script

Step 2: Initialize the Pixel

Step 3: Google Tag Manager Implementation (Optional)

Sending Conversions

When to Send

Basic Implementation

Multiple Products Example

Data Structure

SubItems

Important Notes About Discounts

Metadata

Usage Examples

Important Notes

Google Tag Manager Implementation

Step 1: Create GTM Variables

Step 2: Create Conversion Tag

Step 3: Configure Trigger

Step 4: DataLayer Configuration

Step 5: Advanced GTM Variables

Step 6: Testing in GTM

GTM Best Practices

Validation and Testing

How to Verify It’s Working

Implementation Checklist

Development Environment Testing

Error Handling

Robust Implementation

Troubleshooting

Common Issues

Advanced Debug

Important Considerations

Platform Integration

WordPress/WooCommerce

Shopify

Support

Useful Information for Support