Conversion and Event Tracking | blade47/dub Wiki | doc0

Public

Endpoint Route	HTTP Method	Validation Schema	Required Plan / Auth
`/api/track/click`	POST	`trackClickSchema`	Public (`withAxiom`)
`/api/track/visit`	POST	Request body JSON (`domain`, `url`)	Public (`withAxiom`)
`/api/track/open`	POST	`trackOpenRequestSchema`	Public (`withAxiom`)
`/api/track/lead/client`	POST	`trackLeadRequestSchema`	`["business", "advanced", "enterprise"]` (`withPublishableKey`)
`/api/track/sale/client`	POST	`trackSaleRequestSchema`	`["business", "advanced", "enterprise"]` (`withPublishableKey`)

Step Name	Function / Method	Target / Entity	Purpose
Bot Detection	`detectBot(req)`	NextRequest	Filters automated scrapers and bots
Rate Limiting	`assertRateLimit()`	Upstash Redis	Enforces `RATELIMIT_POLICIES.trackApplication` by IP
Program Identification	`identityProgramSlug(url)`	URL string	Extracts program slug and marketplace flag
Program Lookup	`prisma.program.findUnique()`	Database	Resolves program ID from slug or network constant
Event Dispatch	`trackVisitEvent()` / `trackStartEvent()`	Database & Cookies	Records marketplace application lifecycle events

Parameter	Type	Required / Optional	Purpose
`clickId`	string	Optional (coerced to empty string)	Associated visitor click identifier
`eventName`	string	Optional	Name of the conversion event
`eventQuantity`	number	Optional	Multiplier quantity for the conversion event
`customerExternalId`	string	Optional (New)	Unique external identifier for the customer
`externalId`	string	Optional (Deprecated)	Legacy fallback field for customer external identifier
`customerId`	string	Optional (Deprecated)	Legacy fallback field for customer identifier
`customerName`	string	Optional	Human-readable name of the customer
`customerEmail`	string	Optional	Email address of the customer
`customerAvatar`	string	Optional	URL to the customer's avatar image
`mode`	string	Optional	Processing mode (`wait`, `deferred`, or standard)
`metadata`	object	Optional	Custom key-value metadata associated with the lead

export const trackDubLead = async (user: User) => {
  const cookieStore = await cookies();
  const clickId = cookieStore.get("dub_id")?.value;
 
  if (!clickId) {
    console.log("No dub_id cookie found, skipping lead tracking...");
    return;
  }
 
  // send the lead event to Dub
  await dub.track.lead({
    clickId,
    eventName: "Sign Up",
    customerExternalId: user.id,
    customerName: user.name,
    customerEmail: user.email,
    customerAvatar: user.image,
  });
 
  // delete the cookies
  cookieStore.delete("dub_id");
  cookieStore.delete("dub_partner_data");
};

Parameter	Type	Required	Description
`customerExternalId`	string	Yes (or fallback)	Unique external identifier for the customer
`externalId`	string	Optional	Deprecated fallback for `customerExternalId`
`customerId`	string	Optional	Deprecated fallback for `customerExternalId`
`amount`	number	Yes	Monetary value of the sale transaction
`currency`	string	Optional	Currency code for the transaction (defaults to `"usd"`)
`eventName`	string	Optional	Name of the sale event
`paymentProcessor`	string	Optional	Payment gateway processor name (e.g. `"stripe"`, `"custom"`)
`invoiceId`	string	Optional	External invoice reference ID
`leadEventName`	string	Optional	Associated lead event name
`metadata`	object	Optional	Custom key-value metadata associated with the sale

  if (currency !== "usd") {
    const { currency: convertedCurrency, amount: convertedAmount } =
      await convertCurrency({
        currency,
        amount,
      });
 
    currency = convertedCurrency;
    amount = convertedAmount;
  }

const singularToDubEvent = {
  activated: "lead",
  sng_complete_registration: "lead",
  sng_subscribe: "sale",
  sng_ecommerce_purchase: "sale",
  __iap__: "sale", // In-app purchase
  "Copy GAID": "lead", // Singular Device Assist
  "copy IDFA": "lead", // Singular Device Assist
};

export async function attributeViaPromotionCodeId({
  promotionCodeId,
  workspace,
  mode,
  customerDetails,
}: {
  promotionCodeId: string;
  workspace: Pick<
    Project,
    "id" | "defaultProgramId" | "stripeConnectId" | "webhookEnabled"
  >;
  mode: StripeMode;
  customerDetails: PromoCodeCustomerDetails;
}) {
  const promotionCode = await getPromotionCode({
    promotionCodeId,
    stripeAccountId: workspace.stripeConnectId!,
    mode,
  });
  // ... resolves discountCode, records fake click, and creates customer
}

