PNG Pixel

Complete guide to implement Lomadee conversion tracking PNG pixel

Lomadee PNG Pixel

The Lomadee PNG Pixel is a service that allows real-time tracking of sales conversions. It works through an HTTP request that returns a transparent 1x1 PNG pixel, enabling seamless integration invisible to users.

Installation

1. Basic Implementation

Add the pixel at the end of the checkout process, after payment confirmation:

<img
  src="https://png.lomadee.com.br/fox.png?paymentType=credit_card&orderId=12345&prod=SKU123;category;9990;1;Example%20Product&lmdeeTracking=eyJhbGc..."
  width="1"
  height="1"
  style="display:none;"
  alt=""
/>

2. JavaScript Implementation

function trackLomadeeConversion(transactionData) {
  const baseUrl = "https://png.lomadee.com.br/fox.png";
  const params = new URLSearchParams({
    paymentType: transactionData.paymentType,
    orderId: transactionData.orderId,
    lmdeeTracking: transactionData.lmdeeTracking,
  });

  // Add products
  transactionData.products.forEach((product) => {
    const productString = `${product.sku};${product.category};${
      product.price
    };${product.quantity};${encodeURIComponent(product.name)}`;
    params.append("prod", productString);
  });

  const pixelUrl = `${baseUrl}?${params.toString()}`;

  // Create and load pixel
  const img = new Image();
  img.width = 1;
  img.height = 1;
  img.style.display = "none";
  img.src = pixelUrl;
  document.body.appendChild(img);
}

// Usage example
trackLomadeeConversion({
  paymentType: "credit_card",
  orderId: "ORDER-123456",
  lmdeeTracking: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  products: [
    {
      sku: "SKU-001",
      category: "electronics",
      price: 29990,
      quantity: 1,
      name: "Android Smartphone",
    },
    {
      sku: "SKU-002",
      category: "accessories",
      price: 4990,
      quantity: 2,
      name: "Protective Case",
    },
  ],
});

3. Server-Side Implementation

<?php
function trackLomadeeConversion($transactionData) {
    $baseUrl = 'https://png.lomadee.com.br/fox.png';
    $params = [
        'paymentType' => $transactionData['paymentType'],
        'orderId' => $transactionData['orderId'],
        'lmdeeTracking' => $transactionData['lmdeeTracking']
    ];

    // Add products
    foreach ($transactionData['products'] as $product) {
        $productString = implode(';', [
            $product['sku'],
            $product['category'],
            $product['price'],
            $product['quantity'],
            $product['name']
        ]);
        $params['prod'][] = $productString;
    }

    // Make asynchronous request
    $url = $baseUrl . '?' . http_build_query($params);

    // Use non-blocking cURL
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_TIMEOUT, 1);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_exec($ch);
    curl_close($ch);
}
?>

Endpoint

GET /fox.png

Main endpoint for conversion tracking

Base URL: https://png.lomadee.com.br

Parameters

Required Parameters

paymentType · string · required

Payment method used in the transaction Examples: credit_card, pix, boleto, debit_card, paypal

orderId · string · required

Unique order identifier Format: Unique alphanumeric string Example: ORDER-123456789

prod · array · required

List of sold products. Each product must follow the format: sku;category;price;quantity;name Format for each product: - sku: Product SKU code - category: Product category - price: Unit price in cents (integer, e.g. 9990 for $99.90) - quantity: Quantity sold (integer) - name: Product name (URL encoded if containing special characters) Example: SKU123;electronics;29990;1;Android%20Smartphone

lmdeeTracking · string · required

JWT token containing Lomadee tracking information

How it works: This parameter is automatically added to the URL when users click on shortened links through our link redirector system. The JWT token is generated by our URL shortener and contains the tracking information needed for conversion attribution.

JWT payload structure:

{
  "utmSource": "lomadee",
  "utmMedium": "cpa", 
  "utmCampaign": "affiliate_organization_track"
}

utmCampaign format: {affiliateId}_{organizationId}_{trackId}

Note: You don’t need to generate this token manually. It’s automatically included in the URL parameters when users navigate from Lomadee shortened links to your website.

Usage Examples

Simple Sale

GET https://png.lomadee.com.br/fox.png?paymentType=credit_card&orderId=ORDER-001&prod=SKU001;electronics;19990;1;Bluetooth%20Headphones&lmdeeTracking=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Sale with Multiple Products

GET https://png.lomadee.com.br/fox.png?paymentType=pix&orderId=ORDER-002&prod=SKU001;electronics;29990;1;Smartphone&prod=SKU002;accessories;4990;2;Case&lmdeeTracking=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

cURL Example

curl -X GET "https://png.lomadee.com.br/fox.png" \
  -G \
  -d "paymentType=credit_card" \
  -d "orderId=ORDER-123" \
  -d "prod=SKU001;electronics;19990;1;Test%20Product" \
  -d "lmdeeTracking=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Responses

Success (200)

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 68
Cache-Control: no-store, no-cache, must-revalidate, proxy-revalidate
Pragma: no-cache
Expires: 0

[1x1 transparent PNG binary data]

The response contains a 1x1 transparent PNG pixel that can be displayed on the page without visual impact.

Validation Error (400)

{
  "message": "Invalid query parameters",
  "error": "BadRequest",
  "statusCode": 400
}

Possible validation errors:

• Payment type is required
• Order ID is required
• At least one product is required
• Lomadee tracking token is required
• Invalid product format. Expected: sku;category;price;quantity;name
• Product price must be a valid number
• Product quantity must be a valid integer

Internal Error (500)

{
  "message": "Internal server error",
  "error": "InternalServerError",
  "statusCode": 500
}

Price Format

Important: All prices must be sent in cents (integer values), not in decimal format. For example, a product that costs $99.90 should be sent as `9990`, and a product that costs$299.90 should be sent as 29990.

Important Considerations

Data Privacy: The pixel collects transaction data and basic browser information (User-Agent, IP). Ensure compliance with data protection laws (GDPR, CCPA).

Timeout: The system is designed to respond quickly. In case of external endpoint communication failure, the pixel will be returned normally, ensuring no impact on user experience.

Asynchronous Implementation: We recommend implementing the pixel asynchronously to avoid blocking the confirmation page loading.

Best Practices

1. Asynchronous Loading: Implement the pixel after complete page loading
2. Error Handling: Always handle possible pixel request failures
3. No Duplication: Avoid firing the same pixel multiple times for the same order
4. Local Validation: Validate data before sending to reduce 400 errors
5. URL Encoding: Always encode special characters in product names

Testing Implementation

To test if the pixel is working correctly:

1. Visual Verification: Use browser developer tools (F12) to verify the request was successful (status 200)
2. Network Tab: Monitor the Network tab to confirm the /fox.png request was executed
3. Console Logs: Check for no errors in the browser console

Monitoring

The service includes structured logging for monitoring:

• Performance metrics are automatically collected
• Validation failures are logged for debugging
• Error responses include structured error information

Support

For technical support or implementation questions, contact the Lomadee development team.