Custom Events

Custom events let you track actions that are specific to your business: a quiz completion, a brochure download, a click on an outbound offer link. Once defined, a custom event behaves like any standard event: it appears in your reports, joins the customer journey, and can be sent to Meta as a conversion.

Step 1: Define the event

In your TrueTracked dashboard, go to Settings → Events. Under Custom events, enter an event name and an optional display name, then click Add event.

• Event name: the name you use in code, for example quiz_completed.
• Display name: a friendly label shown in the dashboard, for example “Quiz Completed”. If you leave it blank, TrueTracked creates one from the event name.

Naming rules

• Lowercase letters, numbers and underscores only
• 40 characters maximum
• Cannot reuse a standard event name such as product_viewed
• Cannot start with tt_, which is reserved
• Up to 25 custom events per workspace

The field corrects as you type, turning capitals into lowercase and spaces into underscores, so what you see is exactly what gets stored.

Step 2: Send the event from your site

Use trackCustom with the name you defined. This works anywhere the TrueTracked script is loaded: directly in your HTML, in a Google Tag Manager Custom HTML tag, or in your app code.

<script>
window.truetracked('trackCustom', 'quiz_completed');
</script>

To attach a value, which is useful when you later send the event to Meta as a conversion, pass value and currency:

<script>
window.truetracked('trackCustom', 'quiz_completed', {
  value: 5.00,
  currency: 'USD'
});
</script>

To fire the event on a click, attach it to the element you care about. This example tracks any click on a share button:

<script>
document.addEventListener('click', function (event) {
  if (!event.target.closest('.share-button')) return;
  window.truetracked && window.truetracked('trackCustom', 'share_clicked');
});
</script>

track and trackCustom behave identically for a defined event name, so either will work if you already use track elsewhere.

Improve ad-platform matching

If you know who the customer is when the event fires, pass their details. Meta uses them to match the event to a real person, which raises your Event Match Quality score and makes the conversion far more useful for optimisation. This is the single biggest thing you can do to improve how a custom event performs.

<script>
window.truetracked('trackCustom', 'quiz_completed', {
  value: 5.00,
  currency: 'USD',

  // Optional, but strongly recommended for match quality
  email: '[email protected]',
  phone: '+15551234567',
  first_name: 'Jane',
  last_name: 'Doe',
  city: 'Austin',
  state: 'TX',
  zip: '78701'
});
</script>

These properties work on every TrueTracked event, not only custom ones, so the same applies when you fire contact_info_submitted or purchase yourself.

Step 3: Send it to Meta (optional)

Once a custom event is recording, you can forward it to Meta as a conversion. Go to Settings → TrueSignal, open your Meta pixel, and click Configure events. Add a mapping row, pick your custom event on the left, and choose Custom event name on the right to type the name Meta should receive, for example QuizCompleted.

For conversion data, a custom event sends value and currency when you include them. Any customer details you pass are sent separately for matching, as described above. Full details in the Meta (CAPI) guide.

Pausing and deleting

• Pause: the toggle stops new events being recorded but keeps the name reserved and any Meta mapping intact. Useful while you fix a misfiring script.
• Delete: frees a slot and stops the event immediately. Data already collected is kept, but any Meta mapping using that event stops firing.

Troubleshooting

• The event is not appearing. Open your browser's Network tab, filter for event, trigger the action and read the response body. {"success":true} means it was recorded. {"success":true,"dropped":"unknown_event"} means the name is not defined.
• No request at all. The TrueTracked script is not loaded on that page, or your code runs before it. See the Pixel Installation guide.
• Names must match exactly. Check for a typo between the name in Settings and the name in your code.
• Just defined it? Wait 30–60 seconds and try again.
• Event is paused. Check the toggle in Settings → Events.