Documentation Experience Platform Web SDK Tutorial

Set up event forwarding with Platform Web SDK data

April 26, 2024

Topics:
Web SDK,Tags,Event Forwarding

CREATED FOR:

Beginner
Intermediate
Developer

Learn how to use event forwarding with Adobe 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.

Web SDK and event forwarding diagram

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

A software license that includes event forwarding. Event forwarding is a paid feature of Data Collection. Please contact your Adobe Account Team for more details.
Event forwarding is enabled in your Experience Cloud organization.
User permission for event forwarding. (In Admin Console, under the Adobe Experience Platform Launch product, permission items forPlatforms > Edge and all Property Rights). Once granted you should see Event Forwarding in the left navigation of the Data Collection interface:
Adobe Experience Platform Web or Mobile SDK is configured to send data to Edge Network. You must have completed the following lessons of this tutorial:
- Initial Configuration
- Tags Configuration

Create an event-forwarding property

Begin by creating an event-forwarding property:

Open the Data Collection interface
Select Event Forwarding from the left navigation
Select New Property.
Name the property. In this case, Server-Side - Web SDK Course
Select Save.

Configure the datastream

For event forwarding to use the data you send to the Platform 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:

Go to Data Collection interface
On the left navigation, select Datastreams
Select the previously created Luma Web SDK: Development Environment datastream
Select Add Service
Select Event Forwarding as the Service
Under the Property ID dropdown, select the name you gave to your event-forwarding property, in this case Server-Side - Web SDK Course
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.
Select Save.

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 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:

Go to the Event Forwarding property you recently created
On the left navigation, select Data Elements
Select to Create New Data Element
Name the data element environment.browserDetails.viewportHeight
Under Extension, leave CORE
Under Data Element Type, select Path
Type-in the XDM Object path that contains the Browser Viewport Height arc.event.xdm.environment.browserDetails.viewportHeight
Select Save
Create another data element
Name it ecid
Under Extension, leave CORE
Under Data Element Type, select Path
Type-in the XDM object path that contains the Experience Cloud ID arc.event.xdm.identityMap.ECID.0.id
Select Save

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:

Install Adobe Cloud Connector extension

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

Select Extensions on the left navigation
Select the Catalog tab
Search for the Adobe Cloud Connector, select Install

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 that 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 that 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:

Go to Webhook.site
Find Your unique URL, you use this as the URL request in your event-forwarding rule
Select Copy to clipboard
Leave this window open as you will be able to validate the event forwarding data in real time being captured by Webhook
Go back Data Collection > Event Forwarding > Rules from the left navigation
Select Create New Rule
Name it all events - ad cloud connector - webhook
Add an Action
Under Extension, select Adobe Cloud Connector
Under Action Type, select Make Fetch Call
Paste your Webhook URL in the URL field
Under [Query Params], you will add both data elements you created earlier.
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
Select + Add Another to add another query parameter
On the Key column type in ecid. On the Value column, enter the {{ecid}} data element
Select Keep Changes
Your rule should look like below
Select Save

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:

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.
Before you reload the page, on the Experience Platform Debugger open Logs from the left navigation
Select the Edge tab, then select Connect to view the Platform Edge Network requests
Reload the page
You will see additional requests that give you visibility into the server-side requests being sent by the Platform Edge Network to the WebHook
The request to focus validation on is the one showing the fully constructed URL being sent by the Edge network
Note the viewPortHeight and ecid query string parameters
They match the data seen in the XDM Object
Lastly, validate the data matches in Webhook.site as well by viewing your open Webhook window

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

recommendation-more-help