Data Mappings

[#1]

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

In this article:

Table of Contents Placeholder

About Data Mappings

Data mapping is the process of sending data from a data layer variable to the corresponding parameter in the vendor tag. This is necessary to accommodate the varied naming conventions adopted by each vendor for the data they collect. A data mapping specifies a data layer variable from a value is sourced and a vendor parameter to which the value is passed.

For example, a vendor might collect page name information 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. Once the data mapping is configured, the value of page_name will always be passed to the vendor parameter pName when that tag is triggered.

Data Layer Variable -> Vendor Parameter

When you configure a data mapping, after selecting which data layer variable contains the data you want to pass to the tag vendor (or select Custom Value), a collection of the vendor's parameters is presented where you select one more to receive the mapped value.

Variables vs. Custom Values

When adding a data mapping you have the choice between mapping a variable from your data layer or a custom value that you specify. Mapping a variable is the most common type since it allows dynamic values (different values from page to page) to be passed to the same vendor parameter. However, a custom value mapping is a convenient method for setting static vendor parameters--values that don't change from page to page. The custom value can be a standard text value or a small bit of JavaScript code whose evaluated value will be used.

Example: Variable Data Mapping

A vendor has a parameter for currency code, curr,  to be set to the three-character code matching the currency of a transaction. If the tag will be loaded on pages that handle all types of currencies you probably will have a data layer variable called site_currency or currency_code that will be set to the appropriate value based on the activity of the user. Expected values might be "USD", "CAD", "GBP", "EUR", "JPY", etc. The data mapping would look like this:

Example: Custom Value Data Mapping

If that same tag will only be deployed to a single geographic region where the currency will always be the same, such as "CAD", then a custom value data mapping can be used. In this case, a data layer variable is not necessary and the expected currency code, "CAD", can be set directly in the mapping, like this:

Example: Custom Value with JS Code

The custom value can also be JavaScript code. This option is used if you want to pass a JavaScript number, boolean, or array value to the vendor parameter. You can also enter more advanced statements or even write an inline function. In this example, the mapping will be set to "GBP" if the hostname contains "co.uk", otherwise set to "USD", using the following line of JavaScript.

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

Creating a Data Mapping

Vendor tag parameters (also called destinations) are built into the tag's Data Mappings tab, where you add and manage data mappings.

To create a new data mapping:

1. Expand a tag and in the Mapped Variables area click Edit.
2. Select a data layer variable from the Variables drop-down or click +Add Variable to use a new one.
   
3. Click Select Destination. The mapping dialog appears with the supported vendor parameters.
4. Browse the categories of vendor parameters in the left panel and check the box next to the desired destination.
   

   

5. Click Close and the new data mapping will appear.
   
6. Repeat steps #2 through #5 to map additional variables. When you are done, click Apply.

Creating a Custom Value Mapping

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

1. Expand a tag and in the Mapped Variables area click Edit.
2. Expand the Variables drop-down or click Use Custom Value.
   
3. Click Select Destination. The mapping dialog appears with the supported vendor parameters.
4. 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 even an inline function.
     
5. Browse the categories of vendor parameters in the left panel and check the box next to the desired destination.
6. Click Close and the mapped variable will appear.
7. Repeat steps #2 through #5 to map additional custom values. When you are done, click Apply.

Mapping Precedence

When two or more variables are mapped to the same destination (e.g. "page_name -> pageName" and "dom.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. The last mapping takes precedence if the variables are populated.

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

Creating a Custom Data Mapping

While the built-in destinations should cover most of your mapping needs, there is an option to define a custom mapping to send data to a vendor parameter of your naming. 

1. Follow steps 1 to 3 to create a data mapping.
2. Click +Add Custom in the top panel or +Add Custom Destination in the left panel. 
3. Type a name for the custom variable and click OK or +Add.
4. Repeat to add more custom mappings. When you are done, click Close.

The custom mapping will appear in the Data Mappings tab.

Editing a Custom Data Mapping

The destination variable can be edited by clicking its name in the top panel.  The name becomes a text field where you type the new name. Click OK to apply the changes.

Mapping an AudienceStream Attribute

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

To map an AudienceStream attribute the following requirements must be in place:

• Data Layer Enrichment 
  Your iQ profile must be populated by attributes from the matching AudienceStream profile. Those attributes will be 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 how Data Layer Enrichment works. 
• AudienceStream Capable Tag
  Tags marked as "AudienceStream Capable" have the ability to map attributes from AudienceStream to the tag's destinations. Look for the label in the tips panel or when adding it from the tag marketplace.

Managing Data Mappings

Edit a destination

1. Open the tag's settings window and click Data Mappings.
2. Click Edit next to the mapping you want to modify. The mapping dialog appears.
3. Make any of the following edits:
   
   • change the destination's name
   • map to another destination
   • remove the destination
4. Click Close. 

Repeat to edit more mappings. When your done click Apply.

Delete a destination

1. Open the tag's Data Mappings tab. Click on the trash icon next to the mapping you want to remove.
2. Click Apply to confirm.

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. The only time ordering matters is when two or more data layer variables are mapped to the same vendor destination (example below), in which case the last mapping takes precedence.

In this example, both page_name and page_title are mapped to the pageName vendor variable. If both variables have values, the one appearing lower in the list will take precedence (in this case, page_title).