Data Mappings

[#1]

This article describes how to configure tag data mappings to send data from your data layer to a vendor.

In this article:

• About Data Mappings
• Variable Mappings and Custom Value Mappings
• Example: Variable Mapping
• Example: Custom Value with Plain Text
• Example: Custom Value with JavaScript Code
• Event Mappings
• Using Data Mappings
• Create a Data Mapping
• Create a Custom Value Mapping
• Create an Event Mapping
• Create a Custom Data Mapping
• Edit a Custom Data Mapping
• Mapping an AudienceStream Attribute
• Managing Data Mappings
• Edit a Mapping
• Delete a Mapping
• Mapping Precedence
• Reorder Mappings

About Data Mappings

A data mapping is a connection between a data layer variable and a vendor tag. Data mappings determine the data a tag receives and the type of event tracking it performs.

For example, a tag might collect the page name in a parameter named pName, but your data layer might store this value in a variable named page_name. To send the value of page_name to pName, you create a data mapping. After the mapping is configured, the value of page_name will always be passed to the vendor parameter pName when that tag is triggered.

Data mappings are managed from the tag configuration. The list of supported vendor parameters is organized by category and available on the Data Mappings screen. First, you select the data layer variable to map, then choose the vendor parameter it maps to.

Variable Mappings and Custom Value Mappings

There are two types of data mappings: variable mappings and custom value mappings. A variable mapping is the most common type since it allows values from your data layer to be passed to a vendor parameter. However, a custom value mapping is a convenient method for assigning a value directly in a mapping without using an extension or a data layer variable. The custom value is plain-text that you enter or the return value of a snippet of JavaScript code.

Example: Variable Mapping

A tag vendor has a parameter for currency code, named curr , to be set to the three-character code matching the currency of a transaction. If the tag is loaded on pages that support multiple currencies, you would likely have a data layer variable called site_currency or currency_code that is set to the appropriate value for the current visitor. The expected values might be "USD", "CAD", "GBP", "EUR", "JPY", etc. The variable mapping would look like this:

Example: Custom Value with Plain Text

A tag vendor has a parameter for currency code, named curr , but the tag is only deployed to a single geographic region where the currency is always the same (such as "CAD"). In this case, a data layer variable is not necessary because the value is constant throughout the site.  The expected currency code, "CAD", can be set directly as a custom value mapping, as follows:

Example: Custom Value with JavaScript Code

The custom value can also be returned from JavaScript code. This option can be used to pass a JavaScript number, boolean, or array value to a vendor parameter. You can use advanced statements or even an inline function.

For example, the following line of JavaScript sets the mapping to "GBP" if the hostname contains "co.uk", otherwise it is set to "USD":

location.hostname.indexOf("co.uk") > -1 ? "GBP" : "USD"

To reference a data layer variable such as page_name, use the bobject. For example, b['page_name']. Learn more about the b object.

Event Mappings

An event mapping is a variable mapping that associates your event names to the vendor's event names. For example, an e-commerce tag might run specific tracking functions for each of the primary shopping actions, such as searching for products, viewing product details, adding a product to the cart, checking out, and completing a purchase.

The vendor tag might offer the following tracked events for an e-commerce site:

• viewItem
• viewSearchResult
• addToCart
• viewCart
• completeTransaction

Similarly, your data layer might track these same events using tealium_event and the following values:

• product_view
• search
• cart_add
• cart_view
• purchase

An event mapping associates the values of your event variable ( tealium_event ) to the vendor's event names and triggers the corresponding tag function.

Using Data Mappings

Create a Data Mapping

Vendor tag parameters (also called destinations) are built into the Data Mappings configuration screen for the tag. This is where you add and manage data mappings.

To create a data mapping:

1. Expand a tag to view the details for that tag.
2. Under Mapped Variables, click Edit.
3. Select a data layer variable from the Variables drop-down or click + Add Variable to use a new one.
   
4. Click + Select Destination.
   The mapping dialog displays the supported vendor parameters.
5. Browse the categories of vendor parameters in the left panel and check the box next to the desired destination.
6. Click Done.

The new data mapping displays.

Repeat Steps 2 through 6 to map additional variables.

When done, click Apply.

Create a Custom Value Mapping

To create a data mapping that uses a custom (static) value instead of a data layer variable:

1. Expand a tag to view the details for that tag.
2. Under Mapped Variables, click Edit.
3. Expand the Variables drop-down list or click Use Custom Value.
   
4. Click Select Destination.
   The mapping dialog displays the supported vendor parameters.
5. Select the type of value to set and enter a value.
   • Text: a simple text value.
   • JS Code: a native JavaScript value, such as a number, boolean, array, object, or an inline function.
     
6. Click Close.

The mapped variable displays. Repeat these steps to map additional custom values.

When done, click Apply.

Create an Event Mapping

Use an event mapping to associate your event names with the vendor's event names and corresponding tracking. First, select your event variable (typically tealium_event), then enter the event name from your data layer, then select the corresponding vendor event to trigger.

Use the following steps to map an event:

1. Expand a tag to view the details for that tag.
2. Under Mapped Variables, click Edit.
3. Select the event variable to map.
4. Click + Select Destination.
5. Under Category, find the Events section.
6. ln the Trigger field, enter the event name from your data layer.
7. In the Event drop-down, select the vendor's event to trigger.
8. Click + Add. Repeat these steps to map multiple events.
9. Click Apply.

Event mappings appear in the data mappings list in the format of EVENT_NAME:VENDOR_EVENT. For example, if you mapped the cart_add event to the vendor's event addToCart , the mapping appears as cart_add:addToCart.

Create a Custom Data Mapping

While the built-in destinations cover most of your mapping needs, you can optionally define a custom data mapping to send data to a vendor parameter that you name.

Use the following steps to create a custom data mapping:

1. Expand a tag to view the details for that tag.
2. Under Mapped Variables, click Edit.
3. Select a data layer variable from the Variables drop-down or click + Add Variable to use a new one.
4. Click + Add Custom Destination in the top panel or in the lower left panel.
5. Type a name for the custom variable.
6. Click OK in the top panel or + Add if you used the bottom panel option.
   

Repeat the steps to add more custom mappings. When complete, click Done. The custom mapping displays in the Data Mappings tab.

Edit a Custom Data Mapping

Use the following steps to edit the destination variable:

1. Expand a tag to view the details for that tag.
2. Under Mapped Variables, click Edit.
3. Click the destination variable name in the top panel.
   
   The name becomes a text field.
4. Type the new name.
   
5. Click OK to apply the changes.
6. When complete, click Done.

Mapping an AudienceStream Attribute

AudienceStream attributes are enriched attributes about your visitors that are sent back to your website for use with personalization.

Requirements

The following requirements must be in place to map an AudienceStream attribute:

• Data Layer Enrichment
  Your iQ profile must be populated by attributes from the matching AudienceStream profile. Those attributes are made available as data mappings in the variables drop-down menu. They are organized by attribute types and are clearly labeled as AudienceStream variables.
  Learn more about data layer enrichment.
• AudienceStream Capable Tags
  Tags marked as AudienceStream Capable in the tag marketplace can map attributes from AudienceStream to the tag's destinations. Look for this label in the tips panel when adding a tag. You can optionally filter your tag search results by clicking AudienceStream Capable in the left panel.

Managing Data Mappings

Edit a Mapping

Use the following steps to edit a destination for a mapped variable:

1. Expand a tag to view the details for that tag.
2. Under Mapped Variables, click Edit.
3. Click Edit next to the mapping you want to modify.
   The mapping dialog displays.
   
4. Edit any of the following:
   
   • Change the destination name
   • Map to another destination
   • Remove the destination
5. Click Done.
6. Repeat to edit more mappings.
7. When complete, click Apply.

Delete a Mapping

Use the following steps to delete a mapping:

1. Expand a tag to view the details for that tag.
2. Under Mapped Variables, click Edit.
3. Click the trash icon next to the mapping you want to remove.
   
4. Click Apply to confirm.
   

   No warning or confirmation message displays. The deleted mapping cannot be restored.

Mapping Precedence

When two or more variables are mapped to the same destination, such as page_name > pageName and Document Title > pageName, the last mapping takes precedence. Data mappings can be reordered to account for this precedence.

In this example, if both page_name and Document Title are populated, the destination variable pageName will receive the value from Document Title. If the variables are populated, the last mapping takes precedence.

If a variable does not have a value, the mapping is not applied.

Reorder Mappings

You can drag and drop data mappings in your preferred order. This is helpful if you want to order your mappings alphabetically for better organization.

Order of mapping is important when two or more data layer variables are mapped to the same vendor destination. In this case, the last mapping takes precedence.