Blue Triangle SDK for iOS Installation Guide

Introduction

The Blue Triangle SDK for iOS enables application owners to track their users’ experience so they can focus on user experience issues that impact their business outcomes.

PLEASE read through the mandatory instrumentation instructions to ensure that 

• Mobile native views are reported for views and performance

• User sessions are properly stitched between mobile native views and webviews

• Network details are reported (detailed backend interaction, errors etc.)

• Checkout events are reported

Instrumenting Your App with the Blue Triangle SDK

iOS SDK Default Values

Mandatory Installation Steps

SDK Installation

To download the latest iOS SDK, please visit https://github.com/blue-triangle-tech/btt-swift-sdk. 

Installation using Swift Packages Manager

To integrate Blue Triangle using Swift Packages Manager into your iOS project, follow these steps:

• Go to File > Add Packages

• Enter the package repository URL: https://github.com/blue-triangle-tech/btt-swift-sdk.git

• Click Add Package.

Xcode 11-12:

• Go to File > Swift Packages > Add Package Dependency

• Enter the package repository URL: https://github.com/blue-triangle-tech/btt-swift-sdk.git

• Follow the instructions

Installation using CocoaPods

To integrate BlueTriangle using CocoaPods into your iOS project, you need to follow these steps:

• Open 'Podfile' in text mode and add the following:

pod 'BlueTriangleSDK-Swift'    

•  Save the Podfile and run the following command in the terminal to install the dependencies:

pod install    

Site ID Configuration

In order to use Blue Triangle, the Site ID needs to be configured in the SDK.

Find your site ID by:

• Login to https://portal.bluetriangletech.com 

• Click on "Settings" icon

• Open the Sites page under the Settings Modal. (Logged in user needs to have access to Sites page)

• Get the value for Site ID from the "Tag Prefix" column for the desired "Site Name"

• Replace <BTT_SITE_ID> with your site ID in the following areas:

  • It is recommended to do this in:

    • AppDelegate.application(_:didFinishLaunchingWithOptions:)

               OR

• • SceneDelegate.scene(_ scene:, willConnectTo session:, options,connectionOptions:) 

               method:

BlueTriangle.configure { config in
    config.siteID = "<MY_SITE_ID>"
}

If you are using SwiftUI, add an init() constructor in your App struct and add configuration code there as shown below:

import BlueTriangle
import SwiftUI

