Set up an event-forwarding property

Last update: 2023-11-17
  • Created for:
  • Beginner
    Intermediate
    Developer

Learn how to use event-forwarding property using Experience Platform Web SDK data.

Event forwarding is a new type of property available in Data Collection. Event forwarding gives you the ability to send data to third-party, non-Adobe vendors straight from the Adobe Experience Platform Edge Network instead of the traditional client-side browser. Find out more about the advantages of event forwarding in the Event Forwarding overview.

To use event forwarding in Adobe Experience Platform, data must be sent to Adobe Experience Platform Edge Network first using one or more of the following three options:

NOTE

The Platform Web SDK and Platform Mobile SDK do not require deployment through tags, however, using tags to deploy these SDKs is recommended.

After completing the previous lessons in this tutorial, you should be sending data to Platform Edge Network using the Web SDK. Once the data is in Platform Edge Network, you can enable event forwarding and use an event-forwarding property to send data to non-Adobe solutions.

Learning objectives

At this end of this lesson, you will be able to:

  • Create an event-forwarding property
  • Link an event-forwarding property to a Platform Web SDK datastream
  • Understand the differences between tag property data elements and rules and event-forwarding property data elements and rules
  • Create an event-forwarding data element
  • Configure an event-forwarding rule
  • Validate an event-forwarding property is successfully sending data

Prerequisites

Create an event-forwarding property

Begin by creating an event-forwarding property:

  1. Open the Data Collection interface

  2. Select Event Forwarding from the left navigation

  3. Select New Property.
    Event Forwarding properties

  4. Name the property. In this case Server-Side - Web SDK Course

  5. Select Save.
    event-forwarding property save

Configure the datastream

For event forwarding to use the data you send to the Edge network, you must link the newly created event-forwarding property to the same datastream used to send data to Adobe solutions.

To configure Target in the datastream:

  1. Go to Data Collection interface

  2. On the left navigation, select Datastreams

  3. Select the previously created Luma Web SDK datastream

    Select the Luma Web SDK datastream

  4. Select Add Service
    Add a service to the datastream

  5. Select Event Forwarding as the Service

  6. Under the Property ID dropdown, select the name you gave to your event-forwarding property, in this case Server-Side - Web SDK Course

  7. Under the Environment ID dropdown, select the tag environment you are linking the event forwarding environment to, in this case Development

    TIP

    To send data to an event forwarding environment outside the Adobe org, select Manually enter IDs and paste in an ID. The ID is provided when you create an event-forwarding property.

  8. Select Save.

    Event Forwarding Datastream Enablement

Repeat these steps for staging and production datastreams when you are ready to promote your changes through the publishing flow.

Forward data from the Platform Edge Network to a non-Adobe solution

In this exercise you will learn how to set up an event-forwarding data element, configure an event-forwarding rule, and validate using a third-part tool called Webhook.site.

NOTE

A webhook is a way to integrate different systems in semi-real time. Webhook.site is a third-party tool that lets you easily inspect, test and automate (with the visual Custom Actions builder, or WebhookScript) any incoming HTTP request or e-mail.

IMPORTANT

You must have already created and mapped data elements to an XDM Object, as well as configured tag rules and built those changes within a library to a tag environment to proceed further. If you have not, refer to the Tags Configuration steps in the prerequisites section. Those steps ensure that data is sent to the Platform Edge Network, and from there you can configure an event-forwarding property to forward data to a non-Adobe solution.

Create an event-forwarding data element

The XDM object you previously configured using the Platform Web SDK tag extension becomes the data source for data elements in an event-forwarding property. You use the same data that you have already configured in the tag property as a data source for event-forwarding.

IMPORTANT

There is one key syntax difference when referencing XDM fields in event forwarding versus other contexts. To reference data in an event-forwarding property, the data element path must include the arc.event prefix:

  • arc stands for Adobe Response Context.
  • For example: arc.event.xdm.web.webPageDetails.URL

If this path is specified incorrectly, data is not collected.

In this exercise, you will forward the browser viewport height and the Experience Cloud ID from the XDM Object to a webhook. The XDM field path is determined by the XDM schema created during the Configure an XDM schema lesson.

TIP

