Important
Version 5.x of the Edge Bridge extension uses a new data format compared to the previous versions. If you are using version 4.x or lower of the Edge Bridge extension, please find the relevant tutorials here.
If you want to learn more about the benefits of upgrading to version 5.x, see the Edge Bridge migration guide.
- Overview
- Adobe Experience Platform setup
- Client-side implementation
- Validation with Assurance
- Optional - Map track event data with Data Prep for Data Collection
This tutorial covers how to use Edge Bridge as a drop-in solution for migrating from an existing Analytics implementation to sending data via the Edge Network to Analytics.
graph TD;
step1(1<br/>Existing app using Adobe Analytics) -->
step2(2<br/>Adobe Experience Platform<br/>Update server-side configuration) -->
step3(3<br/>Edge Bridge<br/>Update app to send event data via Edge Network to Analytics) -->
step4(4<br/>Assurance<br/>Verify implementation)
style step1 fill:#3273de,stroke:#333,stroke-width:2px,color:#fff
style step2 fill:#3273de,stroke:#333,stroke-width:2px,color:#fff
style step3 fill:#3273de,stroke:#333,stroke-width:2px,color:#fff
style step4 fill:#3273de,stroke:#333,stroke-width:2px,color:#fff
- macOS machine with a recent version of Xcode installed.
Note
The tutorial app for this exercise already includes the Edge extensions. To learn more about these extensions, please see the Edge extension tutorials.
- A timestamp enabled report suite configured for mobile data collection.
- A tag (also known as a mobile property) configured in the Data Collection UI, which has the Adobe Analytics extension installed and configured.
This section demonstrates how to create and configure a mobile property in Experience Platform, which controls the configuration settings for the Mobile SDK extensions used in this tutorial.
Setup instructions - Skip this section if prerequisite item 2 has already been set up.
To create a new mobile property, refer to the instructions on how to set up a new property.
Install the following Experience Platform extensions:
Adobe Analytics
Open the Catalog and install the Adobe Analytics extension.
In the extension configuration settings window, set the report suite ID (1) for each environment (2) to the one designated for this tutorial. Then, select Save (3).
AEP Assurance
Open the Catalog and install the AEP Assurance extension.
Adobe Experience Platform Edge Network
Open the Catalog and install the Adobe Experience Platform Edge Network extension.
In the extension configuration settings window, set the datastream for each environment (1) to the one designated for this tutorial. Then, select Save (2).
Identity
Open the Catalog and install the Identity extension. There are no settings to configure for this extension.
Consent
Open the Catalog and install the Consent extension.
In the extension configuration settings window, the Default Consent Level should be set to Yes by default (1).
⚠️ Important
For the tutorial app, this setting is acceptable as-is. However, when configuring this setting in production applications, it should align with the organization's data collection and privacy policies.
The following cards should be visible once all the extensions have been installed:
The collectPII API for Analytics does not send events to Edge Network by default; it requires a rule to be configured to forward these events. This section provides an example of how to create such a rule.
- In the Rules tab, select Create New Rule.
- If your property already has rules, the button will be in the top right of the screen.
- Give the rule a recognizable name (1) in your list of rules.
- In this example, the rule is named "Forward PII events to Edge Network".
- In the EVENTS section, select Add (2).
- From the Extension dropdown list (1), select Mobile Core.
- From the Event Type dropdown list (2), select Collect PII.
- Select Keep Changes (3).
-
Under the Actions section, select + Add (1).
-
From the Extension dropdown list (1), select Adobe Analytics.
-
From the Action Type dropdown list (2), select Track.
-
Name the Action field (3) "collect_pii", in the right-side window.
-
Select the + (4) next to Context Data and set the Key to "ruleKey" and Value to "ruleValue" (5).
-
Select Keep Changes (6).
- After completing your configuration, verify that your rule appears as follows:
- Select Save (1).
- Open the code repository: https://github.com/adobe/aepsdk-edgebridge-ios
- Select the green Code button in the top right.
- In the window that opens, select Download ZIP; by default, it should download to your Downloads folder.
- Unzip the archived file by opening it.
- Navigate to the unarchived folder, then navigate to Documentation -> Tutorials -> EdgeBridgeTutorialAppStart.
- Open the file EdgeBridgeTutorialApp.xcworkspace; this should automatically open the Xcode IDE.
The next task is to update the necessary dependencies to enable the Edge Bridge extension to function.
- Install the Edge Bridge (
AEPEdgeBridge) extension.
- In Xcode, from the top bar, select File -> Add Package Dependencies...
- In the Search or Enter Package URL search box in the top right, input
https://github.com/adobe/aepsdk-edgebridge-ios.git - Select the aepsdk-edgebridge-ios package.
- For Dependency Rule, select Branch and input
main. - Select Add Package.
- Remove the Analytics (
AEPAnalytics) extension.
- In Xcode, from the left side file navigator, select EdgeBridgeTutorialApp.
- Under PROJECT, select EdgeBridgeTutorialApp.
- Select Package Dependencies.
- Select AEPAnalytics and then the minus (-) button under the table, then select Remove.
Using CocoaPods instead?
CocoaPods This tutorial assumes a project using Swift Package Manager (SPM) for package dependency management. However, if you are following along with a project that uses CocoaPods, refer to the README for instructions on how to add the Edge Bridge extension.
The file AppDelegate.swift needs to be updated to enable the Edge Bridge extension.
Inside, you will see code blocks for this tutorial that are greyed out because they are commented out. They are marked by the header and footer Edge Bridge tutorial - code section n/m (where n is the current comment section number and m is the total number of sections in the file).
To uncomment the section and activate the code, simply add a forward slash at the beginning of the header:
/* Edge Bridge tutorial - code section (1/2)To:
//* Edge Bridge tutorial - code section (1/2)Make sure that all sections within the file are uncommented (the total number of sections is indicated).
Open AppDelegate.swift:
- In Xcode, in the left-side Project Navigator panel, select the dropdown chevron next to EdgeBridgeTutorialApp.
- If the Project Navigator panel is not visible, from the top menu, select View -> Navigators -> Show Project Navigator.
- Select the dropdown chevron next to the EdgeBridgeTutorialApp folder.
- Select the
AppDelegate.swiftfile.
Set the tutorial app to use the mobile property ID:
- Update the
ENVIRONMENT_FILE_IDvalue to the mobile property ID published in the first section.- See how to find your mobile property ID in the instructions for getting the mobile property ID.
Remove Analytics and AEPIdentity extensions:
Warning
Before proceeding, verify if your application uses any Adobe Experience Cloud Solution extensions, such as Adobe Target or Adobe Campaign (find the full list here). Only remove AEPIdentity if no other solution extensions are in use.
Inside AppDelegate.swift, you will see code blocks for this tutorial marked by a header and footer Edge Bridge tutorial - remove section (n/m) (where n is the current comment section number and m is the total number of sections in the file).
Delete everything between the header and footer, and do this for all "remove section" blocks within the file.
For details on the various Edge extensions used, see the table of related projects.
In Xcode, select the app target you want to run, and the destination device to run it on (either a simulator or a physical device). Then press the Play button in the top left.
You should see your application running on the selected device, with logs displayed in the Xcode console.
Tip
If the debug console area is not shown by default, activate it by selecting:
View -> Debug Area -> Activate Console
With the Edge Bridge extension successfully installed and registered, you can continue to make existing Analytics trackAction and trackState calls. These will be captured by the Edge Bridge extension and sent to the Edge Network.
Check ContentView.swift for implementation examples of both APIs. You will see the data payloads that are sent with each call.
Assurance is the Experience Platform tool for inspecting all events that Adobe extensions send out in real time. It allows observing the flow of events, including the Edge Bridge conversion of trackAction/trackState events.
To create a new Assurance session and connect to it, see the instructions on setting up an Assurance session, using the base URL value:
edgebridgetutorialapp://
To connect the tutorial app to the Assurance session, see the instructions on connecting the app to the Assurance session.
To view Edge Bridge events in the connected app instance:
- Trigger a
trackActionortrackState(1) within the app, which the Edge Bridge extension will convert into Edge events. These events will be captured by the Assurance extension and displayed in the web session viewer.
- Select the AnalyticsTrack event (1) in the events table to view the event details in the right side window.
- Select the RAW EVENT dropdown (2) in the event details window to view the event data payload.
- Verify that the
contextdatamatches what was sent by the AnalyticstrackAction/trackStateAPI.
- Now select the Edge Bridge Request event (1) in the events table.
- Select the RAW EVENT dropdown (2) in the event details window; observe the transformation of the payload structure (3) with the help of the Edge Bridge extension. The Edge Bridge Request event conforms to the format of an Edge Network event.
The following table and diagram highlight the differences in event data structure and format between the two types of events: Analytics (left) vs Edge (right) when using the Edge Bridge extension:
| Item | Before (Analytics) | After (Edge Bridge) |
|---|---|---|
| 1 | Top level ACPExtensionEventType: generic.track |
Top level ACPExtensionEventType: edgeACPExtensionEventData.xdm.eventType: analytics.track |
| 2 | contextdata key under ACPExtensionEventData |
contextData transformed and moved under data.__adobe.analytics |
| 3 | Keys with reserved prefix && directly under contextdata |
Keys with prefix && transformed and moved under data.__adobe.analytics |
| 4 | No Analytics metrics | Analytics metrics added under data.__adobe.analytics (varying locations) |
Note
The two new top-level properties xdm and data are standard Edge Network event properties, integral to Experience Platform's Experience Data Model (XDM) schema-based system for event data organization. This system allows for powerful, customizable data processing.
To learn more about the final data format created by Edge Bridge, please refer to the data format documentation.
Rule-based trackAction/trackState events are also converted to Edge events by the Edge Bridge extension. Select the Trigger Consequence button (1) to initiate a rule that generates a trackAction event.
Tip
If no trackAction event is dispatched upon selecting the Trigger Consequence button, verify that your mobile property is set up with the correct rule - see the section Configure a rule to forward personally identifiable information (PII) events to Edge Network under Adobe Experience Platform setup.
Just like the trackAction/trackState events above, the Edge Bridge extension converts the PII trackAction event into an Edge event.
With this, the migration from an existing Analytics implementation to sending data via Edge Network to Analytics, powered by Edge Bridge, is complete!
Edge Bridge transforms track events into an Edge Network event format suitable for Adobe Analytics, so that mapping data to Experience Data Model (XDM) is not required for Analytics. However, to use this same event data in other Experience Platform applications, it must first be mapped to the XDM specification using Data Prep for Data Collection.
The tutorial Map track event data with Data Prep for Data Collection covers how to create these mappings.