@main
struct YourApp: App {
    init() {
          //Configure BlueTriagle with your siteID
          BlueTriangle.configure { config in
               config.siteID = "<MY_SITE_ID>"
           }
           //...
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Native View Automated Performance Tracking

All UIKit UIViewControllers view counts will be tracked automatically. You can see each view controller name with their count on our dashboard.

SwiftUI views are not captured automatically. You need to call bttTrackScreen() modifier on each view that you want to track. The below example shows the usage of "bttTrackScreen(_ screenName: String)" to track the "About Us" screen.

struct ContentView: View {
    var body: some View {
        VStack{
            Text("Hello, world!")
        }
        .bttTrackScreen("Demo_Screen")
    }
}

Disabling native view tracking

To disable mobile view tracking, you need to set the enableScreenTracking configuration to false during configuration like below, This will ignore UIViewControllers activities and bttTrackScreen() modifier calls.

 BlueTriangle.configure { config in
         ...
         config.enableScreenTracking = false
 }

To disable a named view

BlueTriangle.configure { config in
        ...
        config.ignoreViewControllers = ["UIViewController"]
}

Native View/WebView Tracking/Session Stitching

Websites shown in webview that are tracked by BlueTriangle can be tracked in the same session as the native app. To achieve this, follow the steps below to configure the WebView:

Implement WKNavigationDelegate protocol and call BTTWebViewTracker.webView(webView, didCommit: navigation) in 'webView(_:didCommit:)' delegate method as follows.

  import BlueTriangle

  //....

 extension YourWebViewController: WKNavigationDelegate{

  //....

  func webView(_ webView: WKWebView, didCommit navigation: WKNavigation!) {

      //....

      //Call BlueTringles 'webView(_:didCommit:)' method
      BTTWebViewTracker.webView(webView, didCommit: navigation)
    }

 }

For more clarity, here is a Webview with UIViewController full example:

import UIKit
import WebKit
//Need to import BlueTriangle
import BlueTriangle

class YourWebViewController: UIViewController {
  @IBOutlet weak var webView: WKWebView!

  override func viewDidLoad() {
      super.viewDidLoad()

      //Set navigationDelegate
      webView.navigationDelegate = self

      //Load Url
      if let htmlURL = URL(string: "https://example.com"){
          webView.load(URLRequest(url: htmlURL))
      }
  }
}

//Implement Navigation Delagate
extension YourWebViewController: WKNavigationDelegate {

  func webView(_ webView: WKWebView, didCommit navigation: WKNavigation!) {

      //...

      //Call BlueTringles 'webView(_:didCommit:)' method
      BTTWebViewTracker.webView(webView, didCommit: navigation)
  }
}

Webview with SwiftUI full example:

import SwiftUI
import WebKit
//Need to import BlueTriangle
import BlueTriangle

struct YourWebView: UIViewRepresentable {

  private let webView = WKWebView()

  func makeCoordinator() -> YourWebView.Coordinator {
      Coordinator()
  }

  func makeUIView(context: Context) -> some UIView {

      //Set navigationDelegate
      webView.navigationDelegate = context.coordinator

      //Load Url
      if let htmlURL = URL(string: "https://example.com"){
          webView.load(URLRequest(url: htmlURL))
      }
      return webView
  }
}

extension YourWebView {

  //Implement Navigation Delagate  Coordinator

  class Coordinator: NSObject, WKNavigationDelegate {

      func webView(_ webView: WKWebView, didCommit navigation: WKNavigation!) {

          //...

          //Call BlueTringles 'webView(_:didCommit:)' method
          BTTWebViewTracker.webView(webView, didCommit: navigation)
      }
  }
} 

Network Capture

The Blue Triangle SDK supports capturing network requests using either the bt-prefixed URLSession methods or the NetworkCaptureSessionDelegate.

Network requests using a URLSession with a NetworkCaptureSessionDelegate or made with one of the bt-prefixed URLSession methods will be associated with the last main timer to have been started at the time a request completes. Note that requests are only captured after at least one main timer has been started and they are not associated with a timer until the request ends.

NetworkCaptureSessionDelegate

You can use NetworkCaptureSessionDelegate or a subclass as your URLSession delegate to gather information about network requests when network capture is enabled:

let session = URLSession(
    configuration: .default,
    delegate: NetworkCaptureSessionDelegate(),
    delegateQueue: nil)

let timer = BlueTriangle.startTimer(page: Page(pageName: "MY_PAGE"))
...
let (data, response) = try await session.data(from: URL(string: "https://example.com")!)

If you have already implemented and set URLSessionDelegate to URLSession, you can call NetworkCaptureSessionDelegate objects urlSession(session: task: didFinishCollecting:) method:

func urlSession(_ session: URLSession, task: URLSessionTask, didFinishCollecting metrics: URLSessionTaskMetrics) {

     //Your code ...

    let sessionDelegate = NetworkCaptureSessionDelegate()
    sessionDelegate.urlSession(session, task: task, didFinishCollecting: metrics)
}

URLSession Methods

Alternatively, use bt-prefixed URLSession methods to capture network requests:

Use these methods just as you would their standard counterparts:

let timer = BlueTriangle.startTimer(page: Page(pageName: "MY_PAGE"))
...
URLSession.shared.btDataTask(with: URL(string: "https://example.com")!) { data, response, error in
    // ...
}.resume()

Manual Network Capture

For other network capture requirements, captured requests can be manually created and submitted to the tracker.

If you have the URL, method, and requestBodyLength in the request, and httpStatusCode, responseBodyLength, and contentType in the response

let tracker = NetworkCaptureTracker.init(url: "https://example.com", method: "post", requestBodylength: 9130)
tracker.submit(200, responseBodyLength: 11120, contentType: "json")

If you have urlRequest in request and urlResponse in response

let tracker = NetworkCaptureTracker.init(request: urlRequest)
tracker.submit(urlResponse)

where urlRequest and urlResponse are of URLRequest and URLResponse types, respectively.

If you encounter an error during a network call

let tracker = NetworkCaptureTracker.init(url: "https://example.com", method: "post", requestBodylength: 9130)
tracker.failed(error)

        OR

let tracker = NetworkCaptureTracker.init(request: urlRequest)
tracker.failed(error)

Checkout Event Data

Upon a customer checkout, it is possible to configure the following data parameters for the event:

Brand Value

let timer = BlueTriangle.startTimer( page: Page( pageName: "SignUp", brandValue: 100.0)) 
BlueTriangle.endTimer(timer)

Cart Value, Order Number, Order Time, Cart Count, Cart Checkout Count

let timer = BlueTriangle.startTimer( 
        page: Page( 
                pageName: "Confirmation")) 
BlueTriangle.endTimer( 
        timer, 
        purchaseConfirmation: PurchaseConfirmation( 
                cartValue:99.0, 
                cartCount: 2,
                cartCountCheckout: 5, 
                orderNumber: "ORD-123345")) 

Recommended (Optional) Configurations

Network Capture Sample Rate

Network sample rate indicates the percentage of session network requests that are captured. For example a value of 0.05 means that network capture will be randomly enabled for 5% of user sessions. Network sample rate value should be between 0.0 to 1.0 representing fraction value of percent 0 to 100. The default networkSampleRate value is 0.05, i.e only 5% of sessions network request are captured.

To change network capture sample rate set value of the 'config.networkSampleRate' to 0.5 to set is to 50%.

BlueTriangle.configure { config in
    config.siteID = "<MY_SITE_ID>"
    config.networkSampleRate = 0.5
    ...
}

To disable network capture set 0.0 to 'config.networkSampleRate' during configuration.

It is recommended to have 100% sample rate while developing/debugging. By setting 'config.networkSampleRate' to 1.0 during configuration.

Blue Triangle Campaign Configuration Fields

The following fields can be used to identify and segment users for optimized analytics contextualization. They can be configured in the SDK and modified in the app in real time, and they show in the Blue Triangle portal as parameters for reporting.

BlueTriangle.configure { config in
    config.abTestID = "MY_AB_TEST_ID"
    config.campaignMedium = "MY_CAMPAIGN_MEDIUM"
    config.campaignName = "MY_CAMPAIGN_NAME"
    config.campaignSource = "MY_CAMPAIGN_SOURCE"
    config.dataCenter = "MY_DATA_CANTER "
    config.trafficSegmentName = "MY_TRAFFIC_SEGEMENT_NAME"
} 

Custom Timers

While mobile Views are automatically tracked upon installation, Custom Timers can also be configured if needed.

NOTE: To enable application performance-oriented reporting, the timer duration is limited to 120 seconds.

To measure the duration of a user interaction, initialize a Page object describing that interaction and pass it to BlueTriangle.startTimer(page:timerType) to receive a running timer instance.

let page = Page(pageName: "MY_PAGE")
let timer = BlueTriangle.startTimer(page: page)

If you need to defer the start of the timer, pass your Page instance to BlueTriangle.makeTimer(page:timerType) and call the timer's start() method when you are ready to start timing:

let page = Page(pageName: "MY_PAGE")
let timer = BlueTriangle.makeTimer(page: page)
...
timer.start()

In both cases, pass your timer to BlueTriangle.endTimer(_:purchaseConfirmation:) to send it to the Blue Triangle server.

BlueTriangle.endTimer(timer)

Running timers are automatically stopped when passed to BlueTriangle.endTimer(_:purchaseConfirmation:), though you can end timing earlier by calling the timer's end() method.

timer.end()
...
// You must still pass the timer to `BlueTriangle.endTimer(_:)` to send it to the Blue Triangle server
BlueTriangle.endTimer(timer)

For timers that are associated with checkout, create a PurchaseConfirmation object to pass along with the timer to BlueTriangle.endTimer(_:purchaseConfirmation:):

timer.end()
let purchaseConfirmation = PurchaseConfirmation(cartValue: 99.00)
BlueTriangle.endTimer(timer, purchaseConfirmation: purchaseConfirmation)

Custom Variables 

In certain scenarios, a developer may need to include additional application-specific information with Timers. This can be achieved by setting custom variables within the BlueTriangle class on iOS (andTracker class on Android). These custom variables are global, meaning that once defined, they will automatically be included with every subsequent Timer payload.

To introduce a custom variable, the developer first needs to create it on the BlueTriangle portal. Follow the instructions provided here. Variables created in the portal have a unique variable name associated with them, e.g. CV1, CV2, etc. which are used while setting the custom variable values.

The custom variable values are sent in String format. The following overload functions are just for the convenience of the app developer. In case of boolean value, the custom variable on the portal should be of type “Text”. 

Setting a Single Custom Variable

Swift 

BlueTriangle.setCustomVariable(<VARIABLE NAME>, "Some Textual Information"") // String Overload
BlueTriangle.setCustomVariable(<VARIABLE NAME>, true) // Boolean Overload
BlueTriangle.setCustomVariable(<VARIABLE NAME>, 1.2349) // Numeric Overload

Objective-C 

[BlueTriangle setCustomVariable:<VARIABLE NAME> strValue:@"Some Textual Information")]; // String Overload
[BlueTriangle setCustomVariable:<VARIABLE NAME> numValue:true)]; // Boolean Overload
[BlueTriangle setCustomVariable:<VARIABLE NAME> boolValue:1.2349)]; // Numeric Overload

