Enable User Interaction Capture Mode

To enable user interaction capture mode, you assign the capture mode to the property interactionCaptureMode of the ADEumAgentConfiguration object. The instrumentation code example below configures the iOS Agent to capture all the supported types of user interactions.

ADEumAgentConfiguration *config = [[ADEumAgentConfiguration alloc] initWithAppKey: <#EUM_APP_KEY#>];
config.interactionCaptureMode = ADEumInteractionCaptureModeAll;
[ADEumInstrumentation initWithConfiguration:config];

You can also configure the iOS Agent to only capture one type of user interaction:

ADEumAgentConfiguration *config = [[ADEumAgentConfiguration alloc] initWithAppKey: <#EUM_APP_KEY#>];
config.interactionCaptureMode = ADEumInteractionCaptureModeButtonPressed;
[ADEumInstrumentation initWithConfiguration:config];

Disable Screenshots

shutdownAgent

restartAgent

Enable ANR Detection

Report Stack Traces with ANRs

Runtime Configuration for Hybrid Application Support

The code example below disables the injection of the JavaScript Agent. By disabling the injection, the WKWebViews in your application will not be instrumented and Ajax calls will not be reported.

ADEumAgentConfiguration *adeumAgentConfig = [[ADEumAgentConfiguration alloc] initWithAppKey: <#EUM_APP_KEY#>];
// Disable the JavaScript Agent Injection
adeumAgentConfig.jsAgentEnabled = NO;
[ADEumInstrumentation initWithConfiguration:adeumAgentConfig];

The JavaScript Agent injection is enabled by default. To also enable the collection and reporting of Ajax calls:

ADEumAgentConfiguration *adeumAgentConfig = [[ADEumAgentConfiguration alloc] initWithAppKey: <#EUM_APP_KEY#>];
// Enable the collection and reporting of Ajax calls
adeumAgentConfig.jsAgentAjaxEnabled  = YES;
[ADEumInstrumentation initWithConfiguration:adeumAgentConfig];

Static Configuration for Hybrid Application Support

You should use static configuration for the following reasons:

• force the instrumentation of WKWebViews and/or Ajax calls (override the runtime configuration).
• disable hybrid support and override the runtime configuration.
• set the URL to your self-hosted JavaScript Extension file.

The table below describes the supported properties and provides the default value for the info.plist file.

Example Configuration

The example info.plist below forces the instrumentation of WKWebViews (overriding the runtime configuration), but does not force the collection and reporting of Ajax requests. The configuration also sets the URL where the JavaScript Extension file is obtained.

<plist>
  <dict>
    ...
    <key>ADEUM_Settings</key>
    <dict>
      <key>ForceWebviewInstrumentation</key>
      <true/>
      <key>ForceAjaxInstrumentation</key>
      <false/>
      <key>ADRUMExtUrlHttp</key>
      <string>http://<your-domain>/adrum.cdn</string>
      <key>ADRUMExtUrlHttps</key>
      <string>https://<your-domain>/adrum.cdn</string>
    </dict>
    ...
 </dict>
</plist>

Example of a Programmatically Controlled Session

Use Cases

The following are common use cases for the SessionFrame API.

• One ViewController performs multiple functions and you want more granular tracking of the individual functions.
• A user flow spans multiple ViewController or user interactions. For example, you could use the API to create the session frames "Login", "Product Selection", and "Purchase" to chronicle the user flow for purchases.
• You want to capture dynamic information based on user interactions to name session frames, such as an order ID.

SessionFrame API

Session Frame Example

Add Request Tracking

To add request tracking manually, you tell the agent when the request begins and when it ends. You also set properties to tell the agent the status of the response.

Start Tracking a Request

To begin tracking an HTTP request, call the following method immediately before sending the request.

@interface ADEumHTTPRequestTracker : NSObject
... 
+ (ADEumHTTPRequestTracker *)requestTrackerWithURL:(NSURL *)url;

Where url is the URL being requested. This parameter must not be nil.

To complete tracking an HTTP request, immediately after receiving a response or an error, set the appropriate properties on the tracker object and call the following method to report the outcome of the request back to the agent. You should not continue to use this object after calling this method. To track another request, call requestTrackerWithURL again.

- (void)reportDone;

Set Request Tracker Properties

The following properties should be set on the requestTrackerWithURL object to describe to the agent the results of the call:

@property (copy, nonatomic) NSError *error;

Indicates the failure to receive a response, if this occurred. If the request was successful, this should be nil.

@property (copy, nonatomic) NSNumber *statusCode;

Reports the HTTP status code of the response, if one was received.

• If a response was received, this should be an integer.

• If an error occurred and a response was not received, this should be nil.

  @property (copy, nonatomic) NSDictionary *allHeaderFields;

Provides a dictionary representing the keys and values from the server's response header. The format of this dictionary should be identical to the allHTTPHeadersFields property of NSURLRequest. The dictionary elements consist of key/value pairs, where the key is the header key name and the value is the header value.

If an error occurred and a response was not received, this should be nil.

Example

Given a request snippet like this:

- (NSData *)sendRequest:(NSURL *) url error:(NSError **)error { 
      // implementation omitted 
      NSData *result = nil; 
      if (errorOccurred) { 
          *error = theError; 
      } else { 
          result = responseBody; 
      } 
      return result; 
  }

Adding the tracker could look something like this:

- (NSData *)sendRequest:(NSURL *)url error:(NSError **)error { 
      ADEumHTTPRequestTracker *tracker = [ADEumHTTPRequestTracker requestTrackerWithURL:url]; 
      // implementation omitted 
      NSData *result = nil; 
      if (errorOccurred) { 
          *error = theError; 
          tracker.error = theError; 
      } else { 
          tracker.statusCode = theStatusCode; 
          tracker.allHeaderFields = theResponseHeaders; 
          result = responseBody; 
      } 
      [tracker reportDone]; 
      return result; 
  }

Enable Server-Side Correlation

To enable correlation between your request and server-side processing, add specific headers to outgoing requests that the server-side agent can detect and return the headers obtained from the server-side agent in the response to make them available to the iOS Agent.

This is done automatically for standard HTTP libraries.

@interface ADEumServerCorrelationHeaders : NSObject 
+ (NSDictionary *)generate; 
@end

You must:

1. Call the generate method and set the generated headers before sending a request to the backend.

2. Report back the response headers, using the allHeaderFields property shown above.

Attach Custom Data to a Network Request

You can attach custom data to a network request by calling one (or multiple) of the following methods to add attributes to ADEumHTTPRequestTracker:

• setUserDataLong:value:

• setUserDataBoolean:value:

• setUserDataDouble:value:

• setUserDataDate:value:

- (NSData *)sendRequest:(NSURL *)url error:(NSError **)error { 
      ADEumHTTPRequestTracker *tracker = [ADEumHTTPRequestTracker requestTrackerWithURL:url]; 
      // implementation omitted 
      NSData *result = nil; 
      if (errorOccurred) { 
          *error = theError; 
          tracker.error = theError; 
      } else { 
          tracker.statusCode = theStatusCode; 
          tracker.allHeaderFields = theResponseHeaders; 
          result = responseBody; 
      } 

      // Custom data can be added to this one request.
      // Different types can be used.
      // The data added will only appear for this network request and will not persist.
      [tracker setUserData:@"trackerStringKey" value:@"Test String Value"];
      [tracker setUserDataLong:@"trackerLongKey" value:66004024];
      [tracker setUserDataBoolean:@"trackerBooleanKey" value:1];
      [tracker setUserDataDouble:@"trackerDoubleKey" value:5905400.6];
      [tracker setUserDataDate:@"trackerDateKey" value:[NSDate date]];

      [tracker reportDone]; 
      return result; 
  }

Configure Beacon Channel to Use Custom HTTP Library

The iOS Agent uses HTTP to deliver its beacons. To have the agent use your custom HTTP library for this purpose, do the following.

1. Implement a class that conforms to this protocol:

   /** 
   * Protocol for customizing the connection between the agent SDK and the collector. 
   */ 
   @protocol ADEumCollectorChannel <NSObject> 
    
   /** 
   * Sends a request synchronously and returns the response received, or an error. 
   * 
   * The semantics of this method are exactly equivalent to NSURLConnection's 
   * sendSynchronousRequest:returningResponse:error: method. 
   * 
   * @param request The URL request to load. 
   * @param response Out parameter for the URL response returned by the server. 
   * @param error Out parameter used if an error occurs while processing the request. May be NULL. 
   */ 
   - (NSData *)sendSynchronousRequest:(NSURLRequest *)request returningResponse:(NSURLResponse **)response error:(NSError **)error; 
   @end

2. Set the collectorChannel property in ADEumAgentConfiguration before initializing ADEumInstrumentation, passing in an instance of your class that implements ADEumCollectorChannel. See the latest iOS SDK documentation.

   @property (nonatomic, strong) id<ADEumCollectorChannel> collectorChannel;