Telemetry

Telemetry

To receive telemetry event data from ADAL, a class ADTelemetry.m is provided. A reference to this object can be attained by calling [[ADTelemetry sharedInstance].

Events are published [via the callback pattern] to an <ADDispatcher> interface. Users of this library who wish to receive telemetry data are expected to supply their own implementation of this interface by calling [[ADTelemetry sharedInstance] addDispatcher:dispatcher aggregationRequired:aggregationRequired].

addDispatcher(ADDefaultDispatcher, boolean) accepts two arguments:

• dispatcher : the dispatcher implementation to receive telemetry events
• boolean aggregationRequired : flag used to turn aggregation of events on/off

To capture telemetry data, add the following to your application subclass:

// Establish NSMutableArray for events
_receivedEvents = [NSMutableArray array];

// How to implement Telemetry with Flag to turn event aggregation on/off
- (void)setupADTelemetryDispatcherWithAggregationRequired:(BOOL)aggregationRequired
{
    ADTelemetryDispatcher* dispatcher = [ADTelemetryDispatcher new];
    
    // the dispatcher will store the telemetry events it receives
    [dispatcher setCallback:^(NSDictionary* event)
     {
         [_receivedEvents addObject:event];
     }];
    
    // register the dispatcher
    [[ADTelemetry sharedInstance] addDispatcher:dispatcher aggregationRequired:aggregationRequired];
}

To capture telemtry when a dispatcher has already been created:

@interface TestViewController () <ADDispatcher>

@end

@implementation TestViewController
- (id)init
{
// Get shared dispatcher instance..
 [[ADTelemetry sharedInstance] addDispatcher:self aggregationRequired:YES];
    
    return self;
}   

// Capture dispatch event
- (void)dispatchEvent:(nonnull NSDictionary<NSString*, NSString*> *)event
{
    NSLog("ADTelemetry event dispatched: %@", event);
}

@end

Event Aggregation

Using the aggregationRequired flag, users of ADAL can toggle between two modes of event dispatch: aggregated and non-aggregated. If aggregationRequired is set to YES, all events generated per-request are collapsed into a single event prior to dispatch. If false, events are not collapsed prior to dispatch, and users of the library are instead served distinct events representing the various phases of an authentication request.

Please note: Telemetry data is verbose, and applications with large and active user bases generate proportionally large quantities of telemetry data. For this reason, it is advised that users of this library set aggregationRequired:YES

Personal Identifiable Information (PII) & Organizational Identifiable Information (OII)

By default, ADAL telemetry does not capture or log any PII or OII. The library does allow app developers to turn this on through a setter in the MSIDTelemetry class. By turning on PII or OII, the app takes responsibility for safely handling highly-sensitive data and complying with any regulatory requirements.

// By default, PII and OII is not captured

// PII and OII will be captured
 [ADTelemetry sharedInstance].piiEnabled = YES;

// PII and OII will NOT be captured 
 [ADTelemetry sharedInstance].piiEnabled = NO;