Integration Handler	Inbound Route / Method	Auth / Verification Mechanism	Target Entity / Action
AppsFlyer Webhook	`GET /api/appsflyer/webhook`	`APPSFLYER_IP_RANGES` validation	`trackLead()` or `trackSale()`
Singular Webhook	`GET /api/singular/webhook`	`SINGULAR_IP_RANGES` validation	`trackSingularLeadEvent()` or `trackSingularSaleEvent()`
Shopify Pixel	`POST /api/shopify/pixel`	Upstash Rate Limit & CORS headers	`shopifyCheckoutCache` & order job dispatcher
Stripe Customer Sync	Customer Webhooks (`syncCustomer`)	Stripe Signature & Metadata extraction	Prisma `Customer` upsert & lead creation
Stripe Promotion Code	Checkout Session (`attributeViaPromotionCodeId`)	Stripe Promotion ID lookup	`recordFakeClick()` & discount code mapping

Google Ads API Method	Endpoint / Query	Purpose	Return Type
`listUploadClickConversionActions`	`searchStream` (`SELECT conversion_action.id, ... WHERE conversion_action.type = UPLOAD_CLICKS AND conversion_action.status = ENABLED`)	Queries enabled upload click conversion actions for a customer	`Promise<GoogleAdsConversionAction[]>`
`uploadClickConversion`	`dataManagerFetch` (`events:ingest`)	Uploads an offline click conversion with retry handling	`Promise<{ requestId: string }>`

export async function loadReattributeEventPlan({
  oldCustomerId,
  newCustomerId,
}: {
  oldCustomerId: string;
  newCustomerId: string;
}): Promise<ReattributeEventPlan> {
  const [oldEvents, newEvents] = await Promise.all([
    getCustomerReattributeEvents(oldCustomerId),
    getCustomerReattributeEvents(newCustomerId),
  ]);
 
  if (oldEvents.length >= CUSTOMER_REATTRIBUTION_EVENTS_LIMIT) {
    throw new Error(
      `Customer ${oldCustomerId} has too many events to reattribute (limit ${CUSTOMER_REATTRIBUTION_EVENTS_LIMIT}).`,
    );
  }
 
  const sourceEvents = oldEvents.length > 0 ? oldEvents : newEvents;
  const clickEvent = sourceEvents.find((event) => event.event === "click");
  const leadEvent = sourceEvents.find((event) => event.event === "lead");
  const saleEvents = sourceEvents.filter((event) => event.event === "sale");
 
  return {
    hasClick: Boolean(clickEvent),
    hasLead: Boolean(leadEvent),
    leadCount: leadEvent ? 1 : 0,
    saleCount: saleEvents.length,
    saleAmount: saleEvents.reduce(
      (sum, event) => sum + (event.saleAmount ?? 0),
      0,
    ),
    leadTimestamp: leadEvent?.timestamp ?? null,
    saleTimestamp: saleEvents[saleEvents.length - 1]?.timestamp ?? null,
  };
}

export const POST = withWorkspace(
  async ({ req, workspace }) => {
    try {
      if (workspace.id !== FRAMER_WORKSPACE_ID) {
        throw new DubApiError({
          code: "unauthorized",
          message: "Unauthorized",
        });
      }
 
      const originalPayload = schema.parse(
        await parseRequestBody(req),
      ) as PayloadItem[];

Function Name	Source File	Purpose	Return Type
`getCustomerEvents`	`apps/web/lib/analytics/get-customer-events.ts`	Retrieves and normalizes customer click, lead, and sale events with link metadata	`Promise<ParsedEvent[]>`
`getCustomerReattributeEvents`	`apps/web/lib/api/customers/reattribute-customer.ts`	Fetches and filters customer reattribution events up to the event limit	`Promise<CustomerTBEvent[]>`
`loadReattributeEventPlan`	`apps/web/lib/api/customers/reattribute-customer.ts`	Compiles event totals, counts, and timestamps for customer reattribution	`Promise<ReattributeEventPlan>`
`recreateCustomerForReattribution`	`apps/web/lib/api/customers/reattribute-customer.ts`	Atomically updates old customer stubs and creates new reattributed customer records	`Promise<Customer>`

Conversion and Event Tracking | blade47/dub Wiki | doc0