Documentation

PixelRelay Docs

Full Meta tracking for vibe-coded apps. Two lines of code.

Why You Need Server-Side Tracking

If you're running Meta ads, the browser pixel alone isn't enough. iOS privacy restrictions, ad blockers, and cookie consent banners mean pixel-only setups miss a significant portion of actual conversions.

Meta's solution is the Conversions API (CAPI) — a server-to-server connection that sends conversion events directly from your backend to Meta, bypassing browser limitations entirely.

Setting up CAPI manually means 20–40 hours of developer time, managing access tokens, hashing PII, handling event deduplication, and maintaining server infrastructure.

Without CAPI

  • ✕Meta can't see your real conversions → higher CPAs
  • ✕Lookalike audiences built on incomplete data → worse targeting
  • ✕Can't accurately measure ROAS → bad ad spend decisions
  • ✕Leaving 20–50% of conversion signal on the table

What PixelRelay Does

PixelRelay is a Meta Conversions API proxy. One script tag gives you both browser-side pixel tracking and server-side CAPI — with automatic PII hashing, event deduplication, and zero infrastructure to manage.

1

The p.js script loads in the browser and fires Meta pixel events as normal

2

Simultaneously, PixelRelay sends a server-side copy of each event to Meta via CAPI

3

Event IDs are shared across both channels so Meta deduplicates automatically

4

Any PII you pass via identify() is SHA256-hashed client-side before leaving the browser

Integration Guide

1. Add the Script Tag

Add this to the <head> of every page:

index.html
<script src="https://YOUR_API/p.js?k=YOUR_PUBLIC_KEY" async></script>

window.pylon?.() uses optional chaining — safe to call before the script loads, calls silently no-op until ready.

2. Pageviews (Automatic)

Pageviews are tracked automatically on every page load, including SPA route changes. No manual setup needed.

3. Identify Users

Call identify() whenever you have user info — after signup, login, or form submission.

identify.js
window.pylon?.('identify', {
  email: user.email,
  first_name: user.firstName,
  last_name: user.lastName,
  phone: user.phone
})

All PII is SHA256-hashed client-side before transmission. Raw user data never reaches PixelRelay's servers. Hashed data persists in a first-party cookie for subsequent page loads.

4. Track Conversion Events

track.js
window.pylon?.('track', 'EventName', { ...params })

Events Reference

EventWhen to fire
LeadForm submission, signup
CompleteRegistrationAccount creation confirmed
PurchaseSuccessful payment
InitiateCheckoutCheckout flow started
AddToCartItem added to cart
AddToWishlistItem wishlisted
AddPaymentInfoPayment method saved
ViewContentKey page viewed
SearchSearch performed
SubscribeSubscription started
StartTrialFree trial started
ContactContact form submitted
FindLocationStore locator used
ScheduleAppointment booked
DonateDonation completed
SubmitApplicationApplication submitted
CustomizeProductProduct customised

Examples

Lead generation

signup.js
window.pylon?.('identify', { email: formData.email, first_name: formData.name })
window.pylon?.('track', 'Lead', { content_name: 'waitlist_signup' })

E-commerce purchase

purchase.js
window.pylon?.('identify', { email: customer.email, first_name: customer.firstName })
window.pylon?.('track', 'Purchase', {
  value: order.total,
  currency: 'USD',
  content_name: order.planName
})

SaaS trial start

trial.js
window.pylon?.('identify', { email: user.email })
window.pylon?.('track', 'StartTrial', {
  value: 0,
  currency: 'USD',
  content_name: 'pro_trial'
})

Framework Examples

Next.js (App Router)

app/layout.tsx
// app/layout.tsx
export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <script src=".../p.js?k=YOUR_KEY" async />
      </head>
      <body>{children}</body>
    </html>
  )
}
SignupForm.tsx
'use client'

function SignupForm() {
  const handleSubmit = async (formData) => {
    await createAccount(formData)
    window.pylon?.('identify', { email: formData.get('email') })
    window.pylon?.('track', 'Lead', { content_name: 'signup' })
  }
  return <form action={handleSubmit}>...</form>
}

React (Vite / CRA)

index.html
<head>
  <script src=".../p.js?k=YOUR_KEY" async></script>
</head>
CheckoutButton.jsx
function CheckoutButton({ cart, user }) {
  const handlePurchase = async () => {
    await processPayment(cart)
    window.pylon?.('identify', { email: user.email })
    window.pylon?.('track', 'Purchase', { value: cart.total, currency: 'USD' })
  }
  return <button onClick={handlePurchase}>Buy Now</button>
}

Plain HTML

contact.html
<script src=".../p.js?k=YOUR_KEY" async></script>

<form id="contact-form">
  <input type="email" name="email" required />
  <input type="text" name="name" />
  <button type="submit">Get in Touch</button>
</form>

<script>
  document.getElementById('contact-form').addEventListener('submit', function(e) {
    e.preventDefault()
    const data = new FormData(this)
    window.pylon?.('identify', { email: data.get('email'), first_name: data.get('name') })
    window.pylon?.('track', 'Contact', { content_name: 'contact_form' })
    this.submit()
  })
</script>

AI Agent Integration

PixelRelay is designed to be installed by AI coding agents (Cursor, Claude, Copilot, Bolt, Lovable, etc.) in a single pass.

How to use

Each project in your dashboard has a Copy Prompt button that generates a ready-to-paste prompt with your public key pre-filled. Paste it into Cursor rules, Claude projects, or any AI agent's system prompt.

Meta Pixel Skill

We also publish a standalone Meta Pixel + CAPI skill — a complete reference any AI agent can use to implement Meta tracking from scratch, with or without PixelRelay.

View & copy the skill

How to Test

Verify your PixelRelay integration is working end-to-end using Meta's Test Events tool.

1

Get your test code

In Meta Events Manager, go to your Pixel → Test Events tab. Copy the test code (e.g. TEST12345).

2

Add to PixelRelay

In your project Settings, paste the test code into the Test Events section and save. Takes up to 30 seconds to activate.

3

Generate events

Visit your site and perform actions that trigger events (page loads, form submissions, purchases). Events will be sent with the test code attached.

4

Verify in Meta

Back in Meta Events Manager → Test Events, you should see your events appearing in real-time. Check both browser and server events are being received.

5

Remove test code

Once verified, remove the test code from PixelRelay settings. Events will resume normal production tracking.

How It Works

Browser

  • p.js loads
  • Hashes PII client-side
  • Fires Meta pixel directly
↓

PixelRelay Proxy

  • Receives pre-hashed event
  • Validates API key
  • Forwards via CAPI
↓

Meta

  • Deduplicates events
  • Matches user profiles
  • Optimises ad delivery

Both channels share the same event_id — Meta deduplicates automatically

PixelRelay handles

  • Browser pixel + server-side CAPI
  • Event deduplication via shared IDs
  • SPA pageview tracking
  • CAPI payload formatting
  • Server infrastructure & uptime
  • Usage tracking & event logs

You handle

  • Adding the script tag
  • Calling identify() with user data
  • Calling track() on conversions
  • Configuring Meta credentials in dashboard

Pricing

Free Trial

14 days

No credit card required

  • Browser pixel + server-side CAPI
  • Unlimited projects
  • Unlimited events
Recommended

Pro

$9/month

Everything, forever

  • Unlimited projects & events
  • Priority support
  • Dashboard with event logs
  • Diagnostics

After your 14-day trial, upgrade to Pro to keep tracking. Events stop firing if the trial expires without an upgrade.

FAQ