IBM Watson Customer Experience Analytics SDK for iOS, standard and mobile editions (Tealeaf)

With the Tealeaf iOS SDK, you instrument your native and hybrid iOS applications for logging and analysis. It captures device context and user activity, so you can monitor and evaluate the performance of your applications.

The iOS SDK was designed for simple implementation: it uses standard iOS classes and user interface controls to track user interface events, and minimizes tAD-VPN@wwpdl.vnet.ibm.comhe impact on your application's performance. Even without the framework, Tealeaf can monitor the traffic between your application and your server. With the framework, you get unprecedented insight into the performance of your application.

Quick Links
Requirements for iOS environments	Supported operating systems	Supported frameworks	IBM Tealeaf package contents
Impact on device resources	Environmental data	Guidelines and tips	Tealeaf iOS SDK Tutorials
Other related documentation

Requirements for iOS environments

To develop iOS applications effectively with iOS SDK, follow these system and software requirements:

Xcode 10.1 (or later).
iOS 8.0 (or later).
Note: Apple no longer supports armv6 devices. The framework is compatible with armv7 (or later) devices.
iOS bitcode is enabled in the iOS SDK and is built in 64 bit with latest Xcode version for the static library for the following architectures: arm64, armv7, armv7s, i386 and x86_64. For the dynamic versions, which are available on https://cocoapods.org/pods/IBMTealeaf, it only contains arm64, armv7, armv7s with bitcode enabled and, because of dynamic limitations, i386 and x86_64 with no bitcode. By Apple standards, you are not required to turn in i386 and x86_64 versions that are used only for simulator testing.
Consult the Apple iOS Dev Center for the most recent iOS technical documentation and tools.
IBM Tealeaf client frameworks do not support forwarding of application data to third-party systems. Application data must be forwarded to the server that hosts the native application.

Supported operating systems

Mac OS X 10.13 (or later)

Supported frameworks

The SDK can be integrated with iOS apps developed with the following frameworks.

Supported frameworks	Tealeaf sample code	Documentation
Ionic 3.0	https://github.com/ibm-watson-cxa/SampleCode_Tealeaf_iOS_CXAIonic_3
Cordova 7.0	https://github.com/ibm-watson-cxa/SampleCode_Tealeaf_iOS_CXACordova_7	Instrument IBM Tealeaf SDKs with a Cordova mobile application
React Native Framework	https://github.com/ibm-watson-cxa/CXA_react_native_module/tree/master/Example	Getting started with the IBM Tealeaf SDK for apps developed with the React Native Framework

IBM Tealeaf iOS package contents

There are three folders created for the Tealeaf iOS release that can be found on github at https://github.com/ibm-watson-cxa/SDK_Tools/tree/master/SDKPackages/tealeaf/ios.

EOCore folder – Contains Static Debug and Release of the base library that Tealeaf and Digital Analytics need to communicate with the server.
Tealeaf folder – Contains Static Debug and Release of the library that collect Tealeaf data that is passed to EOCore.
TLFImageTool folder – The TLFImageTool extracts local image resources and generates .png assets for the replay server to use with Native Replay.

Other folders you may find useful when using the Tealeaf iOS SDK are found here: https://github.com/ibm-watson-cxa.

SampleCode folder – Contains several sample applications that demonstrate how to integrate and use the library. It can be found at https://github.com/ibm-watson-cxa.
KillSwitch folder – Contains a basic kill switch implementation for JSP, ASP.Net, and PHP servers. It can be found at https://github.com/ibm-watson-cxa/SDK_Tools/tree/master/KillSwitch.
TealeafTargetSimulator folder – Contains the tool used to convert sessions into images that are used for Native Replay. It can be found at https://github.com/ibm-watson-cxa/SDK_Tools/tree/master/TealeafTargetSimulator.
Templates folder – Contains the latest native templates compatible with the library. It can be found at https://github.com/ibm-watson-cxa/SDK_Tools/tree/master/NativeTemplates.

Impact on device resources

In benchmark tests, the iOS SDK has the following effects on resources of the visitor’s device:

2 to 3% more memory consumption
Note: If the server is unreachable, the SDK saves data to memory until the server is reachable. By default, the SDK will store up to 512,000 bytes to the device memory. If the cache grows larger than 512,000 bytes, the oldest data is truncated from cache and is deleted. The cache size is managed through the CachedFileMaxBytesSize setting in EOCoreAdvancedConfig.json.

Minimal effect on battery life

