Use the Agent with a Custom HTTP Library

The iOS Agent automatically detects network requests when the underlying implementation is handled by either by the NSURLConnection or the NSURLSession classes. This covers the great majority of iOS network requests. In some cases, however, mobile applications use custom HTTP libraries.

  • To have the iOS Agent detect requests from a custom library, add request tracking code to your application manually, using the ADEumHTTPRequestTracker class.
  • To set headers to allow correlation with server-side processing, use the ADEumServerCorrelationHeaders class.
  • To configure the agent to use your custom library to deliver its beacons over HTTP, use the ADEumCollectorChannel protocol and the ADEumAgentConfiguration class.

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.

Warning: You must initialize the agent using one of the ADEumInstrumentation's initWithKey methods before using this method.
CODE 
@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.

CODE 
- (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:

CODE 
@property (copy, nonatomic) NSError *error;

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

CODE 
@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.

    CODE 
    @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:

JSON 
- (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:

JSON 
- (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.

CODE 
@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:

Sample
JSON 
- (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:

    CODE 
    /** 
* 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.
    CODE 
    @property (nonatomic, strong) id<ADEumCollectorChannel> collectorChannel;