By default, the Connect iOS library automatically instruments your application by using a template of selected items that are based on the configured logging level. As needed, you can configure the library for custom instrumentation. A predefined set of events and objects are instrumented in the application, and the rest can be instrumented through custom methods.

📘

Note:

Before you begin, complete the initial configuration tasks that are associated with instrumentation.

You can use any of the available custom instrumentation APIs to meet your application requirements.

Manual instrumentation

When you disable the auto-instrumentation feature, no method swizzling occurs, the application state is not monitored, and screen changes or any other events are not automatically tracked.

To disable auto-instrumentation, open the ConnectBasicConfig.plist file in ConnectResources.bundle and set DisableAutoInstrumentation key to true.

📘

Note:

Disabling auto-instrumentation is not recommended because of the large configuration effort, high chance of errors, and possibility of incomplete coverage. If you choose to disable auto-instrumentation, you are responsible for implementing theses changes.

Required actions

When you use the Connect library with auto-instrumentation turned off, you must configure a set of actions to occur that auto-instrumentation would otherwise do. The list of required actions follows.

• View Controller changes must be logged by using the API logAppContext from the ConnectCustomEvent class.
• HTTP Connection updates must be logged by using the API logConnection from the ConnectCustomEvent class. There are three logConnection APIs: one each for initialization, successful response, and failure.
• Button click events must be logged by using API logClickEvent from the ConnectCustomEvent.
• UITableViewCell tap events must be logged by using the API logValueChangeEvent from the ConnectCustomEvent class.
• Text change events for UITextField, UITextView, and UILabel must be logged by using the API logTextChangeEvent from the ConnectCustomEvent class.
• To sessionize all NSURLMutableRequest objects, you use the API sessionizeRequest from the ConnectApplicationHelper class.
• To track all requests that are made by UIWebView from the UIWebViewDelegate shouldStartLoadWithRequest, you use the API isTealeafHybridBridgeRequest from the ConnectApplicationHelper class.
• To inject the Acoustic Connect hybrid bridge into the JavaScript for all web page loads from UIWebViewDelegate webViewDidFinishLoad, you use the API InjectTealeafHybridBridgeOnWebViewDidFinishLoadfrom the ConnectApplicationHelper class.

How to use the ConnectCustomEvent class

Use the following information to manually track various events with the ConnectCustomEvent class.

- (BOOL)logAppContext:(NSString_)logicalPageName
    applicationContext:(NSString_)applicationContext
              referrer:(NSString\*)referrer

A custom event which in conjunction can have a dictionary of keys and values.

- (BOOL)logEvent:(NSString_)eventName values:(NSDictionary_)values;

Use this API to log failures that occur when a connection is attempted; typically from NSURLConnectionDelegate didFailWithError or when sendSynchronousRequest returns an error. The first parameter is the connection object, and the second parameter is the error that you received.

- (BOOL)logConnection:(NSURLConnection_)connection error:(NSError_)error

Use this API to log successful connections; typically from NSURLConnectionDelegate didReceiveResponse or when sendSynchronousRequest returns success. The first parameter is the connection object. The second parameter is the response that you received, and the third is the connection's response type in milliseconds.

- (BOOL)logConnection:(NSURLConnection_)connection
                      response:(NSURLResponse_)response
    responseTimeInMilliseconds:(long long)responseTime;

Use this API to log connection initialization; typically before or after a NSURLConnection initWithRequest call. The first parameter is the connection object, and the second parameter is the request object.

- (BOOL)logConnection:(NSURLConnection_)connection
              request:(NSURLRequest_)request;

Use this API to log failures that occur when a connection is attempted; typically from NSURLConnectionDelegate didFailWithError or when sendSynchronousRequest returns an error. The first parameter is the connection object, and the second parameter is the error that you received.

- (BOOL)logNSURLSession:(NSObject_)urlSession error:(NSError_)error;

Use this API to log successful connections; typically from NSURLConnectionDelegate didReceiveResponse or when sendSynchronousRequest returns success. The first parameter is the connection object. The second parameter is the response that you received, and the third is the connection's response type in milliseconds.

- (BOOL)logNSURLSession:(NSObject_)urlSession
                      response:(NSURLResponse_)response
    responseTimeInMilliseconds:(long long)responseTime;

Use this API to log connection initialization; typically before or after a call NSURLConnection initWithRequest. The first parameter is the connection object, and the second parameter is the request object.

- (BOOL)logNSURLSession:(NSObject_)urlSession request:(NSURLRequest_)request;

Use this API to log button click events. Call this from your button click event handlers. The first parameter view is the UIButton object on which the click event happened. The second parameter is optional, and is for future use. You can pass Nil for now.

- (BOOL)logClickEvent:(UIView_)view data:(NSDictionary_)data;

