DocumentationExperience PlatformWeb SDK Tutorial

Create tag rules

Last update: Fri May 31 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Beginner
  • Intermediate
  • Developer

Learn how to send events to the Adobe Experience Platform Edge Network with your XDM object using tag rules. A tag rule is a combination of events, conditions, and actions that tells the tag property to do something. With Platform Web SDK, rules are used to send events to Platform Edge Network with the right data.

Learning objectives

At the end of this lesson, you are able to:

  • Use a naming convention for managing rules within tags
  • Send an event with XDM fields using Update Variable and Send Event actions
  • Stack multiple sets of XDM fields across multiple rules
  • Map individual or entire array data elements to the XDM object
  • Publish a tag rule to a development library

Prerequisites

You are familiar with Data Collection tags and the Luma demo site and have completed the previous lessons in the tutorial:

Naming Conventions

To manage rules in tags, it is recommended to follow a standard naming convention. This tutorial uses a five-part naming convention:

  • [location] - [event] - [purpose] - [order]

where;

  1. location is the page or pages on the site where the rule fires
  2. event is the trigger for the rule
  3. purpose is the main action performed by the rule
  4. order is the order in which the rule should fire in relation to other rules

Create tag rules

In tags, rules are used to execute actions (fire calls) under various conditions. The Platform Web SDK tags extension includes two actions that are used in this lesson:

  • Update variable maps data elements to properties in an XDM object
  • Send Event sends the XDM object to Experience Platform Edge Network

In the rest of this lesson we:

  1. Create a rule with the Update variable action to define a “global configuration” of XDM fields.

  2. Create additional rules with the Update variable action that override our “global configuration” and contribute additional XDM fields under certain conditions (for example, adding product details on product pages).

  3. Create another rule with the Send Event action, which will send the complete XDM object to Adobe Experience Platform Edge Network.

All of these rules will be sequenced properly using the “order” option.

This video gives an overview of the process:

https://video.tv.adobe.com/v/3427710/?learn=on

Global configuration fields

To create a tag rule for the global XDM fields:

  1. Open the tag property that you are using for this tutorial

  2. Go to Rules in the left navigation

  3. Select the Create New Rule button

    Create a rule

  4. Name the rule all pages - library loaded - set global variables - 1

  5. In the Events section, select Add

    Name the rule and add an event

  6. Use the Core Extension and select Library Loaded (Page Top) as the Event Type

  7. Select Advanced dropdown and enter 1 as the Order

    note note
    NOTE
    The lower the order number, the earlier it executes. Therefore, we give our “global configuration” a low order number.

  8. Select Keep Changes to return to the main rule screen
    Select Library Loaded Trigger

  9. In the Actions section, select Add

  10. As the Extension, select Adobe Experience Platform Web SDK

  11. As the Action Type, select Update variable

  12. As the Data element, select the xdm.variable.content you created in the Create data elements lesson

    Update Variable Schema

Now, map your data elements to the schema used by your XDM object. You can map to individual properties or entire objects. In this example, you map to individual properties:

  1. Find the eventType field and select it

  2. Enter the value web.webpagedetails.pageViews

    note tip
    TIP
    To understand what values to populate in the eventType field, you must go to the schema page and select the eventType field to view the suggested values on the right rail. You can also enter a new value, if needed.
    eventType suggested values on the schemas page

  3. Next, find the identityMap object in the schema and select it

  4. Map to the identityMap.loginID data element

    Update variable identity map

    note tip
    TIP
    XDM fields will not be included in the network request if the data element is null. Therefore, when the user is not authenticated and the identityMap.loginID data element is null, the identityMap object will not be sent. This is why we can define it in our “global configuration”.

  5. Scroll down until you reach the web object

  6. Select to open it

  7. Map the following data elements to the corresponding web XDM variables

    • web.webPageDetials.name to %page.pageInfo.pageName%
    • web.webPageDetials.server to %page.pageInfo.server%
    • web.webPageDetials.siteSection to %page.pageInfo.hierarchie1%

  8. Set web.webPageDetials.pageViews.value to 1

    Update variable content

    note tip
    TIP
    While neither eventType set to web.webpagedetails.pageViews nor web.webPageDetails.pageViews.value are required for Adobe Analytics to process a beacon as a page view, it is useful to have a standard way to indicate a page view for other downstream applications.

  9. Select Keep Changes and then Save the rule in the next screen to finish creating the rule

