The Tealeaf client frameworks let you capture user interface events and application events from the visitor's client, which might not generate a full request from the web application. These client frameworks are Javascript-based toolkits that are deployed through your web application and installed in the visitor's client.
Without interrupting the customer experience, the client frameworks monitor the client application for events of interest and transmit those events to Tealeaf for capture and processing. Through the client frameworks, you can apply the same level of monitoring on your mobile or web applications as you can through the browser-based applications that are monitored by cxImpact.
Before you begin, one or more of the Tealeaf clients frameworks must be licensed, deployed, and configured in your web application environment. Tealeaf client frameworks require the CX Mobile license.
General workflow
The general workflow for integrating client framework data into Tealeaf is:
- Locate client framework sessions, including differences in how the data is posted.
- Identify user agent information that is provided by the client framework.
- Create step attributes from them to gather user agent data from the logging framework(s).
- Create events from the step attributes.
- Integrate events into existing reporting.
Required licenses
Tealeaf client frameworks can be deployed to capture data from the types of applications that are listed and submitted to Tealeaf for processing. Before you begin, it is assumed that you installed and successfully deployed one of the Tealeaf client frameworks and that you verified client framework data is being captured by Tealeaf.
| Framework | Required license |
|---|---|
| UI Capture j2 | CX-Extended platform license |
| Tealeaf Android Logging Framework |
|
| Tealeaf iOS Logging Framework |
|
Prerequisites
Before you integrate client framework data into Tealeaf, you must complete the following steps:
- Install the latest version of Tealeaf CX.
- Verify that your Portal account has access to the following menus:
- Event Manager: From the Portal menu, select Configure > Event Manager.
- Report Builder: From the Portal menu, select Analyze > Report Builder.
- Integrate one of the client frameworks with your Tealeaf application.
- Verify that extended user agent parsing is enabled. Extended user agent parsing is enabled by default through the Tealeaf Reference session agent, which is required in most pipelines. Use TMS to verify that extended user agent parsing is enabled.
- Configure user agent parsing, if necessary.
- For UI capture only, if you deployed a version of your web application for mobile web browsers, deploy the WURFL public standard to enable detection of mobile-based user agents.
- For UI capture only, after you enabled user agent detection, configure events to detect mobile device characteristics that are based on the captured and verified user agent information.
Use groups and labels to store events and event-related objects
Before you begin building events and event-related objects, you should consider creating groups and labels to store them. You may build hit attributes, events, session attributes, and dimensions, so you should try to find ways to create consistent labels in each of the appropriate tabs in the Event Manager.
This table describes one set of labels and groups for client framework data:
| Label/Group | Description |
|---|---|
Source - UIC |
Event objects created to track data from Tealeaf UI Capture |
Source - Android |
Event objects created to track data from the Tealeaf Android SDK |
Source - iOS |
Event objects created to track data from the Tealeaf iOS SDK |
Source - Mobile |
Event objects created to track data from mobile devices in general |
Identify client framework sessions
When client framework messages are received by the PCA, they are examined for the source of the message. Based on the source that is detected in the x-tealeaf header in the raw request, the PCA inserts header values for each client framework as a name-value pair in the [env] section of the request:
| Client Framework | Name/Value Example |
|---|---|
| Tealeaf UI Capture (JSON) |
This header value is inserted only if UI Capture is submitting JSON-based data. |
| Tealeaf UI Capture (XML) |
For Tealeaf UI Capture solutions that use XML-based messaging, you can locate sessions by searching for this data in the request or for events that you create to identify this exact name-value pair in the request. |
| Android Logging Framework |
|
| iOS Logging Framework |
|
In the above name-value pairs, the value after Lib/ indicates the version number of the client framework that captured and submitted the hit.
HTTP_X_TEALEAF request variable, you must create them manually through the Event Manager. When these objects are created through the recommended method in BBR, the Event Manager identifies them as existing in the provided set of event objects. You can work around this safeguard by manually creating them.Objects provided by Tealeaf for mobile native applications
For mobile native applications, Tealeaf provides a set of objects to help integrating the data into your Tealeaf data set.
This table describes the objects provided for mobile apps:
| Sequence | Object | Description |
|---|---|---|
| 1 | Mobile Device Type hit attribute |
The Mobile Device Type hit attribute is designed to identify hits that was submitted from the mobile client frameworks.
Note: This hit attribute filters out values that were captured from the Tealeaf UI Capture solution that were posted in the
HTTP_X_TEALEAF header. Values that are reported in this hit attribute are for mobile native applications only.
|
| 2 | Mobile Device event |
This event is triggered if the Mobile Device Type hit attribute is found. The recorded value is the value of the hit attribute, which is the value between the parentheses of the request variable. |
| 3 | Mobile Device dimension |
This dimension is recorded from the last value in the session for the Mobile Device event. Dimensions are defined in the Event Manager, which is available through the Portal. |
| 4 | Traffic Type dimension |
When the value for the HTTP_X_TEALEAF variable includes iOS or android, the value for the Traffic Type dimension is set to MOBILE_APP. In this manner, you can segment reporting based on whether the type of traffic is sourced from a mobile native application. |
Attributes and events used to detect sessions
After you create event objects, you can see how sessions sourced from each framework is detected within Tealeaf. Tealeaf uses the combination of hit attributes, events, and dimensions to detect the source of the session captures.
| Source of Session Capture | Hit Attribute | Event | Dimension | Session Attribute |
|---|---|---|---|---|
| Android LF | Mobile Device Type | Mobile Device | Mobile Device | none |
| iOS LF | Mobile Device Type | Mobile Device | Mobile Device | none |
| UIC for JSON | Create a hit attribute to detect sessions sourced from UI capture. | none | none | none |
| UIC for XML | CUI Hit (value must be ClientEvent) | none | none | none |
User agent detection
You can configure Tealeaf to detect and capture user agent information that is submitted from the client application.
User agent standards
This table lists and describes the user agent standards that Tealeaf uses. Standards are listed by application type:
| Application type | User agent standard | Description |
|---|---|---|
| desktop browser | browscap | Tealeaf uses the browscap standard for capturing user agent information that is submitted from desktop browsers |
| mobile desktop browser | WURFL | CX Mobile can use the WURFL public standard for capturing user agent information that is submitted from mobile web browsers |
| mobile native application | n/a | User agent information is submitted in a consistent form by the client framework monitoring your mobile native applications. |
One of the functions of the Tealeaf Reference session agent is to perform lookups against these public standards for user agent information that is submitted from the client.
The Tealeaf Reference session agent must be included in every Windows™ pipeline in which session data is processed.
User agent detection for UI Capture
Since the UI Capture solution is provided for applications being served to fixed desktop browsers or mobile web browsers, user agent information is available as part of regularly submitted requests from these browsers, using Browscap or WURFL.
Tealeaf reference dimensions from UI Capture solutions is written to different values in the request.
User detection and mobile native applications
Typically, individually mobile applications send a unique user agent string that is not known to any public repository, or they may not send a user agent at all. As a result, user agent detection for mobile native applications cannot rely on WURFL, Browscap, or other public standard.
HTTP_X_TEALEAF header and mobile native applications
To enable tracking of user agent-related information for mobile native applications, the Tealeaf client frameworks submit the HTTP_X_TEALEAF header, which is rendered into these request variables:
| Logging Framework | Example submitted header |
|---|---|
| Android Logging |
|
| iOS Logging Framework |
|
HTTP_X_TEALEAF_PROPERTY header and mobile native applications
The Tealeaf client frameworks also submit the HTTP_X_TEALEAF_PROPERTY header, which contains user agent information that is extracted from the device itself.
The Tealeaf Reference session agent then uses the properties included in the above header to write out available values in the [ExtendedUserAgent] section, in the request variables that are used by other Tealeaf components to extract user agent information. In this manner, information that provided directly by the Tealeaf client frameworks is used to populate user agent information throughout Tealeaf without requiring a lookup or other reference data.