Use this API to log UITableViewCell tap events. Call this from your UITableViewDelegate didSelectRowAtIndexPath. The first parameter view is the UITableViewCell object on which the tap event happened The second parameter is optional, and is for future use. You can pass Nil for now.

- (BOOL)logValueChangeEvent:(UIView_)view data:(NSDictionary_)data;

Use this API to log text change events for UITextField, UITextView, and UILabel. Call this from your application wherever contents of these three controls changed. If you add the UITextViewTextDidEndEditingNotification observer, you can call it from there. The first parameter view is the object of any of UITextField, UITextView, and UILabel whose text was edited. The second parameter is optional, and is for future use. You can passNil for now.

- (BOOL)logTextChangeEvent:(UIView_)view data:(NSDictionary_)data;

Use this API to indicate form completion on view.

- (BOOL)logFormCompletion:(BOOL)submitted;

Use this API to log the image as passed in, inside a new type 10 layout message. During replay, the image is displayed under Dynamic Update or as a screenview when the API is called. If the API is called when the screen has already transitioned, the image is shown as Dynamic Update in the replay navlist.

The API returns true if an image is successfully logged; else returns false. If image is nil, the API returns false.

• All APIs are blocking calls. They are all optional and can be called based on your application design and state machine.
• All the APIs return YES if data is logged, and NO in case of failure. The console debug log shows the reason for failure.

- (BOOL)logScreenLayoutWithImage:(UIImage \*)image;

ConnectApplicationHelper class

- (BOOL)sessionizeRequest:(NSMutableURLRequest*)request;

Use this API so that the Connect iOS library can add various Headers and Cookies that can be used to tie all the application session hits together on the server. Call this API as soon as you create the NSMutableURLRequest object, and before you start the HTTP connection. The first parameter is the object of NSMutableURLRequest that the Connect iOS library updates.

- (BOOL)isTealeafHybridBridgeRequest:(NSURLRequest_)request
                             webView:(UIWebView_)webView;

Start this API from UIWebViewDelegate shouldStartLoadWithRequest. The first parameter is object of NSURLRequest, and the second is object of the current UIWebView. The API determines whether the request is specific to and meant for the Acoustic Experience Analytics (Tealeaf) iOS SDK from the Acoustic Experience Analytics (Tealeaf) JavaScript SDK. If it is, the API consumes the data that is sent by the Acoustic Experience Analytics (Tealeaf) JavaScript SDK. If not, handle the request inside your shouldStartLoadWithRequest. For example, if this API returns YES, ignore the request and return NO from shouldStartLoadWithRequest. It was not an actual page navigation request from your HTML or JavaScript. If this API returns NO, handle the request as it came from your own HTML page or JavaScript.

- (BOOL)InjectTealeafHybridBridgeOnWebViewDidFinishLoad:(UIWebView *)webView;

Use this API to inject Acoustic Experience Analytics (Tealeaf) specific JavaScript into your web page. The JavaScript injection helps transfer data from the Acoustic Experience Analytics (Tealeaf) JavaScript UI Capture SDK to the Acoustic Experience Analytics (Tealeaf) Native iOS SDK. The first parameter is the object of UIWebView in which the current web page is loaded. Call it every time a new page is loaded into the UIWebView. Place it in UIWebViewDelegate webViewDidFinishLoad.

Base instrumentation

The objects and events to populate the following sections are automatically instrumented, even if you enable custom instrumentation.

Environmental data is automatically captured during initialization.

User actions and behaviors are not captured when auto-instrumentation is disabled. These events must be manually instrumented.

Custom instrumentation

APIs

The Connect iOS library logs many events automatically, but you can also use it to log errors, exceptions, and custom events. To log custom events, you can use the ConnectCustomEvent class. This singleton class offers different methods to log custom events.

For convenience, the Connect iOS library provides standard events for location tracking and wireless carrier recording.

Here is an example.

[[ConnectCustomEvent sharedInstance] logEvent:@"PurchaseConfirmed"];

API - log event

You use the logEvent API to log a simple custom event quickly.

[[ConnectCustomEvent sharedInstance] logEvent:@"EventName1"];

- (void)logEvent:(NSString*)eventName;

API - log event and dictionary of values

Use the logEvent API to log a custom event and a dictionary of values that are related to that event.

[[ConnectCustomEvent sharedInstance] logEvent:@"EventName3" values:dictionary];

- (void)logEvent:(NSString_)eventName values:(NSDictionary_)values;

API - log event, dictionary of values, and set monitoring level

Use the logEvent API to log a custom event, a dictionary of values, and set a specific ConnectMonitoringLevel.

[[ConnectCustomEvent sharedInstance] logEvent:@"EventName6" values:
dictionary level:2];

- (void)logEvent:(NSString_)eventName
          values:(NSDictionary_)values
           level:(kTLFMonitoringLevelType)level;