Setting Multiple Custom Variables

These methods take a map/dictionary as input, where all the key and values are of String type. The keys correspond to the custom variable names and the values are their respective custom variable values.

Swift

BlueTriangle.setCustomVariables(values)

Objective-C

[BlueTriangle setCustomVariables:values];

Getting a Single Custom Variable

There are no method overloads for different data types, as those values are converted to String when they are set. The app developer needs to use the correct data types are parsed after getting the value from getCustomVariable.

If there is no value stored against the provided variable name, this method will return null/nil.

Swift

var value = BlueTriangle.getCustomVariable(<VARIABLE NAME>)

Objective-C

NSString *value = [BlueTriangle getCustomVariable:<VARIABLE NAME>];

Getting All Custom Variables

These methods take a map/dictionary as input, where all the key and values are of String type. The keys correspond to the custom variable names and the values are their respective custom variable values.

Swift

var variables = BlueTriangle.getCustomVariables()

Objective-C

NSDictionary *values = [BlueTriangle getCustomVariables];

Clearing a Single Custom Variable

Swift 

BlueTriangle.clearCustomVariable(<VARIABLE NAME>)

Objective-C

[BlueTriangle clearCustomVariable:<VARIABLE NAME>];

Clearing All Custom Variables

Swift

BlueTriangle.clearAllCustomVariables()