Note: According to Apple, the API used to retrieve the battery level from the device can be out of sync with the value that displays on the device. See for more information. The value is also updated in 5% increments only. See for more information.

Environmental data

The framework automatically handles environmental data that is captured when the framework initializes, typically when your application starts, and at regular time intervals during execution. It also provides support for your application to report environmental data that needs special privacy attention or requires special frameworks.

Environmental data can be distributed among multiple hits.

Data that is captured when the framework initializes generally appears in one of the first hits of a session.
Data that is captured at regular time intervals appears along with events. Multiple values can be submitted in a single hit where the number of events is low.
Data that is captured by your application (location and carrier information) can appear at any time, independently or in hits with the other types of environmental data. Multiple values for a single hit can be submitted if your application makes multiple calls to the framework.

Captured at initialization

These values are captured one time per launch of your application when the framework initializes.

Environment data is collected based on a timer. Environment data related to initialization can be, but is not always, submitted on the first hit of the session. As environment data is passed through the framework, it is prioritized based on its logging level. The order that it is posted to the server and even whether it is posted to the server depends on the following.

Budgets for in-memory and local storage caches
Network packet size
The send level for the type of network available to the application
Note: Data is not posted to the server in the order that it was captured.

Name	Description
pixelDensity	Value that is returned by `[[UIScreen mainScreen] scale]`.
deviceWidth	Value that is returned by `[[UIScreen mainScreen] bounds].size.width`.
deviceHeight	Value that is returned by `[[UIScreen mainScreen] bounds].size.height`.
width	Value that is returned by `pixelDensity*deviceWidth`.
height	Value that is returned by `pixelDensity*deviceHeight`.
osVersion	Version of iOS running on the device.
totalStorage	Total storage on the device, `free+used`.
totalMemory	Total memory of the device, `free+used`.
manufacturer	`Apple Inc.` on all iOS devices.
userID	Unique user ID generated by the iOS SDK SDK for current instance of the application.
appVersion	Version of the iOS application.
deviceModel	Type of iPhone, iPad, and so on.
appName	Name of the current application.
orientationType	The orientation of the device (`PORTRAIT`, `LANDSCAPE`, `FLAT`, or `UNKNOWN`).
locale	Current locale (for example, en).
language	Current language (for example, English).
osType	The type of device used during capture.
tag	All the controls on which you would like to create events must have unique ids. For example, if there is a text field for `Total` of prices of all the items in the cart, and on server you want to create an event for `Total > 300`, you should to assign unique ids to the text filed control. This can be done by setting the tag property of the `UIView`.

Captured during execution

These values are captured at a regular time interval you can set for each logging level with TimeBetweenSnapshots in TLFLevelsConfiguration.plist.

Note: According to Apple, the API used to retrieve the battery level from the device is not always in sync with the value that displays on the device. See http://iphonedevelopertips.com/device/display-battery-state-and-level-of-charge.html. In addition, the value is updated only in 5% increments. See http://www.iphonedevsdk.com/forum/iphone-sdk-development/14301-battery-level.html for more information.

Name	Description
freeMemory	The memory that is remaining.
freeStorage	The storage that is remaining.
battery	The value that is returned by `( [UIDevice currentDevice].batteryLevel ) * 100`.
carrier	The current network carrier.
networkReachability	The network status (`Unknown`, `NotReachable`, `ReachableViaWiFi`, or `ReachableViaWWAN`).
ip	The IP address of the device.
orientation	0 if `[[UIDevice currentDevice] orientation]` returns `UIDeviceOrientationPortrait`, `UIDeviceOrientationFaceDown`, or `UIDeviceOrientationFaceUp`. 90 if `UIDeviceOrientationLandscapeRight`. 180 if `UIDeviceOrientationPortraitUpsideDown`. 270 if `UIDeviceOrientationLandscapeLeft`.

Guidelines and tips

Apply the following tips to your application development and integration of the IBM Tealeaf iOS SDK:

Use the killswitch to control logging of the iOS application
Add IDs for all UI controls that you want to capture
Apply privacy masking or blocking of all sensitive customer data through the iOS SDK
Due to the way JSON messages are captured and transmitted, force a submission of all queued messages before you allow users of your mobile native application to open a web view. If this step is not done, hits can appear to be out of order during replay in IBM Tealeaf.

Tealeaf iOS SDK Tutorials

Relevant recipes and other tutorials

How do I implement conditional initialization with the UI Capture SDK?