Implement Analytics for digital assistants

With advances in cloud computing, machine learning, and natural language processing, digital assistants are part of everyday life. Consumers talk to their devices and expect human-like responses, and brands can present their services through these same experiences. For example, consumers can ask:

This page provides an overview of how to use Adobe Analytics to measure and optimize these types of experiences.

Digital experience architecture overview

Most digital assistants follow a similar high-level architecture:

How data is sent to Adobe Analytics

A digital assistant app typically runs on a server or platform that has no Adobe client-side library (AppMeasurement or the Web SDK). Send hits server-side using the Data Insertion API. Each interaction you want to measure becomes a Data Insertion API request whose query string (or XML body) carries the variables described on this page — most often context data variables that you map to eVars, props, and events with processing rules.

This page focuses on what to measure and how to model it in Analytics. For the endpoint, the query-string and XML encodings, required components, and response types, see the Data Insertion API documentation. Each variable named below maps to a query-string parameter and XML tag in the variable reference.

Where to implement Analytics

One of the best places to implement Analytics is in the app, which receives the intent and details from the digital assistant and determines how to respond. There are two moments during a request that are helpful to send data to Adobe Analytics:

If you are interested in recording what happened for future optimization, send the hit after the response has been returned — you then have the full context of the request and how the system responded.

What to measure

New installs

For assistants that notify you when someone installs the skill (especially where authentication is involved), send an install event by setting the context data variable a.InstallEvent=1, along with a.InstallDate and the app ID (a.AppID). This is not available on every platform, but is useful for retention analysis when present.

Multiple assistants or apps

Organizations often build apps for multiple platforms. Include an app ID on every request in the a.AppID context data variable, using the format [AppName] [BundleVersion] (for example, Spoofify 1.0). Add a platform or OS context data variable (such as OSType) so you can distinguish Alexa, Google Assistant, and other platforms in reporting.

Visitor identification

Adobe Analytics uses the Adobe Visitor ID Service to tie interactions over time to the same person. Most digital assistants return a userID that you can use as a unique identifier — pass it as the visitor ID override (vid). Some platforms return an identifier longer than the 100 characters allowed; in these cases, hash it to a fixed-length value with a standard algorithm such as MD5 or SHA-1.

Using the Visitor ID Service provides the most value when you map ECIDs across devices (for example, web to digital assistant). If your app is a mobile app, use the Experience Platform Mobile SDK and send the user ID with the setCustomerID method. If your app is a service, use the user ID provided by the service as the visitor ID and also set it with setCustomerID. For how to set identifiers on a server-side request, see Visitor identification using the Data Insertion API.

Sessions

Because digital assistants are conversational, they often have the concept of a session (a multi-turn exchange). When a new session starts, Adobe recommends two things:

Intents

Each assistant detects intents and passes them to the app. An intent is a succinct representation of the request — for example, “Siri, send John $20 for dinner last night from my banking app” might resolve to the intent sendMoney. Send each intent into a context data variable that you map to an eVar so you can run pathing reports across intents. Make sure your app handles requests without an intent as well; Adobe recommends sending No Intent Specified rather than omitting the variable.

Parameters, slots, and entities

In addition to the intent, assistants often provide key/value details of the request (called slots, entities, or parameters). For “Siri, send John $20 for dinner last night,” the parameters might be:

There is typically a finite set of these per app. Send them into context data variables and map each to an eVar.

Error states

Sometimes the assistant passes inputs your app cannot handle (for example, “Siri, send John 20 bags of coal from my banking app”). When this happens, have your app ask for clarification and send data indicating an error state — set a.Error=1 along with an eVar that specifies the error type. Include both errors where the inputs are invalid and errors where the app itself had a problem.

Device capabilities

While most platforms do not expose the exact device, they do expose its capabilities (such as Audio, Screen, or Video), which define the content types you can use. When measuring device capabilities, concatenate them in alphabetical order with leading and trailing colons — for example, ":Audio:Camera:Screen:Video:" — so that you can build segments such as “all hits with :Audio: capabilities.”

Example request

The following Data Insertion API GET request records a SendPayment intent for a banking app, setting the app ID, a launch event, the intent, and slot values as context data:

GET /b/ss/examplersid1,examplersid2/1?vid=[UserID]&c.a.AppID=Penmo%201.0&c.a.LaunchEvent=1&c.Intent=SendPayment&c.Amount=20.00&c.Reason=Dinner&c.ReceivingPerson=John&pageName=SendPayment HTTP/1.1
Host: example.data.adobedc.net

For the full request format, endpoints, and response types, see the Data Insertion API documentation.

Example measurement model

The following table shows how common actions in a music app map to Analytics variables. Set these as context data variables on each Data Insertion API request, then map them to eVars and events with processing rules.