Android SDK overview

Acoustic Tealeaf can monitor traffic between your application and server. It captures device context and user activity so that you can monitor and evaluate the performance of your applications.

The Tealeaf Android SDK supports instrumenting your native and hybrid Android applications for logging and analysis. You can get unprecedented insight into the performance of your application when you use the SDK.

The Android SDK was designed for simple implementation. It uses standard Android classes and user interface controls to track user interface events and minimizes the impact on your application's performance.

πŸ“˜

Note:

For a quick and easy implementation of the Tealeaf SDK in your Android applications, see the Quick start guide for web applications.

🚧

Warning:

Tealeaf client frameworks do not support the forwarding of application data to third-party systems. Application data must be forwarded to the server that hosts the native application.

Requirements for android environments

To develop Android applications with the Android SDK, follow these system and software requirements:

  • API level 21 to 34

  • Supports Android Studio Flamingo | 2022.2.1 Patch 2, Gradle 7.4.2, Kotlin 1.8.10

πŸ“˜

Note:

Tealeaf has passed all Apple Store and Google Play Store regulations. Contact Acoustic support if an issue arises with the Tealeaf library related to Apple Store and Google Play Store scanning requirements.

Supported frameworks

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

Acoustic Tealeaf Android package contents

You can download the Android SDK package from Acoustic Analytics SDK tools. The package contains the following folders:

  • EOCore folder - Contains base jar and aar library needed for Tealeaf and Digital Analytics to communicate to the server.
  • TealeafMod folder - Contains jar and aar library to collect Tealeaf data passed to EOCore.
  • [NativeTemplates](https://github.com/acoustic-analytics/SDK_Tools/tree/master/NativeTemplates) folder - Contains the latest native templates compatible with the library.
  • [KillSwitch](https://github.com/acoustic-analytics/SDK_Tools/tree/master/KillSwitch) folder - Contains a basic kill switch implementation for JSP, ASP.Net, and PHP servers.

Sample applications

The SampleCode folder contains several sample applications that demonstrate integrating and using the library.

Auto instrumentation sample apps

  • Android native Kotlin app - SampleCode_Tealeaf_Android_Kotlin_KitchenSink
  • Android native Java app - SampleCode_Tealeaf_Android_DarkHoloAuto
  • Hybrid app - SampleCode_Tealeaf_HybridHtmlEmbeddedAuto

Impact on device resources

In benchmark tests, the Android SDK has the following effects on the 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 it is reachable. The SDK will store up to 512,000 bytes to the device memory by default. The oldest data is truncated and deleted if the cache grows larger than 512,000 bytes. The cache size is managed through the CachedFileMaxBytesSize setting in EOCoreAdvancedConfig.json.

  • Minimal effect on battery life

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.

NameDescription
pixelDensityValue that is returned by [[UIScreen mainScreen] scale]
deviceWidthValue that is returned by [[UIScreen mainScreen] bounds].size.width.
deviceHeightValue that is returned by [[UIScreen mainScreen] bounds].size.height.
widthValue that is returned by pixelDensity*deviceWidth.
heightValue that is returned by pixelDensity*deviceHeight.
osVersionVersion of Android running on the device.
totalStorageTotal storage on the device, free+used.
totalMemoryTotal memory of the device, free+used.
manufacturerThe manufacturer of the product/hardware.
userIDUnique user ID generated by the Android SDK for the current instance of the application.
appVersionVersion of the Android application.
deviceModelType of device.
appNameName of the current application.
orientationTypeThe orientation of the device (PORTRAIT, LANDSCAPE, FLAT, or UNKNOWN).
localeCurrent locale (for example, en).
languageCurrent language (for example, English).
osTypeThe type of device used during capture.
tagAll 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.

NameDescription
freeMemoryThe memory that is remaining.
freeStorageThe storage that is remaining.
batteryThe value that is returned by ( [UIDevice currentDevice].batteryLevel ) * 100.
carrierThe current network carrier.
networkReachabilityThe network status (Unknown, NotReachable, ReachableViaWiFi, or ReachableViaWWAN).
ipThe IP address of the device.
orientation0 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 Acoustic Tealeaf Android SDK:

  • Use the kill switch to control logging of the Android application
  • Add IDs for all UI controls that you want to capture
  • Apply privacy masking or blocking of all sensitive customer data through the Android 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 Acoustic Tealeaf.
  • When enabling the Tealeaf library for supported Android OS API levels, follow this best practice:
if(Build.VERSION.SDK_INT>=21&&Build.VERSION.SDK_INT<=34){
  Tealeaftealeaf=newTealeaf(this.getApplication());
  Tealeaf.enable();
}