Record important website conversions and connect them to the marketing that drove them

Quotient's tracking tag records page views and sessions automatically, but not the other things people do on your site, like clicking a button or submitting a form. Those are often the actions that matter most: requesting a demo, downloading a whitepaper, watching a video, or logging into your product.

To record these actions, you create custom events in Quotient and send them from your website. Quotient then attributes each one, often called a conversion, to the person who performed it and to the campaign content that brought them to your site, so you can measure how many conversions your marketing drove.

When your site records a custom event, Quotient includes the visitor's current session and attribution context. This lets you answer questions such as "Which campaign drove the most demo requests?" instead of stopping at clicks and page views.

This guide covers events that happen in a visitor's browser. If the conversion completes on your server instead, such as an account created in an OAuth callback, see Server-Side Conversions.

Before you begin, install Quotient website tracking on your site.

Create the Custom Event in Quotient

Open Analytics → Custom Events and click Create Custom Event. Each custom event has three fields:

• Display Name is the readable name shown in Quotient, such as "Requested Demo."
• Event ID is the value your website sends, such as requested_demo. It must start with a letter and contain only letters, numbers, and underscores.
• Description explains what the event means and when your site should send it.

The event ID cannot be changed after you create the event, although you can edit its display name and description. Choose one ID and reuse it everywhere that records the same action.

You must create the event before your website sends it. Quotient rejects an event ID that is not registered for your business.

Record the Completed Action

Send the event after the action succeeds. For example, a demo-request event should run after the form submission is accepted, not when someone first clicks the submit button.

async function handleDemoRequest(formData) {
  const response = await fetch("/api/demo-requests", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(formData),
  });

  if (!response.ok) {
    showSubmissionError();
    return;
  }

  showSuccess();

  void client.analytics.event({
    eventType: "custom",
    customEventId: "requested_demo",
  });
}

Replace requested_demo with the event ID you created in Quotient. The browser SDK sends analytics in the background, so the tracking request does not hold up the form's success state.

The example uses the client created by @quotientjs/client. In a React application, get the same client from the useQuotient() hook.

If the Form Also Adds the Person to Quotient

It's common for a form to do two things at once: identify the person and record a custom event. In that case, wait for Quotient to identify the person before recording the event:

async function handleDemoRequest(formData) {
  try {
    await client.audience.people.identify({
      emailAddress: formData.email,
      firstName: formData.firstName,
      lastName: formData.lastName,
    });
  } catch (error) {
    console.error("Failed to save lead", error);
    showSubmissionError();
    return;
  }

  showSuccess();

  void client.analytics.event({
    eventType: "custom",
    customEventId: "requested_demo",
  });
}

identify() returns only after Quotient has saved the person and added their ID to the browser client. The custom event sent immediately afterward therefore belongs to that person.

Do not send these calls together with Promise.all(). The event could reach Quotient before the person has been identified, causing it to be recorded as an event that is not linked to a known person.

If the visitor has already been identified by a tagged email link or an earlier identify() call, you only need to send the custom event.

What Quotient Records

The SDK adds context automatically. In addition to the custom event ID, Quotient records the current page, browsing session, and attribution from the visitor's utm_* and qt_* URL parameters. When the browser knows the person, their Quotient person ID is included too.

An event can still be useful when Quotient does not know the visitor's identity. Quotient can attribute it to the campaign, email, social post, and session that brought the visitor to your site, even when it cannot name the person.

Custom events do not currently accept additional event properties. Do not add form fields, email addresses, or other personal information to the analytics call. Store person information with people.identify() instead.

Test Your Event

Test from a domain included in your public API key's allowed origins:

1. Open your browser's developer tools and select Network.
2. Complete the action that should send the event.
3. Search the requests for analytics/web.
4. Select the request and confirm that its status is 200.

A 422 response usually means the customEventId does not exactly match an event registered in Quotient. Event IDs are case-sensitive. A 403 response usually means the site's domain is missing from the API key's allowed origins, or the key does not have Analytics: write permission.

Once the request succeeds, ask Quotient a question such as:

How many Requested Demo events did we record in the last 30 days, broken down by UTM source?

Tips for Useful Events

• Track completed outcomes instead of button clicks or attempted submissions.
• Use one stable event ID for the same action across your site.
• Avoid sending the same event from more than one handler, which would count one action twice.
• Upsert the person first when the same form also adds them to Quotient.

Next Steps