Framework and logging

There are several methods for managing the framework, including session management, performance optimization, and delegating callbacks.

The recommended approach for managing session identifiers is to allow your web server to generate the session identifier for insertion into the TLTSID field in the request. This session identifier is consumed and used seamlessly in Acoustic Tealeaf.

You can improve the performance of your application by choosing logging levels carefully and advising the framework about good times to post its data to the server.

You can implement some or all of these methods of TLFLibDelegate to help the framework to work with your application and its server. The easiest way is to add the TLFLibDelegate protocol to your application delegate class, as shown.

Required framework and library files

The Acoustic Tealeaf iOS SDK requires the following frameworks to be linked to your application.

Most applications already include Foundation.framework and UIKit.framework. SystemConfiguration.framework is used for controlling and monitoring the framework's networking.

• Foundation.framework
• UIKit.framework
• WebKit.framework (for iOS version 8 and later)
• SystemConfiguration.framework
• CoreGraphics.framework
• CoreTelephony.framework
• libz.dylib (For use with iOS version 8.)
• libz.tdb (For use with iOS version 9 and later.)

Application data

Application data is consistent across each run of your application on a specific device, except for changes to software version numbers after application upgrades. This data is reported in the [AppEnv]section of the request.

The user ID is generated by the framework and is unique for each installation of your application on a device.

• It is consistent each time your application starts.
• A single user with multiple devices receives multiple user IDs.

Session management

Whenever possible, the approach for managing session identifiers is to allow your web server to generate the session identifier for insertion into the TLTSID field in the request. This session identifier is consumed and used seamlessly in Acoustic Tealeaf.

If necessary, you can generate a session identifier locally by using the iOS SDK. Information about this method follows; however, use this method only if your web server cannot be configured to generate the session identifier.

The iOS SDK starts a session whenever the application starts. It must completely terminate to start a new session and not go to the background.

• To generate a session identifier through the Acoustic Tealeaf iOS SDK, you implement the sessionIdGeneration API of TLFLibDelegate.
• To acquire the current session identifier, call the currentSessionId method of TLFApplicationHelper.

This behavior may not make sense for your application. For example, if you want a new session to begin after every successful purchase, you can use the startNewTLFSession method of TLFApplicationHelper.
The locally generated session ID is reported as a cookie with all framework posts and is automatically stored.
It is stored in the request that is based on how your Acoustic Tealeaf environment is configured to manage session identifiers.

startNewTLFSession

Tells the Acoustic Tealeaf iOS SDK to start a new session. This does not affect the behavior of the iOS SDK on the client, but helps you to analyze data that is received by the server. For example, at the end of a purchase, you can count further user interactions as belonging to a separate session, so you can call this method whenever the user completes a purchase.

- (void)startNewTLFSession

Declared in TLFApplicationHelper.h

currentSessionId

Returns the session ID for the current session. This can be a session ID generated by the iOS SDK, but if you implemented the sessionIdGeneration method, then it is the session ID last returned by that method.
- (NSString *)currentSessionId

Returns the current session ID.

Declared in TLFApplicationHelper.h.

Performance optimization

You can improve the performance of your application by choosing logging levels carefully, and by advising the iOS SDK about when to post its data to the server.

requestManualServerPost

Requests the iOS SDK to post to the server as soon as possible. It is a good idea to call this method after you finished your own network transmissions. The device shuts down the WiFi and cell radios when there is no activity. Powering up the radio takes time and battery power, so it is better to transmit in bursts.

You must set ManualPostEnabled in TealeafBasicConfig.plist to YES for this method to succeed.

- (void)requestManualServerPost

Declared in TLFApplicationHelper.h.

Delegate callbacks

You can implement some or all of these methods of TLFLibDelegate to help the iOS SDK to work with your application and its server.

The easiest way is to add the TLFLibDelegate protocol to your application delegate class, as shown.

