Visual Labeling

After enabling Autocapture on your site, you can begin to create labeled events by clicking specific elements on your site using Amplitude Data's visual labeling feature. This way, non-technical Amplitude users can create these events without needing to understand the structure of the page.

Amplitude maintains labeled events separately from events you've created in other ways. If there are issues with data for labeled events, make adjustments from within the Labeled Events tab, instead of involving your engineering team.

Prerequisites

• Amplitude Browser SDK 2.10.0 or higher
• The SDK's config.autocapture.elementInteractions option set to true. For more information, go to the Browser SDK Configuration.

Create a labeled event with visual labeling

To use Visual Labeling to create new labeled events, follow these steps:

1. Open Amplitude Data and click Visual Labeling.
2. Click the drop-down menu to either select the URL you want or add a new URL.
3. Click Start Labeling. Amplitude opens your website or app in a new tab, with the visual labeling toolbar at the top of the page.
4. Click an element you want to label. The visual labeling overlay appears.
5. In the visual labeling overlay, enter a name, description, and category for your labeled event. Select if tracking should happen when a user clicks the element, or when it changes. Visual labeling uses the clicked event by default. Refine the definition and select filters as needed.
6. Click Save. If Amplitude detects an existing event with the same or a similar definition, a warning appears before the event saves. Refer to Avoid event duplication for details. Amplitude saves the labeled event and displays a confirmation with an option to view the labeled event.
7. Repeat for each event you want to label.
8. You can select another element to continue labeling or click "Back to Amplitude" if you're done.
9. (Optional) Click Navigate to navigate to a different part of the site to label more elements on different pages.

When you're finished, return to Amplitude where you can manually update the tag, text, selector, and page URL of each labeled event.

AI-generated CSS selector

Amplitude uses AI to recommend precise CSS selectors for elements on your web page during the visual labeling process. When you click on an element to label it, Amplitude automatically suggests a selector that may best capture the intended target.

AI-generated CSS selectors appear on individual elements (such as a button) and on groups of elements (such as a list or product tiles).

The AI pre-fills the Name and Description fields using contextual understanding of the selected element. You can modify the AI-generated input for these fields at any time.

Avoid event duplication

When you save a labeled event, Amplitude checks for two types of overlap with existing events and surfaces a warning before you finalize the event:

• Same definition: Another labeled event already captures the exact same page element and interaction. Amplitude surfaces the This labeled event already exists warning. Click View to open the existing event and decide whether to use it instead of creating a new one.
• Similar page elements: Another labeled event matches similar page elements, even if the definitions aren't identical. Amplitude surfaces the Event has a similar definition warning. Click View to compare your new event to the existing events. Amplitude highlights the elements on screen that define each event so you can tell them apart.

Reviewing these warnings before saving helps you avoid duplicate coverage across your tracking plan and keeps your event taxonomy clean. If an existing event covers the same interaction, use it rather than creating a new one.

Edit a labeled event

When your site's code changes, you need to update the definition of your labeled events to match. Since Autocapture consistently captures the raw click events, you can update the definition of your labeled events and fix any gaps in your data.

To edit your labeled events, follow these steps:

1. Open Amplitude Data and click Events and then select the Labeled Events tab.
2. Select the labeled event you want to edit. In the flyout tab, click Edit.
3. If your event is no longer collecting data because of a site change, add another condition on the bottom by clicking Select action....
4. Add a new condition based on your new site structure.

Repair a labeled event

Sometimes, changes to your site's DOM break Visual Labeling's reference to the specific element on your site. You also need to repair a labeled event when an element moves to a different location or its structure changes.

Visual Labeling's repair flow preserves your event history by adding a new OR statement with a secondary definition, rather than replacing the original definition. This means all historical data remains intact while the event begins tracking the new element as well.

To repair a labeled event:

1. Open Amplitude Data and click Events in the left rail and then, in the main section, click the Labeled Events tab.
2. Select a labeled event. In the flyout tab, you can interact with:
   • A chart that depicts the number of times the event Amplitude saw over the last 30 days.
   • Charts for each definition you've added to the labeled event.
3. To repair an event that doesn't have event volume, click Repair. This opens the Visual Labeling flow with the context of the selected event.
4. Select a new element on the page to update the labeled event's definition. The repair process adds this as an additional OR condition to your existing definition, maintaining all historical data.
5. Click Save to exit the Visual Labeler and apply the updated definition.

Find misconfigured events

Amplitude provides information to let you know if a labeled event isn't working as it should.

Navigate to Data > Events, and open the Labeled Events tab. The Recency column shows the last time Amplitude tracked each event. Events that weren't seen recently may show an issue with the event definition.

Labeled events and event volume

When you enable Autocapture, Amplitude begins tracking click and page change events on your site. These events count towards your total event volume. Labeled events act like a virtual layer on top of these events, and help define a specific type of click and use that click in an analysis. As a result, labeled events don't impact event volume beyond Autocapture.

For example, a well-instrumented site may record 10,000 events each day, and Autocapture may add as many as 2,000 events each day. This means the site could experience a 20% increase in daily events. A less-instrumented site may only record 1,000 instrumented events each day. The plugin adding another 2,000 events counts as a 200% increase.

In both cases, the increase in daily events comes from tracking click and page change events. Labeled events don't impact the event count.

Limitations

• Event streams: Labeled events aren't available in live events, or in the event stream in user lookup and Session Replay. The raw Element clicked and Element changed events are visible instead.
• Google Chrome extension: The Amplitude Event Explorer Chrome extension only displays raw events from the browser, so labeled events don't appear.
• Destination event streaming: You can't send labeled events to destinations with event streaming. You can use your labeled events to define cohorts and then use cohort syncing to integrate with other destinations.
• Content Security Policy (CSP): Amplitude requires cross-tab communication between your site and Amplitude. Visual Labeling requires cross-origin-opener-policy to be unsafe-none or unset.

Troubleshooting

I don't see the visual labeling experience on my site

If the visual labeling tools don't appear on your site, check the following:

• If you have pop-up or adblocking tools enabled, they can interfere with the Visual Labeling experience. Disable the adblocker and retry.
• If the URL you entered redirects to another URL, the visual labeling experience may not load. For security reasons, the domain of the page you're labeling must match the domain you entered in Amplitude. Try using the final URL after any redirects are complete.
• Ensure Cross-Origin-Opener-Policy is set to unsafe-none or unset.