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.
Name | Short Name | Value |
---|---|---|
Device Model | deviceModel | The model of the device: Unknown , iPad , iPhone , or iPod . |
User ID | userId | A unique framework-generated ID for this user. |
iOS Version | osVersion | The iOS system version of the device. |
Application Name | appName | The name of the application. |
Application Version | appVersion | The version of the application. For example, CFBundleVersion. |
Tag | 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 . |
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 ofTLFLibDelegate
. - To acquire the current session identifier, call the
currentSessionId
method ofTLFApplicationHelper
.
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.
Network | Configuration Setting | Default Logging Level |
---|---|---|
Cellular | PostMessageLevelCellular | 1 |
WiFi | PostMessageLevelWiFi | 3 |
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
NSError
values. - 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
andPostTimeIntervals
. - When you call a method that tells the framework to post. See
ManualPostEnabled
and the methodrequestManualServerPost
.
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
.
Updated 18 days ago