#import "TLFLibDelegate.h"
...
@interface MyAppDelegate : NSObject <UIApplicationDelegate, TLFLibDelegate> {
...
}

sessionIdGeneration

Implemented by your application to provide a session ID to the framework. This does not affect how the framework operates on the client, but is useful when analyzing logged data later. This lets you tie sessions on your server with sessions recorded by the iOS SDK.

- (NSString *)sessionIdGeneration

Returns the session ID for the framework to record with its logs.

Declared in TLFPublicDefinitions.h.

Logging templates

Logging levels can be set from 0 to 5. Logging templates can be configured to assist with these settings.
You can configure logging templates for the following network types.

When you configure the base logging level for the iOS SDK, a template of items is preselected for logging.

Logging level legend

To configure the logging level, you set the LoggingLevel value in the TLFLevelsConfiguration.plist file.
Use one of the following values.

• If any control event is set to 0, that event is never logged.
• Based on the device network (Cellular or WiFi) and the UI control values in TLFLevelsConfiguration.plist, events are captured and posted to the Acoustic Tealeaf Target page.

Guidelines for tuning iOS Logging Framework

After you get started with the Tealeaf iOS SDK, you make configuration changes that data is collected in a way that is easy to analyze and respectful of your user's privacy. You can also tune the framework so that its work does not interfere with your application's performance.

Session identifiers

The iOS SDK is most powerful as part of a complete Tealeaf system that shows the user activity and device information that is captured by the framework alongside your application's own network activity. The key to organizing all these events is the notion of a session.

A session is a set of related actions that are marked by a common identifier. To join the data from the iOS SDK with your application&'s own data, both sets must share this common identifier.

The best solution for generating session identifiers is to force the first hit of your mobile native application to be a web hit to the web server. Then, the mobile native application can use the generated session identifier as the identifier for the session on the client. Ideally, this value is the TLTSID value that is generated for non-mobile sessions. Other methods of generating session identifiers are not officially currently supported.

For more information about configuring sessioning, see Quick start server configuration in Tealeaf for iOS

If you cannot force the first hit to be a web server hit, then the mobile native application must generate a session identifier locally. This session identifier is submitted as a cookie.

Data collection

To collect data with the iOS SDK, you assign logging levels and identify elements in the user interface. You can also collect extra data and custom events.

Establishing logging levels

Each logging element (a user action, event, or environment data item) has a logging level, 0 - 3. The logging levels are nested. For example, all level 1 elements are included in level 2. Therefore, you assign low logging levels for the most important items.

The logging level is sometimes referred to in the code as a monitoring level and the terms are interchangeable. The framework can have a monitoring level of 0, meaning that no logging takes place. However, each element must have a logging level 1 - 3, where 1 is the lowest logging level and 3 is the highest logging level.

You assign logging levels in the file TLFLevelsConfiguration.plist, part of TLFResources.bundle. Each element is represented by a numeric Item ID, listed in the reference.

📘

Note:

Do not modify the Tealeaf provided property lists. Be sure to not change the structure or the key names in the property list files that are located inside the bundle TLFResources.bundle.

The framework maintains a current logging level. The item LoggingLevel inside TealeafBasicConfig.plist is used the first time your application launches. You can change the current logging level at run time by using a method of the TLFApplicationHelper class:

-(void)setCurrentMonitoringLevelType:(kTLFMonitoringLevelType)
       monitoringLevelType;

The framework remembers this logging level even when the application goes to the background or exits.

Identifying user interface elements

If your view controllers and buttons inherit from the standard iOS classes, like UIViewController and UIButton, the framework can record their activity. The framework also sends the class names of view controllers and controls, so analysts see these names when they study the application's behavior. The framework sends tag values and puts them in the path names that are used to identify captured data.

Choosing unique tag values for your controls makes it much easier to analyze data when it reaches the server. If the tag values are not unique, the controllers, for example text fields, buttons, and keyboards, might not appear in the correct order in the navList in replay, especially after the orientation is changed rapidly and repeatedly.

