Table of Contents
Overview
Use Blue Triangle's Native App Real User Monitoring Module to collect end user experience data for measuring application speed, responsiveness, errors conditions, and network calls.
The iOS SDK is available on the Public GitHub repository page available here.
Detailed documentation is also available on GitHub here.
Installation
Xcode 13: go to File > Add Packages…, enter the package repository URLhttps://github.com/blue-triangle-tech/btt-swift-sdk.git
, and click Add Package.
Xcode 11 - 12: go to File > Swift Packages > Add Package Dependency…and enter the package repository URLhttps://github.com/blue-triangle-tech/btt-swift-sdk.git
, then follow the instructions.
Configuration
Before sending timers you must first configureBlueTriangle
. It is recommended to do this in yourAppDelegate.application(_:didFinishLaunchingWithOptions:)
method:
BlueTriangle.configure { config in config.siteID="MY_SITE_ID" config.isReturningVisitor=true 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_CENTER" config.trafficSegmentName="MY_SEGMENT_NAME" config.crashTracking= .nsException config.performanceMonitorSampleRate=1.0 }
Manual Timers
Overview
Create timers to measure responses to user interactions.
To measure the duration of a user interaction, initialize a Page object describing that interaction and pass it to 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, use makeTimer(page:timerType:) and call the returned 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 endTimer(_:purchaseConfirmation:)to send it to the Blue Triangle server.
BlueTriangle.endTimer(timer)
Running timers are automatically stopped when passed to 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 serverBlueTriangle.endTimer(timer)
For timers that are associated with checkout, create aPurchase
object to pass along with the timer toend
:
timer.end()
let purchaseConfirmation =PurchaseConfirmation(cartValue: 99.00)
BlueTriangle.endTimer(timer, purchaseConfirmation: purchaseConfirmation)
Timer Types
makeTimer(page:timerType:) and startTimer(page:timerType:) have a timer
parameter to specify the type of the timer they return. By default, both methods return main timers with the type BTTimer.TimerType.main. When Network Capture is enabled, requests made with one of the bt-prefixed URLSession methods will be associated with the last main timer to have been started at the time the request completes. It is recommended to only have a single main timer running at any given time. If you need overlapping timers, create additional custom timers by specifying a BTTimer.TimerType.custom timer type:
let mainTimer =BlueTriangle.startTimer(page: Page(pageName: "MY_PAGE"))
let customTimer =BlueTriangle.startTimer(page: Page(pageName: "MY_OTHER_TIMER"), timerType: .custom)
// ...BlueTriangle.endTimer(mainTimer)
// ...BlueTriangle.endTimer(customTimer)
Instance Properties
var endTime: Time
The epoch time interval at which the timer was ended.
var hasEnded:Bool
var interactiveTime: Time
The epoch time interval at which the timer was marked interactive.
var page: Page
An object describing the user interaction measured by the timer.
var startTime:Time
The epoch time interval at which the timer was started.
var state:State
The state of the timer.
let type: Timer
The type of the timer.
Instance Methods
func end() End the timer.
func markInteractive(): Mark the timer interactive at current time if the timer has been started and not already marked interactive.
func start(): Start the timer if not already started.
Enumerations
enum State: Describes the state of a timer.
enum TimerType: Describes the timer type.
Network Capture
The Blue Triangle SDK offersbt
-prefixed versions of commonURLSession
methods that can be used to gather information about network requests when network capture is enabled:
Standard | Network Capture |
---|---|
URLSession.dataTask(with:completionHandler:) |
URLSession.btDataTask(with:completionHandler:) |
URLSession.data(for:delegate:) |
URLSession.btData(for:delegate:) |
URLSession.dataTaskPublisher(for:) |
URLSession.btDataTaskPublisher(for:) |
To enable network capture, configure the SDK with a non-zero network sample rate:
BlueTriangle.configure { config in... config.networkSampleRate=0.05 }
A value of0.05
, for example, means that network capture will be randomly enabled for 5% of user sessions. Network requests made using one of thebt
-prefixedURLSession
methods will be associated with the last main timer to have been started.
let timer = BlueTriangle.startTimer(page: Page(pageName: "MY_PAGE")) URLSession.shared.btDataTask(with: URL(string: "https://example.com")!) { data, response, error in
// ...}.resume()
Requests are not associated with a timer until the request ends.
Classes
class BlueTriangle: The entry point for interacting with the Blue Triangle SDK.
class BlueTriangleConfiguration: Configuration object for the Blue Triangle SDK.
class CustomCategories: Custom textual data that is collected from the page, aggregated, and ultimately appears in the list of filter options in the Blue Triangle portal.
class CustomNumbers: Custom numeric data that is collected from the page, aggregated, and ultimately appears on your trend graphs in the Blue Triangle portal.
class CustomVariables: Custom textual data that is related to individual views but does not need to be seen at a larger, aggregate scale.
class Page: An object describing a user interaction.
class PurchaseConfirmation: An object describing a purchase confirmation interaction.
Automated Timers with Screen View Tracking
Screen view tracking is a method of automatically capturing the performance timings of screen load times. Depending on the framework your application is built on, the installation process will be different for either SwiftUI or UIKit. This documentation aims to guide you through the process of setting up screen view tracking for your application using the Blue Triangle SDK.
To enable screen tracking you have to set the "enableScreenTracking" configuration option to true when setting up the Blue Triangle SDK, see the below code snippet.
BlueTriangle.configure { config in
//Other configurations ..
config.enableScreenTracking = true
}
Tracking UIViewController Subclasses
For the UIKit framework, UIViewControllers are tracked automatically. By configuring the "enableScreenTracking" setting to true, the load time for each View Controller will be captured and the associated pagename will be dependant upon the name of the View Controller.
The performance of each view controller is the execution time of viewDidLoad() and viewWillAppear() for each view controller. The automatic screen tracking for the UIKit framework is based on the UIViewController lifecycle methods viewDidLoad(), viewWillAppear() and viewDidAppear().
Make sure every lifecycle method of UIViewController you are overriding in your UIViewController subclass is calling super, which is a recommended practice as missing the super call can result in undefined behavior. For any screen design where these lifecycle methods of UIViewController are not getting called, then that specific view controller might not be tracked by the automatic screen tracking.
Tracking SwiftUI Views
For the SwiftUI framework, use the bttTrackScreen() modifier provided by the Blue Triangle SDK.
The example code snippet below will track the HomeView by the name "Home View".
struct HomeView: View {
var body: some View {
VStack{
Text("Hello, world!")
}
.bttTrackScreen("Home View")
}
}
Apply the bttTrackScreen() view modifier to the SwiftUIView you want to track. Providing the name of the screen to the bttTrackScreen() in order to set the Pagename of that screen which will be visible from the Blue Triangle Portal. Make sure each view name is unique and does not conflict with other views, otherwise the performance timings can become conflated.
For SwiftUI, only the Views which have the bttTrackScreen() modifier added will have their performance timing tracked, otherwise the load time for views without this modifier will be ignored and not reported to the Blue Triangle portal.
The performance time for SwiftUI Views is the time needed to execute code in the onAppear() of the view which is being tracked. The placement of bttTrackScreen() is important to correctly calculate performance time of a view. Call bttTrackScreen() before .onAppear() on the view which you want to track.
Below are a few examples of implementing the bttTrackScreen(). Note the specific placement of the bttTrackScreen() modifier on the view.
struct ContentView: View {
var body: some View {
VStack{
Text("Hello, world!")
}
.task{
//Task code gos here
}
.bttTrackScreen("Demo_Screen")
.onAppear{
//OnAppear preparation code gos here..
}
}
}
struct ContentView: View {
var body: some View {
VStack{
Text("Hello, world!")
}
.task{
//Task code gos here
}
.bttTrackScreen("Demo_Screen")
}
}
struct ContentView: View {
var body: some View {
VStack{
Text("Hello, world!")
}
.bttTrackScreen("Demo_Screen")
.onAppear{
//OnAppear preparation code gos here..
}
}
}
Comments
0 comments
Please sign in to leave a comment.