Objective-C

[BlueTriangle clearAllCustomVariables] 

Optional Configuration Steps

ANR Detection

BlueTriangle tracks you app’s responsiveness by monitoring main THREAD USAGE. If any task blocking main thread for extended period of time causing app not responding, will be tracked as ANR Warning. By default, this time interval is 5 Sec I.e. if any task blocking main thread more then 5 sec will be triggered as ANRWarning. This timeinterval can be changed using "ANRWarningTimeInterval" Property below.

BlueTriangle.configure { config in
        ...
       config.ANRWarningTimeInterval = 3
}

You can disable it by setting "ANRMonitoring" configuration property to "false" during configuration.

BlueTriangle.configure { config in
        ...
        config.ANRMonitoring = false
}

Memory Warning

Blue Triangle tracks iOS reported low memory warnings by monitoring UIApplication.didReceiveMemoryWarningNotification notifications.

You can disable it by setting "enableMemoryWarning" configuration property to "false" during configuration.

BlueTriangle.configure { config in
        ...
        config.enableMemoryWarning = false
}

Memory Usage

Memory usage is the amount of memory used by the code during the Timer interval. This is measured in number of bytes.

Against each timer, 3 Memory measurements are being sent, minimum, maximum and average.

Memory usage refers to the amount memory (RAM) that is currently being used by application to store and manage data. In analytics.rcv payload data json, 'minMemory', 'maxMemory' and 'avgMemory' are being used to send the respective memory usage.

