Event aliases and discovery

Sooner or later your code and your config disagree about what something is called. Your app sends sign_up; you configured account_created. Your conversion count sits at zero and nothing is technically broken.

Aliases fix that without a deploy.

The discovery panel

Before you go looking for a mismatch, LaunchPulse shows you one. In Settings → Tracking there’s a Detected events panel:

Your site is sending these, but they aren’t mapped to anything yet (last 30 days).

It lists event names your site is actually sending that aren’t accounted for anywhere in your config. Specifically, a name shows up here when it is:

• not your conversion event,
• not your first-value event,
• not in your extra tracked events,
• not already an alias,
• and not a $-prefixed built-in.

Each row shows the event name and how many times it arrived. On the right, one-click buttons:

The Alias to… dropdown offers your configured conversion event, your first-value event, and your tracked events — the names that already mean something in your project.

When everything is accounted for, the panel says:

Nothing unmapped — everything your site sends is accounted for.

That’s the state you want after setup. It’s also a useful thing to glance at after a deploy: a new name appearing here means someone shipped an event nobody’s measuring yet.

What an alias does

An alias maps an incoming name → your configured name. The incoming name is what your code sends; the configured name is what you set in settings.

Aliases are applied at query time. That’s the whole trick, and it has consequences worth stating plainly:

• The alias works on all past and future data, immediately. Events that arrived last month under the old name start counting the moment you save.
• Nothing is rewritten in the event store. Your raw events keep their original names — you’ll still see sign_up in the events log.
• No re-install, no re-send, no backfill.

Under the hood, your configured name expands into a match on that name plus all of its aliases. Anywhere the configured name is counted, the aliases are counted with it: the Pulse dashboard, insights event count metrics, and alert counting.

That last one matters. An alert on your conversion event will fire on aliased names too, so you don’t get a silent alerting gap while a rename works its way through your codebase.

When to use one

A rename split your history

You shipped signup for six months, then renamed it to account_created. Your funnel now has a cliff at the deploy date.

signup → account_created

One alias and the history is whole again. This is the most common reason people reach for aliases, and it’s the one where the read-time behavior really pays off — the fix is instant and retroactive.

Multiple platforms use different names

Your iOS app sends ios_purchase, your web app sends web_purchase, and you want one number.

ios_purchase   → purchase_completed
web_purchase   → purchase_completed

Both alias onto the same configured name. Your conversion count is the sum, and you can still separate the platforms in the events log because the raw names are untouched.

A third-party tool names things its own way

Some tool in your stack fires events you can’t rename — a checkout widget, a form builder, a mobile SDK. Alias its name onto yours and stop thinking about it.

Managing aliases

The panel lists each active alias as incoming → target, with a Remove button.

Twenty-four is plenty for the honest cases — renames, platform splits, third-party naming. If you’re pushing that ceiling, the real problem is probably naming discipline in the codebase, not a missing alias slot. Aliases are for reconciling history you can’t change; going forward, name events consistently and you won’t need them.

Alias or rename?

If you can change the code, changing the code is cleaner — one name, no indirection, nothing for the next person to discover. But it splits your history at the deploy, so you’ll usually want to do both: rename in code going forward, and alias the old name onto the new one so the past still counts.

If you can’t change the code — third-party tool, a mobile app version still in the wild, a client you don’t control — the alias is the whole answer.

Note that old mobile app versions keep sending the old name for as long as people run them. The alias keeps working the entire time, with no coordination needed between your release schedule and your analytics.

Where to go next

• Conversions and activation — the names aliases map onto
• Tracking events — naming events so you need fewer aliases
• Project settings — the rest of the Tracking tab
• Events log — see the raw, un-aliased names