A Guide to Mobile Edge Data Collection Events for Adobe Analytics

[#1]

Whether you are just starting out with your mobile data collection or migrating from the Adobe Experience Cloud based extensions to the Edge Network extension, the sendEvent API is essential to your implementation. In this post, we will take a deeper look at the sendEvent API to understand the required and optional fields when configuring Edge data collection for Adobe Analytics.  

The sendEvent API allows you to send ExperienceEvents to the Edge Network to track events like screen views and user actions, and it will replace your trackState and trackAction calls when migrating from the ACP or solution extensions to AEP/Edge. In general, the ExperienceEvent is structured like this:

//create experience event from dictionary: 
var xdmData : [String: Any] = ["eventType" : "SampleXDMEvent", 
                              "sample": "data"] 
let experienceEvent = ExperienceEvent(xdm: xdmData) 
Edge.sendEvent(experienceEvent: experienceEvent) 

Please reference the developer documentation for more examples of the ExperienceEvent structure in other programming languages.  

Within the ExperienceEvent, you can define the eventType and pass XDM data that aligns with your schema. However, which of these fields are required for Analytics when implementing the AEP SDK?  

Required Fields 

The required parameters within the ExperienceEvent depend on the type of payload you are sending. In your schema, you should have the "web" field group enabled which contains two important subgroups:   

• webPageDetails: Fields related to screen views. 
• webInteraction: Fields related to user actions. 

A note on web fields: In this blog, we are using the "web" fields because they automatically map to the required Analytics fields. Alternatively, you can use the "appInformation" field group (as noted in this tutorial) or create a custom "appInformation" field group for your XDM payload for user-friendly mobile fields. However, these fields will need to be mapped either in data prep or processing rules to accurately configure your Analytics fields and track your screen views and user actions.  

Sending an Analytics screen view (which would replace trackState calls) requires setting the web.webPageDetails.name field in your payload:

//send screen view 
var xdmData: [String: Any] = [ 
  "web": [ 
    "webPageDetails": [ 
      "pageViews": ["value": 1], 
      "name": "ios:content:luma:us:en", 
    ], 
  ], 
] 
let experienceEvent = ExperienceEvent(xdm: xdmData) 
Edge.sendEvent(experienceEvent: experienceEvent) 

To send an Analytics user action (replacing trackAction calls), the web.webInteraction.name and web.webInteraction.type fields are required. These required fields allow Analytics to correctly identify the hit types.

//send user action 
var xdmData: [String: Any] = [ 
  "web": [ 
    "webInteraction": [ 
      "linkClicks": ["value": 1], 
      "name": "shop now", 
      "type": "other", 
    ], 
  ], 
] 
let experienceEvent = ExperienceEvent(xdm: xdmData) 
Edge.sendEvent(experienceEvent: experienceEvent)

Note that if neither the web.webPageDetails.name field or web.webInteraction.type fields are set, the payload is dropped, and Analytics ignores the hit completely. 

Recommended Fields 

With the few required parameters passed in the XDM payload, you can begin collecting mobile data for Adobe Analytics. In addition to the required parameters, consider these recommended parameters:  

• eventType: While the eventType isn't required, it is helpful to distinguish the type of hit being sent, such as, web.webPageDetails.pageViews, web.webInteraction.linkClicks, or other accepted values for eventType.   
• web.webPageDetails.pageViews.value or web.webInteraction.linkClicks.value: Setting these fields to 1 is technically not considered during Analytics processing but gives you confidence when testing the implementation and gives you flexibility in other Adobe services.  

Optional Fields 

Lastly, you may want to pass additional data with your screen views or user actions, such as user or commerce data, to enhance your data collection. You can do this by setting these schema fields in the XDM payload, as such:

//send screen view with custom data 
var xdmData: [String: Any] = [ 
  "eventType": "web.webPageDetails.pageViews", 
  "web": [ 
    "webPageDetails": [ 
      "pageViews": ["value": 1], 
      "name": "ios:content:luma:us:en", 
      "isHomePage": true, 
      "siteSection": "Home", 
    ], 
  ], 
  "_luma": [ 
    "user": [ 
      "userType": "guest", 
      "storeNumber": "A123", 
    ], 
  ],
] 
let experienceEvent = ExperienceEvent(xdm: xdmData) 
Edge.sendEvent(experienceEvent: experienceEvent) 

In conclusion, understanding the required ExperienceEvent fields will help to structure your XDM payloads correctly and mitigate data quality issues in your mobile Analytics implementation. While this post focused on mobile, the required, recommended, and optional fields hold true for Web, too.  

In the comments below, share your experiences configuring these fields for your Web SDK implementations!   

Resources: 

• Track event data 
• API Reference: sendEvent 
• Send events to Edge Network 
• Sending data to Adobe Analytics 
• Implement Adobe Analytics with Adobe Experience Platform Edge 

[#2]

Hi ageisler,

Where are you setting the XDM structure for the payload?  pageViews and linkClicks make perfect sense to me, but "_luma" has me a bit confused.

Thanks.

[#3]

Hi @Dave_hamel1 , 

We build the XDM structure in the xdmData variable with the eventType, web fields, and any other schema fields that you need to collect in the payload and then pass as xdm in the ExperienceEvent. In my examples, I'm using "_luma" to represent my tenant ID for custom fields in my schema. You should replace "_luma" with your own tenant ID and add schema paths as needed. For standard fields, you can omit the tenant ID.

Hope that helps!