Collecting extra data

The framework can be configured to log extra data through convenience methods that present data to the server in a standard format. Examples follow.

• Error return values, where you can log NSErrorvalues.
• Objective-C exceptions, so you can pass in NSException objects from your application's exception handler.
• GPS location coordinates, so you can log location from your application's location change handler.
• Wireless carrier information.

Custom events

If the standard elements tracked by the framework are still not enough, you can create your own custom events.

You can use the TLFCustomEvent class to define your own events.

Performance optimization

Different techniques are available for optimizing device and network performance.

Kill switch

The kill switch is a control mechanism that prevents the framework from initializing and having any further effect on your application. To disable the framework:

• Disable a page on your server.
• Force the server to return a status code outside the range of 200-399.
  The kill switch is checked each time that the application starts.

For the kill switch to function, you must configure it in the file TealeafBasicConfig.plist inside TLFResources.bundle.

• KillSwitchEnabled:YES means that the URL is checked before the rest of the framework initializes; NO means that the framework is always initialized.
• KillSwitchURL: The URL to check. When the page is reachable, the framework initializes. If the page is not reachable, because of network problems or because you disabled it on your server, the framework does not initialize.
• KillSwitchTimeout: How long in seconds to wait for a response from the kill switch before the next try or giving up.
• KillSwitchTimeInterval: If there is no response from the page, this tells the framework how many seconds to wait before the next try.
• KillSwitchMaxNumberOfTries: How many times to try to get a response from the kill switch page before giving up.

Initialization

You can configure the framework to delay its initialization for a fixed time so that it does not interfere with your application's responsiveness when starting. DelayTimeOfTLFInitialization inside TealeafBasicConfig.plist tells the framework how long to wait, in seconds, before initializing.

Network performance

You can define when the framework synchronizes data with the server so that you can optimize network performance and make sure that logging data gets sent to the server in a timely way.

The framework monitors the following situations. You can set them up to cause a post of data to the server.

• When the application goes to the background, which gives the framework a chance to send the most recent data to the server. The user's intention may be to quit and not run the application soon. See DoPostAppGoesToBackground.
• When the application comes from the background, to check for any data that the framework was unable to send. See DoPostAppComesFromBackground.
• When the application is started, to check for any data the framework was unable to send, as well as a report of the app crashing last time it was run. See DoPostAppIsLaunched.
• When the screen changes, so data is sent to the server when a screen's worth of interactions were logged. See DoPostOnScreenChange.

While the application is running, you can also set up posts:

• At regular time intervals. See DoPostOnIntervals and PostTimeIntervals.
• When you call a method that tells the framework to post. See ManualPostEnabled and the method requestManualServerPost.

You can limit the packet size that is used for posting to the server with PostMessageMaxBytesSize if you need to make sure that the framework does not take too much time to transmit.

You can also limit the total network activity per launch of your application. See MaxNumberOfPostsPerActivation and MaxNumberOfBytesPerActivation.

Intelligent local cache

You can configure the framework to balance its use of local storage, memory, and network bandwidth.

• You can turn off the cache, which makes the framework rely on RAM, but prevents it from writing potentially sensitive data to local storage. See HasToPersistLocalCache.
• You can adjust the size of the cache in local storage. See CachedFileMaxBytesSize and {MaxLoggedElementsSize.
• You can adjust the size of what is cached in memory. See MemoryWarningMaxMemoryBytesSize to have the framework respond automatically to low memory warnings.

The framework uses logging levels to manage how much it logs, stores, and posts. These are independent from one another. For example, if it can log at a high level and transmit over WiFi at that same level, you can collect much data when the user has a good connection. However, you could set the caching level lower so that if you lose your network connection, only the most important data gets stored and sent later.

See CachingLevel, PostMessageLevelCellular, and PostMessageLevelWiFi.