|
This article covers the following: |
Overview
Websites record many visitor actions that Wingify cannot detect on its own, such as a visitor saving their cookie preferences or signing up for a newsletter. These actions are not tied to a specific page URL or page element, so metrics that rely on page visits or element clicks cannot capture them. Many websites use a tag manager, such as Google Tag Manager (GTM) or Tealium iQ, to deploy and manage tracking scripts without editing the site’s code each time.
A tag manager also maintains a data layer, which is a structured store of information about your web pages and visitor actions. Each entry in the data layer typically consists of keys and values. For example, when a visitor signs up for a newsletter, the data layer might receive the key event with the value newsletter_signup.
Custom event mapping allows Wingify to use this information to record visitor actions without modifying your website’s code. A custom event is a visitor action that you define in Wingify, such as Newsletter signup. You can use custom events as metrics in your campaigns and reports to understand how these actions relate to visitor behavior and campaign performance.
To link a data layer action to a custom event, you create an event mapping. An event mapping is a rule that informs Wingify which activity in the data layer should be recorded as which custom event. Each rule has one or more conditions, and each condition checks whether a specific key in the data layer has a specific value. For example, a condition can check whether the key event has the value purchase. Whenever a visitor’s action sends data to the data layer that meets the conditions in your event mapping, Wingify records the custom event in your account.
Custom event mapping is available for Google Tag Manager (GTM) and Tealium iQ. To set up the event mappings connection, see Integrate Wingify with Google Tag Manager or Integrate Wingify with Tealium iQ for Advanced Visitor Targeting. Some options are available only with GTM and are marked (GTM only) in this article.
Key Benefits
- Uses existing data: Custom event mapping uses information already available in your data layer. You only need to define conditions in Wingify to specify when a custom event should be recorded. No additional code is needed.
- Supports flexible conditions: Decide when Wingify records an event. You can specify whether any one condition must be met (some) or all conditions must be met (all). With GTM, you can also match conditions across different data layer entries and check values within arrays.
Use Cases
Measure cookie preference updates: When a visitor saves their choices in a cookie banner such as OneTrust, the banner sends a OneTrustGroupsUpdated event to the data layer. Custom event mapping records this as a Wingify custom event each time it occurs. You can use the event as a metric to measure how often visitors update their preferences.
Measure newsletter signups: Configure an event mapping to detect an event such as newsletter_signup in the data layer. Wingify records the corresponding custom event each time a visitor signs up.
OneTrustGroupsUpdated and newsletter_signup are example data layer event names. Your data layer may use different names. In the event mapping, select the Wingify custom event that should be recorded when the data layer event occurs.Prerequisites
- An active Wingify account with Admin access.
- The Wingify SmartCode installed on all web pages where the events you want to capture occur.
- A tag manager (GTM or Tealium iQ) installed on your website, with your events and values already being pushed to the data layer.
Set Up Custom Event Mapping
Use custom event mapping to trigger a Wingify custom event from your data layer. For example, you can trigger an event when a visitor updates their cookie preferences or signs up for a newsletter. You define one or more conditions based on data layer keys and values, and Wingify triggers the event whenever those conditions are met.
To configure a custom event mapping:
- From the left navigation panel of the Wingify dashboard, go to the Profile menu and then select Configurations > Integrations.
- Click the tile for your tag manager (Google Tag Manager (GTM) or Tealium iQ).
- Under Active Connections, go to the Event mappings for Google Tag Manager (GTM) Data Layer or Event mappings for Tealium iQ Data Layer table.
- In the Event mappings column, click Add Event mappings. If the connection already has event mappings, click the number of event mappings instead.
The Event mappings panel opens. - Click Add Custom Event Mapping.
The Create custom event mapping panel appears. - In the Create custom event mapping panel, enter the following:
- Custom Event Name: Select the Wingify custom event you want to trigger. You can search for an event by name. If the event does not exist, click Add custom event to create it from the panel. For details about creating events, see Working with Events in Wingify.
-
Matching: Choose how Wingify evaluates the conditions:
- some: The event triggers when at least one condition matches (OR).
- all: The event triggers only when every condition matches (AND).
- (GTM only) When you select all, an additional option lets you specify where the conditions must match:
- in any event of the Datalayer: The conditions can match across different data layer entries.
-
in the same event: All conditions must match within a single data layer entry.
more information, see Match Conditions Across Data Layer Items (GTM only).
For each condition, enter the following: - (GTM only) Object or Array: Select Object for data layer items made of keys and values. Select Array for items that are lists, such as arguments. If you select Array, also enter the position of the entry in the first box, counting from 0.
For more information, see Target Array Values in the Data Layer (GTM only). - Context key: Enter the data layer key that Wingify should check, such as event. To target a key inside another key, or a key whose name contains a dot, see Target Nested Keys and Target Keys that Contain a Dot.
- Comparison operator: Select how to compare the value, such as equals or contains. For more information, see Select Condition Operators.
-
Value: Enter the value to match, such as
OneTrustGroupsUpdated. -
Add condition: For example, to record cookie preference updates, add a second condition where the key
OnetrustActiveGroupscontains the valueC0001, and set Matching to all. For GTM, also select in the same event.
- Click Create event mapping.
A confirmation message appears, and the mapping is added to the list in the Event mappings column in Active Connections.
- Choosing where the conditions must match: in any event of the Datalayer or in the same event.
- Targeting values inside arrays, using the Array option.
Configure Custom Event Conditions
The following sections describe the available condition settings and operators you can use when configuring a custom event mapping.
Select Condition Operators
For each condition, select how Wingify compares the data layer value with the value you enter.
Operator |
Triggers when |
| equals | The data layer value is exactly the value you enter. |
| does not equal | The data layer value is anything other than the value you enter. |
| is lower than | The data layer value is less than the value you enter. Use numbers only. |
| is higher than | The data layer value is greater than the value you enter. Use numbers only. |
| is included between | The data layer value falls between a lower and an upper value you enter. Use numbers only. |
| contains | The data layer value includes the text you enter. For example, if you enter C0001, the value C0001,C0002 matches, but C0002,C0003 does not. Use this operator for text values. |
| does not contain | The data layer value does not include the text you enter. For example, if you enter C0001, the value C0002,C0003 matches, but C0001,C0002 does not. Use this operator for text values. |
| is true | The data layer value is true. Use for true or false values. |
| is false | The data layer value is false. Use for true or false values. |
| is declared | The key exists in the data layer. You do not enter a value. |
| is not declared | The key does not exist in the data layer. You do not enter a value. |
Target Nested Keys
A data layer item can hold keys inside other keys. To target a nested key, enter the path to it with dots between the key names. For example, for the following item:
page: {
pageType: "HOME",
device: { type: "mobile" }
}
}-
page.pageTypehas the valueHOME. -
page.device.typehas the valuemobile.
Dot paths work only for objects and nested objects.
Target Keys that Contain a Dot
Some keys have a dot in their name, such as gtm.uniqueEventId. To target such a key, enter it inside double quotes, for example "gtm.uniqueEventId", so that Wingify does not read the dot as a path to a nested key.
Match Conditions Across Data Layer Items (GTM only)
The GTM data layer is an array that stores data layer messages. Each message can contain event information and other key-value pairs.
For example:
dataLayer.push({ event: "OneTrustGroupsUpdated" });
dataLayer.push({ OnetrustActiveGroups: ",C0001,C0002," });In this example, the two values appear in different entries:
- If Matching is set to all and you select in the same event, the conditions do not match because neither entry contains both values.
- If Matching is set to all and you select in any event of the Datalayer, the conditions can match because the required values appear across the data layer entries.
Target Array Values in the Data Layer (GTM only)
Some GTM data layer items are arrays instead of objects.
For example, items that start with arguments hold a list of values instead of key and value pairs, such as ['consent', 'default', { ad_storage: 'denied' }].
To target a key in such an item:
- In the condition row of the Create custom event mapping panel, open the Object dropdown and select Array.
- In the position field, enter the position of the object in the list, counting from 0. For example, enter 2.
- In the Context key, enter the key inside that object. For example, ad_storage.
- Select how to compare the value, then enter the Value to match. For example, denied.
Troubleshooting
Issue |
Possible cause |
Recommended solution |
| The event is not captured. | The event name or data layer key in the mapping does not match the data layer. | Check the data layer on your website and make sure the event name and keys match exactly. |
| A custom event does not trigger when Matching is set to all. | The conditions are in different data layer entries, but in the same event is selected. | For GTM, select in any event of the Datalayer if the conditions are expected to match across entries. Otherwise, ensure all required values are present in the same entry. |
| An array condition does not match. | The position is incorrect, or the expected key is not inside an object at that position. | Check the array position, counting from 0, and confirm that the key exists inside an object at that position. |
FAQs
-
Can I use custom event mapping with both Google Tag Manager and Tealium iQ?
Yes. Custom event mapping is supported for both Google Tag Manager (GTM) and Tealium iQ. However, some options, such as matching conditions across data layer entries and targeting array values, are available only for GTM.
-
Can I use transaction event mapping with Tealium iQ?
No. Transaction event mapping is available only for Google Tag Manager. For Tealium iQ, you can use custom event mapping to trigger a custom event when a purchase occurs, but it does not capture details such as the transaction ID or revenue. To capture those details, use the Wingify API or create rules in Wingify. For more information, see Configure Transaction Event in Wingify Data Platform
-
Does Wingify show an error if I map the wrong key?
No. Wingify records the values it finds under the keys you enter. Make sure you enter the correct data layer keys.
Need more help?
For further assistance or more information, contact Wingify Support.