# Adobe Analytics

Complement your Adobe Analytics data with real-time mobile and web engagement events.

## Overview

Adobe Analytics provides behavioral analytics and content performance measurement for websites and mobile apps. Airship [Real-Time Data Streaming](https://www.airship.com/docs/reference/glossary/#rtds) (RTDS) provides a live view into your application, adding the "messaging perspective" to your Adobe Analytics information. This integration enables a complete view of the user experience by combining Adobe Analytics data with user-specific interactions such as push sends, direct and indirect opens, web notification clicks, and uninstalls.

Additionally, Airship augments Adobe's device reporting with information on in-app behavior defined by the Airship SDK. Airship events can tell you when a Message Center message was delivered, read, and deleted. They can also describe what happened to an in-app notification — whether it was displayed or expired, and what happened to it after it was displayed. Did the user dismiss it, interact with it, or allow it to resolve itself?

---

There are three major steps to setting up this integration. You will need help from your developers (iOS and Android) and your Adobe Analytics and Airship administrators to:

1. **Add client code** (Developers) — This code associates the user IDs between the two systems, tying events captured from the Airship SDK (iOS, Android, or Web) to events captured from the Adobe Analytics SDK.
1. **Configure an outbound integration for Adobe Analytics** (Airship administrator) — The RTDS integration sends Airship events to an Adobe Analytics report suite.
1. **Set up Adobe Analytics processing rules** (Adobe Analytics administrator) — These rules map Airship events to your Adobe variables and events.

## Adobe Analytics Integration Requirements

This integration requires these accounts:
   1. Adobe Analytics 
   1. Airship — Must include both:
      * Messaging
      * [Real-Time Data Streaming](https://www.airship.com/docs/reference/feature-packages/#data)

## Adding Client Code

Fetch the Adobe Analytics visitor ID for your user, then associate it with the
Airship [Channel ID](https://www.airship.com/docs/reference/glossary/#channel_id). See [Android](https://www.airship.com/docs/developer/sdk-integration/android/analytics/#associated-identifiers), [iOS](https://www.airship.com/docs/developer/sdk-integration/apple/analytics/#associated-identifiers), and [Web](https://www.airship.com/docs/developer/sdk-integration/web/analytics-and-reporting/#custom-identifiers) custom identifiers documentation.


#### iOS Swift


```swift
// Get the Adobe visitor ID
let visitorID = ADBMobile.visitorMarketingCloudID()

// Add the visitor ID to the current associated identifiers
let identifiers = Airship.analytics.currentAssociatedDeviceIdentifiers()
identifiers.set(identifier: visitorID, key:"AA_visitorID")

// Associate the identifiers
Airship.analytics.associateDeviceIdentifiers(identifiers)
```


```obj-c
// Get the Adobe visitor ID
NSString *visitorID = [ADBMobile visitorMarketingCloudID];

// Add the visitor ID to the current associated identifiers
UAAssociatedIdentifiers *identifiers = [UAirship.analytics currentAssociatedDeviceIdentifiers];
[identifiers setIdentifier:visitorID forKey:@"AA_visitorID"];

// Associate the identifiers
[UAirship.analytics associateDeviceIdentifiers:identifiers];
```



#### Android Java


```java
// Get the Adobe visitor ID
String visitorId = Visitor.getMarketingCloudId();

// Add the visitor ID to the current associated identifiers
Airship.getAnalytics()
    .editAssociatedIdentifiers()
    .addIdentifier("AA_visitorID", visitorId)
    .apply();
```



#### Web


The Adobe Experience Cloud Identity Service (ECID) JavaScript library retrieves the visitor ID asynchronously. Initialize both SDKs before associating the identifier.

```javascript
const sdk = await UA;

// Adobe ECID provides the visitor ID via callback
Visitor.getInstance(adobeOrgId).getMarketingCloudVisitorID(async (visitorId) => {
  if (visitorId) {
    await sdk.analytics.associatedIdentifiers.edit()
      .add("AA_visitorID", visitorId)
      .apply();
  }
});
```


> **Note:** The `analytics` feature must be enabled in your Web SDK configuration. This is controlled by the `enabledFeatures` list. Ensure `analytics` is included. See [Data Collection for the Web SDK](https://www.airship.com/docs/developer/sdk-integration/web/data-collection/).





<p>Once set, all associated identifiers are returned in RTDS under the <code>&quot;identifiers&quot;</code> key:</p>
```json
{
   "ios_channel": "a6b392d6-3b0d-4c00-98ef-5cb91d51268a",
   "named_user_id": "albert",
   "identifiers": {
     "foo": "bar",
     "verycustomid": "123554"
   },
   "attributes": {
     "package_name": "com.company_name.app_name",
     "version": "1.0.0",
     "ua_library": "7.0.2"
   }
 }
```

<p>See also: <a href="https://www.airship.com/docs/developer/rest-api/connect/schemas/device-information/">RTDS API: Device Information</a>.</p>

## Configuring the Outbound Integration

> **Warning:** Airship sends events to Adobe with timestamps. If your Adobe Analytics Report Suite has timestamps disabled, Adobe will drop Airship events. See [Timestamps Optional](https://docs.adobe.com/content/help/en/analytics/admin/admin-tools/timestamp-optional.html) for more information.


You will need your Adobe Analytics Report Suite ID and Tracking Server URL. If you do not have these, contact your iOS, Android, or Web developer.

In Airship:

1. Next to your project name, select the dropdown menu (
), then **Settings**.
1. Under **Project settings**, select **Partner Integrations**.
1. Select **Adobe Analytics**.
1. Select **Configure** for the outbound integration and follow the onscreen instructions to:
    * Enter your Report Suite ID
    * Enter your Tracking Server URL
    * Select the Airship events to send to your Report Suite

After configuring your app and your integration, you can
create event-based Segments in Adobe Analytics. See
[Recommended Attribute Mapping](#connect-aa-mapping) for
recommended mapping of Data Streaming events to Adobe Analytics events.

### Recommended Property Mapping {#connect-aa-mapping}

> **Important:** If you set up your integration before March 11, 2020, your event fields will not belong to a global `airship` object. You must create a new integration to use the `airship.` namespace.


In Adobe Analytics, you capture the data that is valuable to you using context data and processing rules. Airship uses Adobe's [Data Insertion API](https://helpx.adobe.com/analytics/kb/data-insertion-api-post-method-adobe-analytics.html) to send data to Adobe Analytics. Airship uses the `contextData` field so that you can include every piece of relevant data from an Airship event without consuming the limited number of variables and properties that Adobe Analytics supports.

You can set the Adobe Analytics processing rules so that every field in an Airship event maps to an Adobe Analytics concept. After your Adobe Analytics administrator sets up your processing rules, you can view Airship event data in your Adobe Analytics dashboard.

We derive `contextData` keys from the original Data Streaming events using JSON notation, and use `airship` to represent the global parent for all Airship event properties. For example, this is the push identifier of a notification that caused an event:

```json
{
   "body": {
      "triggering_push": {
         "push_id": "d99bd842-f816-4560-bc59-b057f7c0e164"
      }
   }
}
```


This field would be available for mapping as `airship.body.triggering_push.push_id`.
When mapped to an sProp, eVar, event, or other Adobe Analytics
concept, the variable's value would be
`d99bd842-f816-4560-bc59-b057f7c0e164`.

> **Note:** The above JSON represents a partial event object. Actual JSON objects coming from the
> Real-Time Data Streaming API are more complex.


To see all the available fields, read the
[Data Streaming API Reference](https://www.airship.com/docs/developer/rest-api/connect/).

## Setting Up Adobe Analytics Processing Rules

You or your Adobe administrator must set up processing rules in the Adobe Analytics Admin Console to enable Adobe Analytics to capture events from Airship. These processing rules assign `contextData` variables to Adobe Analytics variables or increment events (counters) accordingly.

1. In the Adobe Analytics interface, select **Admin Console** and navigate to **Report Suites**.
1. Select the Report Suite that Airship is sending data to, and then go to **Edit Settings**, then **General**, then **Processing Rules**.
1. Select **Add Rule**.
1. Enter a title for the rule. For example, "Airship to Adobe Analytics Integration."
1. Select **Add Action**.
1. If you need to setup an sProp or eVar to capture a dimension (e.g., Event Type), select **Overwrite Value Of** and then select the sProp or eVar that you want to set. After the **With** label, select the `contextData` variable that you want to set the sProp or eVar with.
1. If you need to set up an Event to capture the number of times something occurred, e.g., the number of Opens, select **Set Event** and then select the Adobe Analytics Event you want to set. Select **Custom Value** and set the value to 1. Then set a condition for when you want to set the event.

   Continuing with the *Opens* example, you would set up a condition where the *If* is for the same *type* `contextData` variable, and the condition would be *equals OPEN*. This will increment the Open Event each time the Data Streaming Event Type is set to *OPEN*.

This is just one example of how you can set up a variable and an event. The same concept applies for each Airship event type and dimension that you want to capture in Adobe.

### Recommended Concept Mappings

Below are some recommendations on different ways that you can get started mapping the Airship concepts to Adobe Analytics concepts.

This table provides example `contextData` variable keys and the recommended Adobe Analytics variable type to capture information from incoming Airship event information. See our [Real-Time Data Streaming documentation](https://www.airship.com/docs/developer/rest-api/connect/) for information on events and fields that aren't listed below. Use JSON object notation to reach nested properties (in the format `airship.property.sub-property`). In Adobe analytics, all variables are preceded by `airship.`.

| Airship Concept | Recommended Adobe Analytics Mapping Context | Data Variable |
|  --- |  --- |  --- |
| Data Streaming event type (e.g., send, direct open, indirect open, web notification click) | Custom event (one for each type), and an sProp for segmentation (all the people who received a message, or opened, etc.) | `type` |
| Unique push ID, group  ID, or variant | eVar | `airship.body.push_id`, `airship.body.group_id`, `airship.body.variant`, `airship.body.triggering_push.push_id`, `airship.body.triggering_push.group_id`, `airship.body.triggering_push.variant`, `airship.body.last_delivered.push_id`, `airship.body.last_delivered.group_id`, `airship.body.last_delivered.variant`, `airship.body.replacing_push.push_id`, `airship.body.replacing_push.group_id`, `airship.body.replacing_push.variant` |
| Device Identifiers — mobile (e.g., Named User, Airship Channel ID) | eVar | `airship.device.ios_channel`, `airship.device.android_channel`, `airship.device.named_user`, `airship.device.identifiers.com.urbanairship.idfa` |
| Device Identifiers — web (Airship Channel ID) | eVar | `airship.device.channel` |
| Web browser context | sProp | `airship.device.attributes.web_browser_name`, `airship.device.attributes.web_browser_type`, `airship.device.attributes.web_browser_version`, `airship.device.attributes.web_user_agent_string` |
| In-App Message Resolution Type | sProp AND eVar | `airship.body.type`<br> (and type is `IN_APP_MESSAGE_RESOLUTION`) |
| In-App Message Expiration Type | sProp AND eVar | `airship.body.type` (and type is `IN_APP_MESSAGE_EXPIRATION`) |
| In-App Message Button identifiers | sProp | `airship.body.button_id`, `button.button_description` |
| Adobe visitorId (via associated identifiers) | eVar | `airship.device.identifiers.AA_visitorID` |
| Other Data Streaming information | Varies | You can determine what the context variable name will be based on the Data Streaming event data. Inner properties are joined with outer properties via a period. |

`contextData` can take a long time to appear in the Adobe Analytics dashboard.
Please allow at least one hour before contacting Airship Support.

> **Important:** **Known issue:** If no processing rules have been defined, no `contextData`
> variables will be available for mapping.
> 
> As a workaround until Adobe Analytics fixes this issue, add a trivial rule
> that does nothing, then proceed establishing your mapping as normal.


## Sample Data Sent to Adobe

```xml
<?xml version="1.0"?>
<request>
  <reportSuiteID>your-report-suite-id</reportSuiteID>
  <scXmlVer>1.0</scXmlVer>
  <pageName>OPEN-ios</pageName>
  <timestamp>2016-05-19T22:42:36.946Z</timestamp>
  <contextData>
    <id>03f13497-1e13-11e6-bc8d-001018948f58</id>
    <offset>444449</offset>
    <occurred>2016-05-19T22:42:36.946Z</occurred>
    <processed>2016-05-19T22:42:51.511Z</processed>
    <device.ios_channel>ec2816a3-72c7-4b9b-9ee6-ae31229f28bd</device.ios_channel>
    <device.named_user_id>mtr1234</device.named_user_id>
    <device.identifiers.com.urbanairship.limited_ad_tracking_enabled>true</device.identifiers.com.urbanairship.limited_ad_tracking_enabled>
    <device.identifiers.session_id>72153D08-B6A2-4900-9045-6776734B183B</device.identifiers.session_id>
    <device.identifiers.com.urbanairship.idfa>E51089C4-DD2D-44AA-BCD0-092DD6A16085</device.identifiers.com.urbanairship.idfa>
    <device.identifiers.com.urbanairship.vendor>DFEF1B87-2253-423C-97D4-003AA36F5C25</device.identifiers.com.urbanairship.vendor>
    <device.attributes.locale_variant/>
    <device.attributes.app_version>215</device.attributes.app_version>
    <device.attributes.device_model>iPhone6,1</device.attributes.device_model>
    <device.attributes.app_package_name>com.urbanairship.internalsampleapp</device.attributes.app_package_name>
    <device.attributes.iana_timezone>America/Los_Angeles</device.attributes.iana_timezone>
    <device.attributes.push_opt_in>true</device.attributes.push_opt_in>
    <device.attributes.locale_country_code>US</device.attributes.locale_country_code>
    <device.attributes.device_os>9.3.2</device.attributes.device_os>
    <device.attributes.locale_timezone>-25200</device.attributes.locale_timezone>
    <device.attributes.locale_language_code>en</device.attributes.locale_language_code>
    <device.attributes.location_enabled>false</device.attributes.location_enabled>
    <device.attributes.background_push_enabled>true</device.attributes.background_push_enabled>
    <device.attributes.ua_sdk_version>7.1.0</device.attributes.ua_sdk_version>
    <device.attributes.location_permission>UNPROMPTED</device.attributes.location_permission>
    <body.session_id>787bf679-4732-4722-b761-bcd9b1e7a1eb</body.session_id>
    <body.last_delivered.push_id>685783c0-68b1-4d05-bc94-98e90d943fd1</body.last_delivered.push_id>
    <body.last_delivered.variant_id>1</body.last_delivered.variant_id>
    <body.last_delivered.time>2016-05-19T18:04:40.049Z</body.last_delivered.time>
    <type>OPEN</type>
  </contextData>
  <visitorID>ec2816a372c74b9b9ee6ae31229f28bd</visitorID>
</request>
```

