On-demand custom data, also known as remote instrumentation, allows you to collect new custom events and metadata from your web applications without writing new code or waiting for an app release.

This feature uses the Element Query method, which empowers you to target any HTML element in the DOM using a CSS selector. Once targeted, you can either:

• Create Custom Events: Trigger a new custom event when a user interacts with the element (e.g., "Click", "Hover", "View").

• Collect Custom Metadata: Scrape the value of an element's attribute (like href, src, or data-product-sku) and attach it to events as custom metadata.

Prerequisites

Before you can create an on-demand key, your account must have at least one Javascript-based Collector Configuration.

Note: If you do not have a Javascript-based Collector Configuration, the "Create a new key" option will be disabled.

How to Create a New On-Demand Key

You can create a new on-demand key from the "Mapped Keys" section of an existing alias.

1. Navigate to Settings > Custom Data.

2. Select a custom data alias from the side panel (e.g., "product_view" or "product_price").

3. In the main panel, find the Mapped Keys section.

4. Click the ADD NEW button.

5. The "Map a key to [alias name]" overlay will appear. This overlay allows you to map existing unmapped keys.

6. At the bottom of this overlay, click + Create a new key. The "Create a key for [alias name]" overlay will open.

The fields shown in this overlay depend on whether the parent alias is an "Event" or "Metadata".

Event Key Configuration

If you are creating a key for an Event alias , you will see the following fields:

• Key Name: A unique name for this key.

• Collector Configuration: A dropdown list of your available Javascript-based Collector Configurations. If you only have one, it will be pre-selected.

• Element Selector Query: The CSS selector query to identify the HTML element.

• Interaction Type: A dropdown to select the user interaction that will trigger the event. Options include interactions like "Click", "Double Click", "Hover", "View".

Metadata Key Configuration

If you are creating a key for a Metadata alias , you will see more detailed fields:

• Key Name: A unique name for this key.

• Collector Configuration: A dropdown list of your available Javascript-based Collector Configurations.

• Element Selector Query: The CSS selector query to identify the HTML element

• Element Attribute: The specific attribute of the element whose value you want to collect.

• Results Limit: A dropdown to limit how many matching elements' values are collected.

• Event Specific: A radio button to determine if this metadata should be collected all the time or only with a specific event.

  • No (Default): The metadata will be collected and attached to any event fired by the Datazoom SDK.

  • Yes: If you select "Yes" , a new dropdown will appear allowing you to select a specific Event alias. The metadata will only be collected when that specific event occurs.

How On-Demand Keys Work at Runtime

• For Event Keys: When the Datazoom SDK is loaded on your web application , it will listen for the Interaction Type (e.g., "Click") on the element(s) matching your Element Selector Query. When the user performs that action, the custom event associated with the alias is fired and collected.

• For Metadata Keys: When the Datazoom SDK is loaded and an event is fired , the SDK will find the element(s) matching your Element Selector Query. It will then get the value from the specified Element Attribute and attach that value to the fired event as custom metadata.

Editing an On-Demand Key

You can edit an on-demand key at any time.

1. In the Mapped Keys table, find the row you want to edit.

2. Click on the row, ensuring its Method is "Element Query".

3. The "View / Edit Key for [alias name]" overlay will appear.

4. You can see and edit all the previously saved values. The "Save" button will become enabled if you make changes and all fields are valid.