Configuration
Configuration options and examples for Android SDK and iOS SDK for Tealeaf
There are several settings you can configure to capture data from your applications. You can configure most of the basic global settings in the TealeafBasicConfig file. Some settings configuration in the EOCoreBasicConfig file and TealeafLayoutConfig.json file.
Application key
The application key identifies and sessionizes mobile applications with Tealeaf services.
Use a unique Application Key for each mobile application. You may also capture the same data from more than one application. In such cases, you can use the same application key for all the applications. You can then group the data captured from the various application as a single entity.
Contact your administrator for the value of the application key for the SaaS service. The on-premises service may use cookies for sessionization. If cookies are used, then use TLTSID as the cookie name.
Setting ID | Value |
---|---|
AppKey | string |
Kill switch
A kill switch is a mechanism that lets you disable the Connect library remotely on end users' devices. When you enable the kill switch setting, you must provide the URL for the application. The kill switch settings verify if the URL is reachable or not.
Settings ID | Value | Description |
---|---|---|
KillSwitchEnabled | yes/no | Set the value to yes to check the kill switch target page before starting. If you set the value to no, the framework starts immediately. |
KillSwitchUrl | URL | Provide the URL to check for the kill switch. When the kill switch is enabled, the framework checks the URL you provide here. It requires a successful response from the check to initialize. |
KillSwitchMaxNumberOfTries | Integer | Set the number of times the framework should check for the kill switch URL before giving up. This value should be set to at least 1. |
KillSwitchTimeInterval | Seconds | Set the time the framework should wait before rechecking the kill switch URL if it is not responding. |
UseWhiteList | yes/no | Set to yes if you want the framework to check the whitelist of phone IDs when kill switch is enabled. When set to yes, the framework requires a phone ID to assign. When set to no, the framework defaults to use random sampling. |
WhiteListParam | Current whitelist server-ID | Provide the whitelist ID that corresponds to the phone ID assigned. |
KillSwitchTimeout | Seconds | Set the timeout value for the HTTP request that checks for the kill switch. |
Settings ID | Value | Description |
---|---|---|
KillSwitchEnabled | true/false | Set the value to true to check the kill switch target page before starting. If you set the value to false, the framework starts immediately. |
KillSwitchUrl | URL | Provide the URL to check for the kill switch. When the kill switch is enabled, the framework checks the URL you provide here. It requires a successful response from the check to initialize. |
KillSwitchMaxNumberOfTries | Integer | Set the number of times the framework should check for the kill switch URL before giving up. This value should be set to at least 1. |
KillSwitchTimeInterval | Seconds | Set the time the framework should wait before rechecking the kill switch URL if it is not responding. |
UseWhiteList | true/false | Set to true if you want the framework to check the whitelist of phone IDs when kill switch is enabled. When set to true, the framework requires a phone ID to assign. When set to false, the framework defaults to use random sampling. |
WhiteListParam | Current whitelist server-ID | Provide the whitelist ID that corresponds to the phone ID assigned. |
KillSwitchTimeout | Seconds | Set the timeout value for the HTTP request that checks for the kill switch. |
Cookie settings
Settings ID | Value | Description |
---|---|---|
SessionizationCookieName | String | Provide the cookie parameter used for the sessionization of the application. For example, TLTSID or JSESSIONID. |
disableTLTDID | Yes/No | The TLTDID is a cookie used to identify a visitor's device uniquely. A Device ID, or device identifier, helps distinguish between different devices and associate specific events with them. The device identifier is a unique alphanumeric string stored in the TLTDID cookie by default. You can disable the TLTDID cookie by setting the property disableTLTDID to yes in TealeafBasicConfig.plist. |
Settings ID | Value | Description |
---|---|---|
CookieUrl | String | Provide the cookie URL—for example, http://m.staussandplesser.com. |
CookieParam | String | Provide the cookie parameter used for the sessionization of the application. For example, TLTSID or JSESSIONID. |
CookiePath | String | Provide the path of the cookie. For example, /. |
CookieDomain | String | Provide the domain of the cookie. For example, .straussandplesser.com. |
CookieExpires | true/false | Set to true to let the cookie expire. |
CookieSecure | true/false | Set to true to add a secure parameter to the cookie. You can use this setting only in HTTPS post URLs. |
CookieExpiresFormat | Valid date formats: ASCTIME, RFC1036, or RFC1123 | Set a valid date format to indicate the cookie expiration format. |
disableTLTDID | True/False | The TLTDID is a cookie used to identify a visitor's device uniquely. A Device ID, or device identifier, helps distinguish between different devices and associate specific events with them. The device identifier is a unique alphanumeric string stored in the TLTDID cookie by default. You can disable the TLTDID cookie by setting the property disableTLTDID to true in the module section for TLCookie.
|
Session timeout
Settings ID | Value | Description |
---|---|---|
SessionTimeout | Minutes | Set the timeout value for the session. When set, the expiration of the cookie is the current time plus the session timeout value. |
Settings ID | Value | Description |
---|---|---|
SessionTimeout | Minutes | Set the timeout value for the session. When set, the expiration of the cookie is the current time plus the session timeout value. |
SessionTimeoutKillSwitch | true/false | Set to true to call the kill switch to create a new session ID. The default setting is false. |
Screenshot
The screenshot setting controls how screenshots are captured. You can store screenshots in memory instead of in the local memory on the device. To store in memory, set PersistLocalCache to no in the local cache file settings.
Settings ID | Value | Description |
---|---|---|
ScreenshotFormat | PNG/JPG | Provide the format of the screenshot. |
PercentOfScreenshotsSize | Integer, 1-100 | Set what percentage of the original screenshot pixel dimensions are submitted. |
PercentToCompressImage | Integer, 1-100 | Set the percentage to compress an image. You can use this setting only for JPG images. PNG images ignore this setting and default to 100. |
ScreenShotPixelDensity | Integer, 0,1.5,2,3,3.5,4 | Set a pixel density for the screenshot. The screenshot is taken at the specified density, irrespective of a device's pixel density. If you use 1.5 as the pixel density, captured images are between 12 KB to 20 KB, and replay fidelity is good. When pixel density is set higher than 1.5, fidelity is better, but the file size is larger. When pixel density is set to 1 and lower, images are blurred with smaller file sizes. Valid values are 0 and higher. Default is 1.5. |
Capture native layout
Configure the following settings to capture the screen layout.
Settings ID | Value | Description |
---|---|---|
LogViewLayoutOnScreenTransition | yes/no | Set to yes, to log the screen layout. When set to no, the screen layout is not logged and produces type 10 data. |
GetImageDataOnScreenLayout | yes/no | Set to yes for prototyping to view base64 data sent to the server. The prototyping helps display images correctly during replay. You should extract the image data later. Then set it up on the server, and switch to no for production of the application to be released. |
Settings ID | Value | Description |
---|---|---|
LogViewLayoutOnScreenTransition | true/false | Set to true, to log the screen layout. When set to false, the screen layout is not logged and produces type 10 data. |
GetImageDataOnScreenLayout | true/false | Set to true for prototyping to view base64 data sent to the server. The prototyping helps display images correctly during replay. You should extract the image data later. Then set it up on the server, and switch to no for production of the application to be released. |
Gesture enabled
Configure the following settings to capture gestures.
Settings ID | Value | Description |
---|---|---|
SetGestureDetector | yes/no | Set to yes to log gestures. When set to no, gestures are not logged and produce type 11 data. |
CaptureNativeGesturesOnWebview | yes/no | Set to yes to log the gestures in a webview. When set to no, the gestures are not logged and produce type 11 data. The default is set to no. It is better to have the gesture data for the webview from the UI Capture library. The UI Capture library has better information on the webview. |
Settings ID | Value | Description |
---|---|---|
SetGestureDetector | true/false | Set to true to log gestures. When set to false, gestures are not logged and produce type 11 data. |
CaptureNativeGesturesOnWebview | true/false | Set to true to log the gestures in a webview. When set to no, the gestures are not logged and produce type 11 data. The default is set to false. It is better to have the gesture data for the webview from the UI Capture library. The UI Capture library has better information on the webview. |
Auto-geolocation
Configure the following settings to capture location.
Settings ID | Value | Description |
---|---|---|
LogLocationEnabled | yes/no | Set to yes to log the location. When set to no, the location is not logged and doesn't produce type 13 data. |
Settings ID | Value | Description |
---|---|---|
LogLocationEnabled | true/false | Set to true to log the location. When set to false, the location is not logged and doesn't produce type 13 data. |
LogLocationTries | Integer | Set the number of times to try to get the location. You should set it to at least 1. |
LogLocationTimeout | Seconds | Set the amount of time to wait before trying to get a location if it was unable to be obtained the first time. |
For example, when the device signal is weak if you want the device to try three times to get the geolocation signal and for the device to wait 30 seconds between retries, you must set the configurable items as follows:
#Auto Geolocation logging enabled or not
LogLocationEnabled = true
LogLocationTries = 3
LogLocationTimeout = 30
Auto-instrumentation
Settings ID | Value | Description |
---|---|---|
DisableAutoInstrumentation | yes/no | Set the value to no and install the TeaCuts.jar to enable auto-instrumentation. |
Android enables the use of one handler at a time for any object. As a result, auto-instrumentation is not supported in Tealeaf. You must apply instrumentation as part of your application development.
Post settings
The post settings help manage the data posted from the framework to the server. You can configure the post settings in the EOCoreBasicConfig and the TealeafBasicConfig files.
Configure the following in the TealeafBasicConfig file.
Settings ID | Value | Description |
---|---|---|
PostMessageUrl | URL | Provide the URL for posting data to your server.Note: To enable secure transport between the logging framework and the target page, configure the URL, to begin with, https://. |
DoPostOnScreenChange | true/false Default is false | Set to true if you want the SDK to post data when the app transitions from one UIViewController to another. Change the default settings in the EOCoreBasicConfig.plist file. Set DoPostOnIntervals to yes and PostMessageTimeIntervals to a positive value. |
PrintScreen | Integer, 0-3 | Set the logging level of a screenshot to be sent to the server.
|
MaxStringsLength | Integer | Set the maximum string length to be sent to the target page per value in log statements. It prevents long strings from taking up storage and bandwidth. Note: This value must be at least 1. |
Settings ID | Value | Description |
---|---|---|
PostMessageUrl | URL | Provide the URL for posting data to your server. Note: To enable secure transport between the logging framework and the target page, configure the URL, to begin with, https://. |
Connection | Integer, 0-3 | Set the logging level of connection events of type connection to be sent to the server that produces type 3 data.
|
PrintScreen | Integer, 0-3 | Set the logging level of a screen shot to be sent to the server.
|
MaxStringsLength | Integer | Set the maximum string length to be sent to the target page per value in log statements. It prevents long strings from taking up storage and bandwidth. Note: This value must be at least 1. |
You can also configure the following settings in the EOCoreBasicConfig file.
Settings ID | Value | Description |
---|---|---|
PostMessageLevelWiFi | Integer, 0-3 | Set the logging level of events to be sent to the server over Wi-Fi when network performance is good.
|
PostMessageLevelCellular | Integer, 0-3 | Set the logging level of events to be sent to the server over the cellular (3G) network.
|
ManualPostEnabled | true/false | Set to true to manually post the data from the framework to the server. The data is posted only when the requestManualServerPost method is called. When set to false, you must also configure the DoPostOnIntervals and PostMessageTimeIntervals settings. |
DoPostOnIntervals | true/false | Set the value to true to post data from the framework to the server at regular time intervals. You must specify the time intervals using the postMessageTimeIntervals setting. Note: The value must be set to true if you set the ManualPostEnabled as false. ManualPostEnabled and Do postOnIntervals cannot be enabled or disabled at the same time. At least one of these settings must be set to true. |
PostMessageTimeIntervals | Seconds | Set the seconds to configure how often you want the framework to post the data to the server. When the DoPostOnIntervals is set to true, the data is posted regularly at the time interval you set here. |
DoPostAppComesFromBackground | yes/no | Set to yes to send data to the server when the application comes from the background. |
DoPostAppGoesToBackground | yes/no | Set to yes to send data to the server when the application goes to the background. |
DoPostAppGoesToClose | yes/no | Set to yes to send data to the server when the application closes. |
DoPostAppIsLaunched | yes/no | Set to yes to send data to the server when the application starts. |
DoPostOnScreenChange | yes/no | Set to yes to send data when the screen changes, subject to ScreenTimeNeededToPost. |
DynamicConfigurationEnabled | yes/no | Set to yes to enable the kill switch. To use the iOS SDK libraries, set the value to yes, and call enableTealeafFramework. If the kill switch is not implemented, set the value to no for libraries to load. |
Settings ID | Value | Description |
---|---|---|
PostMessageLevelWiFi | Integer, 0-3 | Set the logging level of events to be sent to the server over Wi-Fi when network performance is good.
|
PostMessageLevelCellular | Integer, 0-3 | Set the logging level of events to be sent to the server over the cellular (3G) network.
|
ManualPostEnabled | true/false | Set to true to manually post the data from the framework to the server. The data is posted only when the requestManualServerPost method is called. When set to false, you must also configure the DoPostOnIntervals and PostMessageTimeIntervals settings. ManualPostEnabled and Do postOnIntervals cannot be enabled or disabled at the same time. At least one of these settings must be set to true. |
DoPostOnIntervals | true/false | Set the value to true to post data from the framework to the server at regular time intervals. You must specify the time intervals using the postMessageTimeIntervals setting. Note: The value must be set to true if you set the ManualPostEnabled as false. ManualPostEnabled and Do postOnIntervals cannot be enabled or disabled at the same time. At least one of these settings must be set to true. |
PostMessageTimeIntervals | Seconds | Set the seconds to configure how often you want the framework to post the data to the server. When the DoPostOnIntervals is set to true, the data is post posted regularly at the time interval you set here. |
Local cache
Use the Local cache file settings to manage the local cache in the device used to log data. The local cache file settings are configured in the EOCoreBasicConfig file.
Settings ID | Value | Description |
---|---|---|
PersistLocalcache | yes/no | Set the value to yes to store data in the device’s local storage instead of the memory. You must also configure the Cachinglevel setting. |
CachingLevel | Integer, 0-3 | Set the level for caching data. You can set the value from 0 to 3, where
|
Settings ID | Value | Description |
---|---|---|
PersistLocalcache | true/false | Set the value to true to store data in the device’s local storage instead of the memory. You must also configure the Cachinglevel setting. |
CachingLevel | Integer, 0-3 | Set the level for caching data. You can set the value from 0 to 3, where
|
Log level settings
You can use the Log level settings to manage the data that is logged during a session. The log level settings are configured in the EOCoreBasicConfig file.
Settings ID | Value | Description |
---|---|---|
LoggingLevel | Integer,0-3 | Set the level for logging data. You can set the value from 0 to 3, where
|
Settings ID | Value | Description |
---|---|---|
LoggingLevel | One of the following values: - 0 - does not send log data.- 1 - logs the highest priority (critical) data.- 2 - logs the medium priority (important) data.- 3 - logs the lowest priority (information) data. | Sets the level for logging data. The setting applies only when the log level is not indicated in the log statement. |
DisplayLogging | Boolean | Enable the setting to display debug log statements in LogCat. Filter for the UICAndroid tag in the LogCat. |
Auto layout
AutoLayout logs type 10 screen layouts for screen views of native mobile application sessions. It also enables the application to continue logging type 10 screen layouts when it resumes to the foreground.
You can configure the auto layout setting in the TealeafLayoutConfig.json file. Each AutoLayout entry has the following sub-entries.
Setting ID | Value | description |
---|---|---|
ScreenChange | Boolean | Set to true to capture type 2 for the screen. set to false if you do not want to track the screen. |
DisplayName | String | Provide the name of the screen to be shown during the replay. This shows the name of the screen instead of the view controller name or activity name. DisplayName is displayed during replay in the navigation list. If DisplayName is empty, the view controller class name is used. |
CaptureLayoutDelay | Numeric | Set the time in milliseconds to delay before you want to capture the layout of a screen. If you increase the value, the time between layout load and layout logging increases. The CaptureLayoutDelay value is used for ScreenChange and ScreenShot. |
ScreenShot | Boolean | Set to true to capture screenshots on type 2, 4, 10, 11 for the screen. Set to false if you do not want to capture screenshots on the screen. |
CaptureUserEvents | Boolean | Set to true to resume capturing user events (type 4, 11) on the specified screen. Set to false to pause capturing type 4, 11 events. Events are not captured based on the CaptureScreenVisits and capturescreen load/unload events. |
CaptureLayoutOn | Numeric | Set the level for when you want to capture the layout. You can set the value from 0 to 2, where:
|
CaptureScreenshotOn | Numeric | Set the level for when you want to capture screenshots for view controller load events. You can set the value from 0 to 2, where:
|
NumberOfWebViews | Numeric | Provide the value to indicates the amount of web views on the page. Default value is 0. |
CaptureScreenVisits | [Boolean] | Use this setting to indicate whether you want ScreenView messages [type 2] objects on pages that you set CaptureUserEvents to false. This property helps you understand how your users use your application by showing how they get to a page. The default value is true. Set this entry to false if you do not want to track screen load/unload events. CaptureScreenVisits setting applies only if the CaptureUserEvents setting is set to false. If the CaptureUserEvents setting is true, the CaptureScreenVisits setting is ignored. The load/unload events are tracked because it doesn't make sense to track user events on a screen where visits are not tracked. |
Assign an identifier to a target item
To assign an identifier to a target item, add the AppendMapIds
key to the TealeafLayoutConfig.json file. You can assign a readable identifier to the mid that maps to the target item. You can then configure events to fire when the identifier is encountered. You can use the same identifier for Android devices as well as iOS devices. When you assign the same identifier to your Android and iOS devices, you can create a single event in Event Manager that fires on the identifier. The event fires for both Android and iOS devices.
For example:
"AppendMapIds": {
"[PWDV,0][ABOL,0][FL,0][TH,0][LL,0][TW,0][LL,1][LL,0]": {
"mid": "LoginButton"
},
"ibm.com.demoapp.main_activity_login:id\/send": {
"mid": "LoginButton"
}
}
Uses the mid setting to assign an identifier to two targets. The first target is for an iOS device, and the second target is for an Android device. The target for both devices is identified as LoginButton. You can create a single event that fires when LoginButton is encountered in either application.
The following snippet is an example of a TealeafLayoutConfig.json file:
{
"AutoLayout": {
"GlobalScreenSettings":{
"ScreenChange": true,
"DisplayName": "",
"CaptureLayoutDelay": 500,
"ScreenShot": false,
"NumberOfWebViews": 0,
"CaptureUserEvents": true,
"CaptureScreenVisits": true,
"CaptureLayoutOn": 2,
"CaptureScreenshotOn": 0
},
"PaymentActivity":{
"ScreenChange": false,
"DisplayName": "The Payment Screen",
"CaptureLayoutDelay": 500,
"ScreenShot": false,
"NumberOfWebViews": 0,
"CaptureUserEvents": false,
"CaptureScreenVisits": true,
"CaptureLayoutOn": 0,
"CaptureScreenshotOn": 0
}
},
"AppendMapIds": {
"[w,9290],[v,0]": {
"mid": "ASimpleUIView"
},
"tag2999999": {
"mid": "giveAdditionalId1"
},
"idxPathValue": {
"mid": "giveAdditionalId2"
}
}
}
Updated 18 days ago