To set the interval (in s) at which the Memory usage is being captured, set the following field:

 BlueTriangle.configure { config in
         ...
         config.performanceMonitorSampleRate = 1
     }

To disable Memory usage set the following field:

BlueTriangle.configure { config in
       ...
       config.isPerformanceMonitorEnabled = false
   } 

CPU Usage

CPU Usage is the amount of CPU being used by the code during the Timer interval. This is measured in the form of 0-100%.

Against each timer, 3 CPU measurements are being sent, minimum, maximum and average.

CPU usage is being reported by xcode as X.100% format [where X is number of cores], it typically means that the system is utilizing the CPU resources heavily. To express this in a 0% to 100% format, Blue Triangle calculates the CPU usage by dividing number of CPU cores. This will give you a percentage value between 0% and 100%.

0% to 100% format = Total current CPU usage on Instruments / Number of CPU cores.

For example:, if you have 4 CPU cores and your current usage is 300%. then actual BTT CPU usage 300% / 4 = 75%. This indicates that CPU is being utilized at 75% of its total capacity.

To set the interval (in s) at which the CPU usage is being captured, set the following field in BlueTriangleConfiguration:

BlueTriangle.configure { config in
         ...
         config.performanceMonitorSampleRate = 1
     }

To disable CPU usage set the following field in BlueTriangleConfiguration:

BlueTriangle.configure { config in
       ...
       config.isPerformanceMonitorEnabled = false
   }

Track Crashes

Blue Triangle tracks app crashes - by default crash tracking is enabled. 

Crash tracking tools can interfere with each other, and not configuring the Blue Triangle SDK properly may result in conflicts that will not allow the Blue Triangle SDK to capture crashes. 

It is recommended to configure the Blue Triangle SDK before any other crash tracking tool to prevent conflicts with those tools. Additionally, testing the crash reporting before moving to production is advised in order to ensure crashes are reported to both Blue Triangle and your other crash tracking tool.

If it is not possible to configure the Blue Triangle SDK before your other crash tracking tool, please use  BlueTriangle.startCrashTracking(). This function allows Blue Triangle to start crash tracking earlier, which will help in scenarios where you wish to configure the Blue Triangle SDK after a different crash tracking tool is configured.

To disable blue triangle crash tracking use following configuration:

BlueTriangle.configure { config in
config.siteID = "<MY_SITE_ID>"
//Disable crash tracking
config.crashTracking = .none
} 

Offline Caching

Offline caching is a feature that allows the BTT SDK to keep track of timers and other analytics data while the app is in offline mode. i.e, the BTT SDK cannot send data back to Blue Triangle.

There is a memory limit as well as an expiration duration put on the cached data. If the cache exceeds the memory limit then additional tracker data will be added only after removing some older, cached data (first in, first out). Similarly, cache data that has been stored for longer than the expiration duration would be discarded and won't be sent to the tracker server.

Memory limit and Expiry Duration can be set by using configuration property cacheMemoryLimit and cacheExpiryDuration as shown below:

 BlueTriangle.configure { config in
         ...
            config.cacheMemoryLimit = 50 * 1024 (Bytes)
            config.cacheExpiryDuration = 50 * 60 * 1000 (Millisecond)
 }

