Custom events

Custom events are storefront events you define yourself, beyond the standard events Máximo already tracks (page views, add to cart, checkout, and so on). You publish them from your theme, a theme app extension, a checkout or customer account extension, or a Hydrogen storefront, and Máximo delivers them to your connected data warehouse. Think a newsletter signup, a size-guide open, a wishlist add, or anything else specific to your store.

Note

Custom events are separate from the standard events covered in Storefront events overview. They aren’t sent to Google, Meta, TikTok, or Pinterest; they go only to your own connected data warehouse.

Turning it on

Go to Settings → Storefront events → Custom events and turn on the toggle. That’s the only setup needed on Máximo’s side. Once it’s on, Máximo accepts the custom events your storefront publishes.

Custom events are rolling out gradually. If you don’t see the Custom events card on that page, it isn’t available for your store yet.

Publishing custom events

Online Store theme and theme app extensions

Use Shopify’s own Shopify.analytics.publish(name, data):

Shopify.analytics.publish("newsletter_signup", { plan: "pro" });

Checkout and customer account UI extensions

Use the extension’s own shopify.analytics.publish(name, data) (lowercase, from Shopify’s extension API):

shopify.analytics.publish("newsletter_signup", { plan: "pro" });

Hydrogen storefronts

On a Hydrogen storefront, use the Máximo SDK instead. The SDK needs to be set up first, with the config URL and config key from your headless setup (Settings → Storefront architecture). Until it is, no custom event (or any other Máximo event) leaves your Hydrogen pages. Once it’s wired up, there are two ways to send a custom event:

Call track() directly, via the useMaximo() hook, with any name that isn’t one of the standard events Máximo already tracks:

import { useMaximo } from "@mthd-studio/hydrogen";

function NewsletterForm() {
  const maximo = useMaximo();

  function onSubmit() {
    maximo.track("newsletter_signup", { plan: "pro" });
  }

  // ...
}

Or forward events from Hydrogen’s own analytics system. List the event names you want forwarded on the <MaximoAnalytics /> component, prefixed with custom_:

<MaximoAnalytics customEvents={["custom_newsletter_signup"]} />

Then publish them the way you normally would with Hydrogen’s analytics:

useAnalytics().publish("custom_newsletter_signup", { plan: "pro" });

Máximo drops the leading custom_ before recording the event, so custom_newsletter_signup published this way and newsletter_signup published with maximo.track() land as the same event name.

Note

The customEvents list only applies to events published through Hydrogen’s own useAnalytics().publish("custom_...") (or <Analytics.CustomView type="custom_...">). An event published that way whose name isn’t in the list is ignored. maximo.track() calls don’t need the list: any name that isn’t a standard event is sent as a custom event.

Attaching traits to an event

To describe the shopper alongside an event, add a custom_traits key to the event’s data. Those traits are stored with that event only. See Custom traits for the details, including how to update a shopper’s profile.

Naming rules

Whatever name you publish, Máximo converts it to a consistent lowercase, underscore-separated form before storing it. For example, Signup Clicked becomes signup_clicked and my-app:Wishlist Add becomes my_app_wishlist_add. Converted names are capped at 63 characters: a name that would be longer once converted is rejected rather than cut short.

Names that match a standard Shopify or Máximo event are never treated as custom events. They’re dropped, not renamed, because that name already carries a specific meaning in your storefront data. This includes names like purchase, add_to_cart, checkout_started, page_viewed, and their common variants such as Product Added. If you hit this, rename your event to something more specific to what you’re tracking, for example promo_banner_clicked instead of clicked.

Payload limits

An event’s data (the second argument to publish or track) is limited to:

Limit	Value
Total size	16 KB
Nesting depth	5 levels
Total keys	200
Key name length	128 characters

An event over any of these limits is dropped entirely rather than trimmed, so you never end up with a silently truncated row. Keep custom event payloads to the handful of fields you actually need.

Consent

Custom events follow the same consent rules as every other storefront event Máximo captures, gated on the shopper’s Shopify Customer Privacy choice. See Consent for the details.

Where the data goes

Custom events are delivered to your connected data warehouse, if you have one connected. Each event lands in a custom_events table (your event name, plus its full data as JSON), and also gets a row in the shared tracks table alongside your other events, so you can find it either way.

If you turn on Restricted mode for a warehouse, the JSON columns on these rows are cleared there, the same as for any other event carrying JSON data.

Custom events stay inside your own data. They are never sent to Google, Meta, TikTok, or Pinterest.

Sending custom events to Google Tag Manager

If you’re also pushing Máximo’s storefront events into your own Google Tag Manager dataLayer (see your Google Tag settings), custom events can go there too. This needs both custom events and the dataLayer push turned on. With either one off, nothing is pushed.

Each custom event arrives as:

window.dataLayer.push({ event: "newsletter_signup", plan: "pro" });

event is the same converted name your event was stored under. A handful of keys are reserved and dropped from the push if you happen to use them: event, ecommerce, maximo, and anything starting with gtm..

Caution

On checkout pages, this needs the Máximo checkout tracking snippet re-pasted into Settings → Customer events → Add custom pixel. A snippet pasted before custom events shipped won’t pick this up on its own.

To keep a busy storefront from flooding your dataLayer, Máximo applies a few protections: the exact same event published twice within a second is only pushed once, no more than 50 pushes happen within any 2-second window, and no more than 200 custom events are pushed on a single page. On top of that, after the same event with the same details is pushed 10 times within 60 seconds, it’s held back for the next 60 seconds. These only affect the dataLayer push. Your data warehouse still receives every event.

Caution

Don’t set up a Google Tag Manager tag that listens for these dataLayer pushes and republishes them back through Shopify.analytics.publish. That creates a loop between Máximo and your own tag.

Custom events published from a customer account extension still reach your data warehouse, but they aren’t forwarded to the dataLayer, because Google Tag Manager has nothing to listen on there.

What’s not covered

• Very early events, on a theme. An event published before the Máximo app embed has finished loading on the page can miss the Google Tag Manager dataLayer push. Your data warehouse still receives it.
• Very early events, on Hydrogen. An event published on a visitor’s very first page view, before the SDK has finished loading its configuration, is dropped entirely.

Troubleshooting quick list

• Nothing is showing up at all. Confirm the toggle on Settings → Storefront events → Custom events is on, and that you have a data warehouse connected.
• One specific event never appears. Check its name doesn’t match a standard event (see Naming rules above), and that its data is within the payload limits.
• It’s not reaching Google Tag Manager. Confirm both the custom events toggle and your dataLayer push are on, and that checkout pages are using the current checkout tracking snippet.

See Troubleshooting for more.

Related

• Storefront events overview
• Enable tracking
• Custom traits
• Consent
• Troubleshooting