Conversion Tracking Integration Guide

Pixel Setup

Add this script tag to your website, replacing CLIENT_UUID with your client ID (found in the Conversions tab > Setup > Pixel).

<script src="https://coppica.com/pixel/v1.js" data-client="YOUR_CLIENT_UUID"></script>

Tracking events

After the pixel loads, call the global coppica() function to track events:

// Track a purchase
coppica('track', 'purchase', { value: 99.00, ref: 'ORDER-123' })

// Track a lead
coppica('track', 'lead', { ref: 'FORM-456' })

// Track a signup
coppica('track', 'signup')

// Disable tracking (user opts out)
coppica('consent', false)

Privacy

The pixel respects Global Privacy Control (GPC). It is cookieless by default and only sets a first-party cookie (_ck_utm, 7-day expiry) when UTM parameters are present in the URL. No cross-site tracking, no fingerprinting.

Webhook / API Key Setup

Create an API key in the Conversions tab > Setup > Webhook Keys. Send conversion events as POST requests with your key as a Bearer token.

curl -X POST https://coppica.com/api/conversions/inbound \
  -H "Authorization: Bearer ck_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "utm_content": "OUTPUT_UUID_FROM_TRACKING_LINK",
    "event_type": "purchase",
    "conversion_value": 99.00,
    "currency": "USD",
    "customer_ref": "ORDER-123"
  }'

Platform Setup

// Shopify Custom Pixel
analytics.subscribe('checkout_completed', (event) => {
  coppica('track', 'purchase', {
    value: event.data.checkout.totalPrice.amount,
    ref: event.data.checkout.order.id
  })
})

<!-- In your thank-you page template -->
<script>
  document.addEventListener('DOMContentLoaded', function() {
    var orderTotal = document.querySelector('.order-total .amount')
    if (orderTotal) {
      coppica('track', 'purchase', {
        value: parseFloat(orderTotal.textContent.replace(/[^0-9.]/g, '')),
        ref: window.location.pathname.split('/').pop()
      })
    }
  })
</script>

<script>
  coppica('track', 'lead', { ref: 'ghl-funnel' })
</script>

{
  "utm_content": "{{utm_content_from_order_metadata}}",
  "event_type": "purchase",
  "conversion_value": {{charge_amount}},
  "currency": "USD",
  "customer_ref": "{{charge_id}}"
}

<script>
  // Fire on your conversion confirmation page
  coppica('track', 'purchase', {
    value: {{DL - Order Total}},
    ref: {{DL - Order ID}}
  })
</script>

Event Types

Tracking Links

Every finalized output has a Copy Link button that generates a URL with a unique utm_content parameter. This is how conversions are attributed back to specific pieces of copy.

Use tracking links in your ads and external posts only. Never use them for links within your website.

Meta Ad URL Tagging

When Heimdall flags a large chunk of revenue as Untracked, the cause is almost always missing UTM parameters on your Meta ad URLs. iOS 14+ ATT strips fbclid before the click lands, so the only signal Cortana can use to tie a click back to a specific ad is the utm_content parameter — and Meta only adds it if you tell it to.

The fix is a one-time setup in Meta Ads Manager that applies to every ad in the account.

1. Open Meta Ads Manager → Ad Account → Settings → URL Parameters

The account-level URL Parameters field applies to every ad you publish from this account, so you only set it once.

2. Paste this template

utm_source=meta&utm_medium=paid&utm_campaign={{campaign.name}}&utm_content={{ad.name}}&utm_term={{adset.name}}

Meta interpolates the {{ad.name}} macro at impression time, so every click carries the actual ad name in utm_content. That is the bridge Cortana (and the Coppica pixel) uses to tie the conversion to a specific creative.

3. Verify it’s working

After saving, click any of your ads from a fresh browser. The landing-page URL should carry ?utm_content=<your ad name> in the address bar. If it shows {{ad.name}} literally, the template isn’t saved correctly — re-check Step 1.

Existing ads inherit the new template on next edit/republish. If you want it applied to currently-running ads without waiting, edit each ad and save (no other changes needed) to force a republish.

Heimdall’s “Untracked” bucket should drop within 24-48 hours of new conversions flowing through the corrected templates. Existing untracked conversions stay untracked — you’re fixing the bleed forward, not back.

Testing

Send a test event with the test: true flag. This runs all validation without inserting into the database.

// Pixel test
coppica('track', 'purchase', { value: 1.00, ref: 'TEST', test: true })

// Webhook test
curl -X POST https://coppica.com/api/conversions/inbound \
  -H "Authorization: Bearer ck_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"utm_content": "OUTPUT_UUID", "event_type": "purchase", "test": true}'