Product page fields

Now, start to use Update variable in additional, sequenced rules to enrich the XDM object before sending it to Platform Edge Network.

TIP
Rule order determines which rule runs first when an event is triggered. If two rules have the same event type, the one with the lowest number runs first.

Start by tracking product views on the product detail page of Luma:

  1. Select Add Rule

  2. Name it ecommerce - library loaded - set product details variables - 20

  3. Select the + symbol under Event to add a new trigger

  4. Under Extension, select Core

  5. Under Event Type, select Library Loaded (Page Top)

  6. Select to open Advanced Options, type in 20. This order value ensures the rule runs after the all pages - library loaded - set global variables - 1 which sets the global configuration.

  7. Select Keep changes

    Analytics XDM rules

  8. Under Conditions, select to Add

  9. Leave Logic Type as Regular

  10. Leave Extension as Core

  11. Select Condition Type as Path Without Query String

  12. On the right, enable the Regex toggle

  13. Under path equals set /products/. For the Luma demo site, it ensures the rule only triggers on product pages

  14. Select Keep Changes

    Analytics XDM rules

  15. Under Actions select Add

  16. Select Adobe Experience Platform Web SDK extension

  17. Select Action Type as Update variable

  18. Select xdm.variable.content as the Data element

  19. Scroll down to the commerce object

  20. Open the productViews object and set value to 1

    set up Product View

    note tip
    TIP
    Setting commerce.productViews.value=1 in XDM automatically maps to the prodView event in Analytics

  21. Scroll down to eventType and set it to commerce.productViews

    note note
    NOTE
    Because this rule has a higher order, it will overwrite the eventType set in the “global configuration” rule. eventType can only contain one value and we recommend setting it with the most valuable event.

  22. Scroll down to and select productListItems array

  23. Select Provide individual items

  24. Select Add Item

    Setting product view event

    note caution
    CAUTION
    The productListItems is an array data type so it expects data to come in as a collection of elements. Because of the Luma demo site’s data layer structure and because it’s only possible to view one product at a time on the Luma site, you add items individually. When implementing on your own website, depending on your data layer structure, you may be able to provide an entire array.

  25. Select to open Item 1

  26. Map productListItems.item1.SKU to %product.productInfo.sku%

    Product SKU XDM object Variable

  27. Select Keep Changes

  28. Select Save to save the rule

Shopping cart fields

You can map entire array to an XDM object, provided the array matches the format of the XDM schema. The custom code data element cart.productInfo you created earlier loops through the digitalData.cart.cartEntries data layer object on Luma and translates it into the required format of the productListItems object of the XDM schema.

To illustrate, see the comparison below of the Luma site data layer (left) to the translated data element (right):

XDM object array format

Compare the data element to the productListItems structure (hint, it should match).

IMPORTANT
Note how numeric variables are translated, with string values in the data layer such as price and qty reformatted to numbers in the data element. These format requirements are important for data integrity in Platform and are determined during the configure schemas step. In the example, quantity uses the Integer data type.
XDM schema data type

