Engine allows you to learn more about your user's journey. User Journey is the story of where a user goes throughout the day. For example:

• The user the started out at home.
• From 9:15am - 9:30am the user drove from home to work at Factual.
• From 9:30am - 12:30pm the was stationary at work at Factual.
• From 12:30pm - 12:35pm the user walked from Factual to Shake Shack at the Westfield Century City Mall.
• etc.

There are two types of user journey callbacks in the SDK: events and spans.

Events are delivered when small updates in the user's state occur. You can get a user journey event when the user's activity changes (ex: from stationary to walking), when the user's visiting state changes (ex: ingresses at or egresses from somewhere), when the user's place attachment state changes (ex: the user is now visiting a Shake Shack, but was previously at Starbucks), or when their app state changes (ex: the user backgrounds or foregrounds the app).

Spans are summarized user journey information over a defined span of time. Spans don't overlap with each other. There are two types of spans: transit spans (the user was traveling from one location to another) and stationary spans (the user was stopped at a location). Spans bundle up all of the state changes you would get in user journey events into individual span objects.

Consider the following user journey events:

• The user is at Shake Shack.
• The user started driving at 4:00pm.
• The user stopped driving and is now stationary at 4:30pm.
• The user is at Starbucks at 4:30pm.

This would be summarized in a single user journey span:

• From 4:00pm - 4:30pm the user drove from Shake Shack to Starbucks.

Track User Journey

To set up your app to receive user journey information, first have your AppDelegate implement the UserJourneyDelegate. For example:

#import <UIKit/UIKit.h>
#import "FactualEngine.h"

@interface AppDelegate : UIResponder <UIApplicationDelegate,
                                      FactualEngineDelegate, // Engine system debug info
                                      UserJourneyDelegate> // handling user journey

@property (strong, nonatomic) UIWindow *window;

@end

// ---- methods to support the UserJourneyDelegate interface ----
- (void)userJourneyEventDidOccur:(UserJourneyEvent *)userJourneyEvent {
  NSLog(@"User Journey Event Occurred: %@", [userJourneyEvent toDict]);
}

- (void)userJourneySpanDidOccur:(UserJourneySpan *)userJourneySpan {
  NSLog(@"User Journey Span occurred: %@", [userJourneySpan toDict]);
}

Finally, set the delegate when starting the sdk:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  
  // for demonstration, we're requesting location permissions here:
  if (_manager == nil) {
    _manager = [[CLLocationManager alloc] init];
  }
  [_manager requestAlwaysAuthorization];
  // start the SDK.
  // Note, you don't need to worry about whether or not the necessary
  // authorizations have returned from the user before calling start.
  // Engine will automatically detect for any changes to location
  // authorizations and behave accordingly.
  [FactualEngine startWithApiKey:@"Your API Key Here"
                        delegate:self   // FactualEngineDelegate
             userJourneyDelegate:self]; // UserJourneyDelegate
  return YES;
}

After these steps, your app will receive user journey event and span updates.