By default, the cacheMemoryLimit is set to 48 hours and cacheExpiryDuration is set to 30 MB.

Network State Capture

BlueTriangle SDK allows capturing of network state data. Network state refers to the availability of any network interfaces on the device. Network interfaces include wifi, ethernet, cellular, etc. Once Network state capturing is enabled, the Network state is associated with all Timers, Errors and Network Requests captured by the SDK. This feature is enabled by default.

You can disable it by setting enableTrackingNetworkState property to "false" during configuration.

 BlueTriangle.configure { config in
         ...
         config.enableTrackingNetworkState = false
  }

Launch Time

Blue Triangle tracks app launch performance. Launch time refers to the duration it takes for an app to become ready for user interaction after it has been started. Blue Triangle automatically tracks both hot launch and cold launch.

Cold Launch

A cold launch occurs when the app process is not already stored in the main memory. This can happen because iOS or the user terminated your app's process or its first time launch after install/update/reboot.

The Blue Triangle SDK measures the cold launch latency, which is the time between the process start time and the end of 'applicationDidBecomeActive(:)'. The cold launch time is the cumulative time taken to load the process plus the time taken by 'application(:didFinishLaunchingWithOptions:)', 'applicationWillEnterForeground(:)' and 'applicationDidBecomeActive(:)'.

Hot Launch

A Hot Launch occurs when the app is already running in the background and is brought to the foreground. This type of launch is typically faster since the app's state is preserved in memory.

The Blue Triangle SDK measures the hot launch latency, which is the time between the end of 'applicationWillEnterForeground(:)' and end of 'applicationDidBecomeActive(:)'. The hot launch time is taken from 'applicationDidBecomeActive(:)'.

When the user locks the device while the app was on the screen and then unlocks it,  iOS gives a background and a foreground notification. Therefore, unlocking followed by locking while the app was active is tracked as a Hot Launch.

You can disable it by setting "enableLaunchTime" configuration property to "false" during configuration:

BlueTriangle.configure { config in
...
config.enableLaunchTime = false

}

How to Test your iOS SDK

Memory Warning

To test Memory Warning, In the iOS Simulator, you can generate a memory warning using the following steps:

        1. Launch Simulator

        2. Go to XCode 'Debug' menu

        3. Select 'Simulate Memory Warning' to generate memory warning

ANR Tracking

To test ANR Tracking, You can declare and call the following function on the main thread:

func testANRTracking(){ let startTime = Date() while true { 
  if (Date().timeIntervalSince1970 - startTime.timeIntervalSince1970) > 30 { 
      break } 
    } 
  }

Crash Tracking

To test Crash Tracking, you can declare and call the following function:

func testCrashTracking() {  let array = NSArray()  array.object(at: 99)  } 

Limitations/Known Issues

Crashes

The expiration timestamp is only updated when the app offscreen event is received and therefore the app offscreen events cannot be handled when a crash happens. Because of this, BTT is unable to renew the session expiration timestamp in crash scenarios. The potential impact of this scenario is that the session could expire in less than 30 minutes instead of 30 minutes. The exact duration of expiration would depend on the last time the user went offscreen since that was when the expiration timestamp was set. 

WebView Stitching

If a WebView was displaying in the app when the user went offscreen, when the user returns the session is updated. The Blue Triangle btt.js tag receives the new session id, however the btt.js tag manages its own session. Because of this, after the session is injected into the WebView, the btt.js tag itself renews its internal session, possibly resulting in the tag using a different session than the Native SDK.

General Information

Supported SDK Metrics

• Performance & Network Timings

  • Main Timers

  • Network Timers

  • Custom Timers

• Errors & Crashes

• Application Not Responding (ANR)

• HTTP Response Codes

• App Crashes

• Device Stats & Session Attributes

  • OS/OS Version

  • App Version

  • Device Type

  • Geographical/Country

  • CPU Usage

  • Memory Warnings

  • Memory/Out of Memory

  • Hot/Cold Launch

  • Network Type

  • Device Model

  • Custom variables

Release Notes