next-conversions-kit 🚀

Zero-Boilerplate Hybrid Conversions Setup for Meta (CAPI) & Google Ads / GA4.
Automatically handles redundant client + server tracking, SHA-256 advanced matching, and deduplication out of the box.

⚡ Quick 3-Step Setup for Any Next.js Website

1. Environment Variables (.env)

Add your credentials to your project's .env:

# Meta (Facebook) Conversions API & Pixel
NEXT_PUBLIC_META_PIXEL_ID=123456789012345
META_ACCESS_TOKEN=EAAG...your_system_user_access_token
META_TEST_EVENT_CODE=       # Optional: e.g. TEST12345 to verify in Meta Events Manager

# Google Ads & Google Analytics 4 (GA4)
NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXXXXX
GA4_API_SECRET=your_ga4_measurement_protocol_api_secret
NEXT_PUBLIC_GOOGLE_ADS_ID=AW-XXXXXXXXXX                 # Optional: for standalone Google Ads tag
NEXT_PUBLIC_GOOGLE_ADS_PURCHASE_LABEL=AbCdEfGh          # Optional: purchase conversion action label
NEXT_PUBLIC_GOOGLE_ADS_LEAD_LABEL=                      # Optional: lead conversion action label
NEXT_PUBLIC_GOOGLE_ADS_SIGNUP_LABEL=                    # Optional: sign up conversion action label

2. Add to app/layout.jsx

Mount <ConversionScripts /> and <TrackingProvider />:

import { ConversionScripts, TrackingProvider } from "next-conversions-kit/components";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        <ConversionScripts />
      </head>
      <body>
        <TrackingProvider />
        {children}
      </body>
    </html>
  );
}

What this does automatically:

• Injects Google Tag (gtag.js) with Enhanced Conversions enabled.
• Injects Meta Pixel (fbq) with <noscript> fallback.
• Listens to SPA route changes and tracks PageView / page_view seamlessly.
• Captures ad click parameters (fbclid, gclid, wbraid, gbraid) and sets standard _fbc cookies.

3. Add Hybrid API Route (app/api/conversions/route.js)

Create a one-liner API route:

import { createConversionsHandler } from "next-conversions-kit/server";

export const POST = createConversionsHandler();

🎯 Tracking Events Anywhere in Your App

Import clean tracking helpers anywhere in your client components:

import {
  trackViewContent,
  trackAddToCart,
  trackInitiateCheckout,
  trackAddPaymentInfo,
  trackPurchase,
  trackLead,
  trackContact,
  trackCompleteRegistration,
} from "next-conversions-kit/client";

1. Product View (ViewContent / view_item)

trackViewContent({
  id: "prod_123",
  title: "Premium Smart Pet Tag",
  salePrice: 499,
});

2. Add to Cart (AddToCart / add_to_cart)

trackAddToCart(
  {
    id: "prod_123",
    title: "Premium Smart Pet Tag",
    salePrice: 499,
  },
  1 // quantity
);

3. Initiate Checkout (InitiateCheckout / begin_checkout)

trackInitiateCheckout(cartItems, totalAmount);

4. Add Payment Info (AddPaymentInfo / add_payment_info)

trackAddPaymentInfo(cartItems, totalAmount, "Cashfree / Razorpay / Stripe");

5. Client Purchase (Purchase / purchase)

trackPurchase(order);

6. Lead Generation (Lead / generate_lead)

trackLead("newsletter_subscription", { email: "[email protected]" });
// or
trackContact({ name: "John Doe", email: "[email protected]", subject: "Inquiry" });

7. User Registration (CompleteRegistration / sign_up)

trackCompleteRegistration({ name: "John Doe", email: "[email protected]" });

🔒 Server-Side Tracking (Webhooks / Payment Callbacks)

When a payment webhook fires (Cashfree, Razorpay, Stripe, PayU, COD) on your backend, dispatch a server-side conversion with deduplication:

import { sendUnifiedConversionServer } from "next-conversions-kit/server";

// Inside your webhook or payment status handler:
await sendUnifiedConversionServer({
  eventName: "Purchase",
  eventId: `order_${order.id}`, // Matches client eventId for deduplication!
  userData: {
    email: order.buyer.email,
    phone: order.buyer.phone,
    name: order.buyer.name,
    city: order.address.city,
    state: order.address.state,
    zipCode: order.address.zipCode,
    country: "in",
    fbp: order.tracking?.fbp,
    fbc: order.tracking?.fbc,
    gaClientId: order.tracking?.gaClientId,
  },
  customData: {
    value: order.total,
    currency: "INR",
    content_ids: order.items.map((i) => i.id),
    contents: order.items.map((i) => ({ id: i.id, quantity: i.quantity, item_price: i.price })),
    order_id: order.id,
  },
  googleParams: {
    transaction_id: order.id,
    value: order.total,
    currency: "INR",
  },
});

📦 How to Install / Distribute This Package

You can use this package across all your company's projects in any of the following ways:

Option A: Local / Monorepo reference

npm install ./packages/next-conversions-kit

Option B: Pack as a reusable .tgz file

Run in terminal:

cd packages/next-conversions-kit
npm pack

This generates next-conversions-kit-1.0.0.tgz. You can copy this file to any project and install:

npm install ./path/to/next-conversions-kit-1.0.0.tgz

Option C: Host on GitHub Repo

Push this folder to a GitHub repository (e.g. github.com/your-org/next-conversions-kit), then install anywhere with:

npm install github:your-org/next-conversions-kit

Option D: Publish to NPM (Public or Private)

npm publish --access public
# or npm publish (for private orgs)

Then install anywhere with:

npm install next-conversions-kit