Attach Data to SDK Events
The attach data rule action is supported in Mobile Core starting version 2.1.8 (Launch), 2.3.5 (iOS), and 1.4.5 (Android). This action is powerful and complex and enables advanced use cases.
To use this action, we'll provide context on how events flow in the Adobe Experience Platform Mobile SDK and how they interact with the SDK's rules engine. Then, we'll show how you can use the action along with relevant examples.
In the Experience Platform Mobile SDK, events hold all data that is required by other extensions to complete their necessary actions. Events have the following properties:
Property | Description |
Type | Describes the event. Example: Analytics, Target, Lifecycle, etc. |
Source | Indicates cause of or directionality of the event. Example: request or response. |
Event data | Additional data required to define the event. Example: context data on an Analytics event. |
Extensions that register with Mobile Core will also register event listeners. A listener is defined by an event type and source combination. When the SDK event hub processes an event, it notifies all listeners that match the provided combination.
Events are created by an extension and are then dispatched to the SDK event hub. Each published rule created in Adobe Experience Platform Launch is then evaluated against the current event. Finally, the event is passed to each of the listeners for Events with this type /source combination.
Events are created and dispatched when an SDK public API is invoked. Attach data action use cases are meant to act on these types of events.
The rules engine lives in aforementioned SDK event hub. Before listeners are notified, the rules engine evaluates each Launch rule against the triggering event. A rule is defined by 3 properties:
Property | Description |
Event | Trigger for the rule. |
Condition | Definition of criteria to compare against the triggering event. |
Action | The resulting action to happen if evaluation of rule is positive. |
A rule may be read out loud like so: If SDK Event occurs and Condition(s) are met, then perform the Action(s).
Attach Data is a type of Rule Action that allows you to add Event Data to an SDK Event. The modification of data happens in the Rules Engine before Event listeners are notified of the Event.
Attach Data Rule Actions will only add data to the Event, and they will never modify or remove data.
If there is a conflict between the data that is defined in your Rule and the data in the Event, the data in the Event will always have preference.
When defining a payload for the attach data action, the payload must match the format of the triggering event. For example, if you want to add context data to an Analytics event, you will need to know where the context data is defined on that event and match the format in your rule. For this reason, it is strongly recommended that you enable verbose logging in the SDK and carefully study the format of the event to which you attach data. If the format does not match, it is unlikely that the expected results will be received.
The following sample shows how to attach data to all outgoing TrackAction Analytics network requests. To create this type of rule, select your property in Launch and complete the following steps:
​Create a new Rule​
On the Rules tab, click Create New Rule.
If you do not have existing rules for this property, the Create New Rule button will be in the middle of the screen. If your property has rules, the button will be in the top right of the screen.
Give your rule an easily recognizable in your list of rules.
In this example, the rule is named Attach Places Data to Analytics Track Action Events.
Under the Events section, click Add.
From the Extension drop-down list, select Mobile Core.
From the Event Type drop-down list, select Track Action.
Click Keep Changes.
Under the Actions section, click Add.
From the Extension drop-down list, select Mobile Core.
From the Action Type drop-down list, select Attach Data.
On the right pane, in the JSON Payload field, type the data that will be added to this event.
Click Keep Changes.
On the right pane, you can add a freeform JSON payload that adds data to an SDK event before an extension that is listening for this event can hear the event. In this example, some context data is added to this event before the Analytics extension processes it. The added context data will now be on the outgoing Analytics hit.
In the following example, launches and anAddedKey keys are added to the contextdata of the Analytics event. Values for the new keys can either be hardcoded in the rule, or dynamically determined by the SDK when this event processes by using Data Elements.
After you complete your configuration, verify that your rule looks like the following:
Click Save
Rebuild your Launch property and deploy it to the correct Environment.