You can also find the XDM object path by using your web browser network tools, filtering for /ee requests, opening the beacon Payload and drilling down to the variable you are looking for. Then right-click with your mouse and select “Copy property path”. Here is an example for the Browser Viewport Height:
Event Forwarding XDM Path

  1. Go to the Event Forwarding property you recently created

  2. On the left navigation, select Data Elements

  3. Select to Create New Data Element

    Event Forwarding New Data Element

  4. Name the data element environment.browserDetails.viewportHeight

  5. Under Extension, leave CORE

  6. Under Data Element Type, select Path

  7. Type-in the XDM Object path that contains the Browser Viewport Height arc.event.xdm.environment.browserDetails.viewportHeight

  8. Select Save

    Event Forwarding ECID path

  9. Create another data element

  10. Name it ecid

  11. Under Extension, leave CORE

  12. Under Data Element Type, select Path

  13. Type-in the XDM object path that contains the Experience Cloud ID arc.event.xdm.identityMap.ECID.0.id

  14. Select Save

    Event Forwarding ECID path

    CAUTION

    Make sure to include the arc.event. prefix in the path. Also, make sure to follow the exact case as the XDM Object field name—the ECID namespace must be in all caps.

    TIP

    When working with your own website, you can find the XDM object path with your web browser network tools, filtering for /ee requests, opening the beacon Payload and drilling down to the variable you are looking for. Then right-click with your mouse and select “Copy property path”. Here is an example for the Browser Viewport Height:
    Event Forwarding XDM Path

Install Adobe Cloud Connector extension

To send data to third-party locations, you will first install the Adobe Cloud Connector extension.

  1. Select Extensions on the left navigation

  2. Select the Catalog tab

  3. Search for the Adobe Cloud Connector, select Install

    Event Forwarding ECID path

There is no extension configuration needed. With this extension, you can now forward data to a non-Adobe solution!

Create an event-forwarding rule

There are a few main differences between configuring rules in a tag property and a rule in an event-forwarding property:

  • Events & Conditions:

    • Tags: All rules are triggered by an Event which must be specified in the rule, for example, Library Loaded - Page Top. Conditions are optional.
    • Event forwarding: It is assumed that every event sent to Platform Edge Network is a trigger to forward data. Therefore, there are no Events that must be selected in event-forwarding rules. To manage which events trigger an event-forwarding rule, you must configure conditions.
  • Data element tokenization:

    • Tags: Data element names are tokenized with a % at the beginning and end of the data element name when used in a rule. For example, %viewportHeight%.

    • Event forwarding: Data element names are tokenized with {{ at the beginning and }} at the end of the data element name when used in a rule. For example, {{viewportHeight}}.

  • Sequence of rule actions:

    • The Actions section of an event forwarding rule is always executed sequentially. Make sure the order of actions is correct when you save a rule. This execution sequence cannot be executed asynchronously like it can with tags.

To configure a rule to forward data to your webhook, you must first obtain your personal webhook:

  1. Go to Webhook.site

  2. Find Your unique URL, you will use this as the URL request in your event-forwarding rule

  3. Select Copy to clipboard

  4. Leave this window open as you will be able to validate the event forwarding data in real time being captured by Webhook

    Copy Webhook URL

  5. Go back Data Collection > Event Forwarding > Rules from the left navigation

  6. Select Create New Rule

    Event Forwarding New rule

  7. Name it all events - ad cloud connector - webhook

  8. Add an Action

  9. Under Extension, select Adobe Cloud Connector

  10. Under Action Type, select Make Fetch Call

  11. Paste your Webhook URL in the URL field

    Copy Webhook URL

  12. Under [Query Params], you will add both data elements you created earlier.

  13. On the Key column type in viewPortHeight. On the Value column, enter the {{environment.browserDetails.viewportHeight}} data element by either typing it in or selecting from the data element selector icon

  14. Select + Add Another to add another query parameter

  15. On the Key column type in ecid. On the Value column, enter the {{ecid}} data element

  16. Select Keep Changes

    Add query parameter

  17. Your rule should look like below

  18. Select Save

    Save event-forwarding rule

Create and build the library

Create a library and build all the changes to your event-forwarding development environment as you normally would in a tag property.

NOTE

If you haven’t linked Staging and Production event-forwarding properties to your datastream, you will see Development environment as the only option to build a library to.

Save event-forwarding rule

Validate event-forwarding rule

Now you can validate your event-forwarding property using the Platform Debugger, and Webhook.site:

  1. Follow the steps to switch the tag library on the Luma Demo site to the Web SDK tag property to which you mapped your event-forwarding property in the datastream.

  2. Before you reload the page, on the Experience Platform Debugger open Logs from the left navigation

  3. Select the Edge tab, then select Connect to view the Platform Edge Network requests

    Event forwarding edge network session

  4. Reload the page

  5. You will see additional requests that give you visibility into the server-side requests being sent by the Platform Edge Network to the WebHook

  6. The request to focus validation on is the one showing the fully constructed URL being sent by the Edge network

    Event forwarding debugger

  7. Note the viewPortHeight and ecid query string parameters

    Event forwarding validate query strings

  8. They match the data seen in the XDM Object

    Event forwarding matching data

  9. Lastly, validate the data matches in Webhook.site as well by viewing your open Webhook window

    Event forwarding webhook site data

Congratulations! You have configured event forwarding!

Next: Conclusion

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, share them on this Experience League Community discussion post

On this page