Now, let’s map our array to the XDM object:

  1. Create a new rule named ecommerce - library loaded - set shopping cart variables - 20

  2. Select the + symbol under Event to add a new trigger

  3. Under Extension, select Core

  4. Under Event Type, select Library Loaded (Page Top)

  5. Select to open Advanced Options, type in 20

  6. Select Keep Changes

    Analytics XDM rules

  7. Under Conditions, select to Add

  8. Leave Logic Type as Regular

  9. Leave Extensions as Core

  10. Select Condition Type as Path Without Query String

  11. On the right, do not enable the Regex toggle

  12. Under path equals set /content/luma/us/en/user/cart.html. For the Luma demo site, it ensures the rule only triggers on the cart page

  13. Select Keep Changes

    Analytics XDM rules

  14. Under Actions select Add

  15. Select Adobe Experience Platform Web SDK extension

  16. Select Action Type as Update variable

  17. Select xdm.variable.content as the Data element

  18. Scroll down to the commerce object and select to open it.

  19. Open the productListViews object and set value to 1

    set up Product View

    note tip
    TIP
    Setting commerce.productListViews.value=1 in XDM automatically maps to the scView event in Analytics

  20. Select eventType and set to commerce.productListViews

  21. Scroll down to and select productListItems array

  22. Select Provide entire array

  23. Map to cart.productInfo data element

  24. Select Keep Changes

  25. Select Save to save the rule

Create two other rules for checkout and purchase following the same pattern with the below differences:

Rule name: ecommerce - library loaded - set checkout variables - 20

  1. Condition: /content/luma/us/en/user/checkout.html

  2. Set eventType to commerce.checkouts

  3. Set commerce.checkout.value to 1

    note tip
    TIP
    This is equivalent to setting scCheckout event in Analytics

Rule name: ecommerce - library loaded - set purchase variables - 20

  1. Condition: /content/luma/us/en/user/checkout/order/thank-you.html

  2. Set eventType to commerce.purchases

  3. Set commerce.purchases.value to 1

    note tip
    TIP
    This is equivalent to setting purchase event in Analytics

  4. Set commerce.order.purchaseID to the cart.orderId data element

  5. Set commerce.order.currencyCode to the hardcoded value USD

    Setting purchaseID for Analytics

    note tip
    TIP
    This is equivalent to setting s.purchaseID and s.currencyCode variables in Analytics

  6. Scroll down to and select productListItems array

  7. Select Provide entire array

  8. Map to cart.productInfo.purchase data element

  9. Select Keep Changes

  10. Select Save

When you are done, you should see the following rules created.

Analytics XDM rules

Send event rule

Now that you have set the variables, you can create the rule to send the complete XDM object to Platform Edge Network with the Send event action.

  1. On the right, select Add Rule to create another rule

  2. Name the rule all pages - library loaded - send event - 50

  3. In the Events section, select Add

  4. Use the Core Extension and select Library Loaded (Page Top) as the Event Type

  5. Select Advanced dropdown and enter 50 in Order. This will ensure this rule fires after all of the other rules you have configured (which had 1 or 20 as their Order).

  6. Select Keep Changes to return to the main rule screen
    Select Library Loaded Trigger

  7. In the Actions section, select Add

  8. As the Extension, select Adobe Experience Platform Web SDK

  9. As the Action Type, select Send event

  10. As the XDM, select the xdm.variable.content data element created in the previous lesson

  11. Select Keep Changes to return to the main rule screen

    Add the Send Event action

  12. Select Save to save the rule

    Save the rule

Publish the rules in a library

Next, publish the rule to your development environment so you can verify it works.

To create a library:

  1. Go to Publishing Flow in the left navigation

  2. Select Add Library

    Select Add Library

  3. For the Name, enter Luma Web SDK Tutorial

  4. For the Environment, select Development

  5. Select Add All Changed Resources

    note note
    NOTE
    You should see all the tag components created in previous lessons. The Core extension contains the base JavaScript required by all web tag properties.

  6. Select Save & Build for Development

    Create and build the library

The library may take a few minutes to build and when it is complete it displays a green dot to the left of the library name:

Build complete

As you can see on the Publishing Flow screen, there is a lot more to the publishing process, which is beyond the scope of this tutorial. This tutorial just uses a single library in your Development environment.

Now, you are ready to validate the data in the request using the Adobe Experience Platform Debugger.

Next Validate with Adobe Experience Platform Debugger

NOTE
Thank you for investing your time in learning about Adobe Experience Platform Web SDK. If you have questions, want to share general feedback, or have suggestions on future content, please share them on this Experience League Community discussion post
recommendation-more-help
8cbc0fd8-ca1d-433b-9c3d-bc3f113347d4