ForeSee Class Reference

Inherits from NSObject
Declared in ForeSee.h
ForeSee.m

Overview

The ForeSee class provides the main interface to the Trigger module and the SessionReplay module, bundled together in the ForeSee framework. You must add a foresee_configuration.json file to your project that defines the behavior of the Trigger module (e.g. defines the triggering criteria for inviting a user to participate in a survey) and it defines whether to enable SessionReplay.

To use the ForeSee framework, simply call [ForeSee start]; in your application:didFinishLaunchingWithOptions: and it will automatically parse your configuration file and start the Trigger module and SessionReplay module.

(Alternatively, use + (void)startWithConfigurationFile:(NSString *)configFileName to specify a custom configuration file name (e.g. to include a configuration for both debug and release builds).)

While integrating the ForeSee framework into your app, it is suggested you enable debug logging. This will output useful log messages to the console.

Configuration

Most configuration is done through the foresee_configuration.json file. Behavior such as trigger criteria, invitation modes, repeat days, are done through the configuration file. If you want to customize runtime behavior e.g. displaying custom invitations, you can provide a delegate with the setInviteDelegate: method.

Debugging

When testing your configuration, it is recommended you enable debug log mode. Useful information regarding internal state will be posted to the console for inspection.

Notifications

The ForeSee SDK will post a number of notifications to the default NSNotificationCenter:

  • FSInviteDidShowNotification ( Posted when the default invitation was displayed. )
  • FSInviteWasDeclinedNotification ( Posted when the default invitation was declined. )
  • FSInviteWasAcceptedNotification ( Posted when the default invitation was accepted. )
  • FSSurveyWasCompletedNotification ( Posted when the survey was completed. )
  • FSSurveyWasAbandonedNotification ( Posted when the survey was abandoned. )
  • FSSurveyDidShowNotification ( Posted when the survey was presented. )

CPPs

CPPs (Customer Passed Parameters) are key/value pairs that you can optionally attach to a completed survey.

Masking

If you have SessionReplay enabled, you can register views to mask using the maskView: method. Masked views will be replaced by a black box in the recorded movie. By default, UITextFields that are marked as secure fields will automatically be masked.

Start-up

+ start

Starts the Trigger and SessionReplay modules.

+ (void)start

Discussion

Behavior of the two modules is defined in the foresee_configuration.json file.

For SessionReplay, a recording starts once this method is called and ends when the app is put into the background.

Declared In

ForeSee.h

+ startWithConfigurationFile:

Starts the Trigger and SessionReplay modules using a custom configuration file.

+ (void)startWithConfigurationFile:(NSString *)configFileName

Parameters

configFileName

The name of the configuration file to use when loading modules

Discussion

Behavior of the two modules is defined in the named configuration file in your project.

See Also

Declared In

ForeSee.h

+ startWithConfigurationJson:

Starts the Trigger and SessionReplay modules using custom configuration JSON.

+ (void)startWithConfigurationJson:(NSString *)json

Parameters

json

The configuration JSON to use when loading modules

Discussion

Behavior of the two modules is defined by the string provided.

See Also

Declared In

ForeSee.h

Debug

+ version

Gets the version of the SDK

+ (NSString *)version

Declared In

ForeSee.h

+ setMaskingDebugEnabled:

Sets whether or not to enable masking debug for Replay

+ (void)setMaskingDebugEnabled:(BOOL)enabled

Parameters

enabled

YES to enable masking debug, NO to disable.

Discussion

Masking debug will draw translucent red areas on screen to indicate which views are masked and which are not. This must be called after the ForeSee SDK is started. By default, masking debug is disabled

Declared In

ForeSee.h

+ isMaskingDebugEnabled

Returns whether or not masking debug is enabled

+ (BOOL)isMaskingDebugEnabled

Return Value

YES if enabled, NO otherwise

Declared In

ForeSee.h

+ setDebugLogEnabled:

Sets whether or not to enable debug logging

+ (void)setDebugLogEnabled:(BOOL)enabled

Parameters

enabled

YES to enable debug logging, NO to disable.

Discussion

Debug logging will print useful state information to the console for inspection. By default, debug logging is disabled

Declared In

ForeSee.h

+ isDebugLogEnabled

Returns whether or not debug logging is enabled

+ (BOOL)isDebugLogEnabled

Return Value

YES if enabled, NO otherwise

Declared In

ForeSee.h

+ setEventLogEnabled:

Sets whether or not to enable remote event logging

+ (void)setEventLogEnabled:(BOOL)enabled

Parameters

enabled

YES to enable event logging, NO to disable.

Discussion

Event logging captures and transmits significant events that occur during the SDK life cycle. By default, event logging is enabled and it is highly recommended that this logging remain enabled in release builds.

Declared In

ForeSee.h

+ isEventLogEnabled

Returns whether or not event logging is enabled

+ (BOOL)isEventLogEnabled

Return Value

YES if enabled, NO otherwise

Declared In

ForeSee.h

+ resetState

Erases all stored counts and state in the SDK; resets the Trigger and Replay modules to be active and recording. This should only be used for specific debugging or testing purposes; it should not be used in production code.

+ (void)resetState

Declared In

ForeSee.h

+ setSkipPoolingCheck:

Disables the pooling check.

+ (void)setSkipPoolingCheck:(BOOL)shouldSkip

Parameters

shouldSkip

YES to skip the pooling check.

Discussion

When debugging your implementation of the ForeSee SDK, it may be useful to disable the pooling check. This ensures that the invite will always show if the loyalty criteria has been fulfilled.

Declared In

ForeSee.h

+ shouldSkipPoolingCheck

Get pooling check setting

+ (BOOL)shouldSkipPoolingCheck

Return Value

YES if pooling check is skipped, NO otherwise

Declared In

ForeSee.h

Trigger Delegate

+ setInviteDelegate:

Sets an invite lifecycle delegate

+ (void)setInviteDelegate:(id<FSInviteDelegate>)delegate

Parameters

delegate

An object conforming to the FSInviteDelegate protocol

Discussion

Objects conforming to the FSInviteDelegate protocol and registered with the SDK using this method will be notified of events in the SDK’s lifecycle

Declared In

ForeSee.h

+ setInviteHandler:

Sets a custom invite handler

+ (void)setInviteHandler:(id<FSInviteHandler>)inviteHandler

Parameters

inviteHandler

An object conforming to the FSInviteHandler protocol

Discussion

Use an object conforming to the FSInviteHandler protocol to display a custom invite. Objects will be told when to show and hide custom views, based on the user’s state.

Declared In

ForeSee.h

CPP (Customer Passed Parameters)

+ addCPPValue:forKey:

Adds a CPP to be sent to the server along with a completed survey

+ (void)addCPPValue:(NSString *)value forKey:(NSString *)key

Parameters

value

The value to transmit

key

The key identifying the value

Discussion

CPPs are unique to their provided key. If you add a value for an existing key, the old value will simply be overwritten.

Declared In

ForeSee.h

+ setCPPValue:forKey:

Adds a CPP to be sent to the server along with a completed survey

+ (void)setCPPValue:(NSString *)value forKey:(NSString *)key

Parameters

value

The value to transmit

key

The key identifying the value

Discussion

CPPs are unique to their provided key. If you set a value for an existing key, the old value will simply be overwritten.

Declared In

ForeSee.h

+ setCPPValueFromArray:forKey:

Adds a list of CPP values to be sent to the server along with a completed survey. The values will be sent as a comma-separated list.

+ (void)setCPPValueFromArray:(NSArray<NSString*> *)value forKey:(NSString *)key

Parameters

value

The values to transmit

key

The key identifying the values

Discussion

CPPs are unique to their provided key. If you set a value for an existing key, the old value will simply be overwritten.

Declared In

ForeSee.h

+ appendCPPValue:forKey:

Adds a CPP value to the end of the list of values for the given key. If no such list exists, then it will be created. If the key already contains a non-array value, then that value will be destroyed and a new list will be created.

+ (void)appendCPPValue:(NSString *)value forKey:(NSString *)key

Parameters

value

The value to add

key

The key identifying the values

Discussion

The values in the resulting array will be sent as a comma-separated list.

Declared In

ForeSee.h

+ removeCPPValueForKey:

Remove a CPP

+ (void)removeCPPValueForKey:(NSString *)key

Parameters

key

The key of the value to remove.

Declared In

ForeSee.h

Significant Events

+ incrementSignificantEventCountWithKey:

Increments the event count for a given key

+ (void)incrementSignificantEventCountWithKey:(NSString *)key

Parameters

key

The key of the event

Discussion

Significant events are defined in the foresee_configuration.json file.

Declared In

ForeSee.h

+ incrementSignificantEventCountAndCheckEligibilityWithKey:

Increments the event count for a given key and checks eligibity after

+ (void)incrementSignificantEventCountAndCheckEligibilityWithKey:(NSString *)key

Parameters

key

The key of the event

Declared In

ForeSee.h

Page Views

+ incrementPageViews

Increments the view controller load count (“page views”). This is done automatically for most view controllers.

+ (void)incrementPageViews

Declared In

ForeSee.h

Manual Control

+ showSurveyForSurveyID:

Force a survey to display for a given surveyID

+ (void)showSurveyForSurveyID:(NSString *)surveyID

Parameters

surveyID

The ID of the survey you wish to display.

Discussion

Calling this method will display a survey regardless of the user’s current eligibility.

Declared In

ForeSee.h

+ showInviteForSurveyID:

Force a invite to display for a given surveyID

+ (void)showInviteForSurveyID:(NSString *)surveyID

Parameters

surveyID

The ID of the survey you wish to invite the user to take.

Discussion

Calling this method will display an invite regardless of the user’s current eligibility.

Declared In

ForeSee.h

+ checkIfEligibleForSurvey

Checks to see if the user is currently eligible to be invited to a survey.

+ (void)checkIfEligibleForSurvey

Discussion

In order to be eligible, a number of conditions must be fulfilled:

  1. The library is in an enabled state. If the user has previously declined an invite or completed a survey, the library will be in a disabled state. Otherwise, the library is in an enabled state.
  2. The user has met the loyalty threshold defined in your foresee_configuration.json file.
  3. The user is in the sampling pool. If the previous two conditions have been met, the library makes an HTTP call to our servers to determine if the user is in the sampling pool. If s/he is, the invite will be presented. If not, the invite will not be shown. Disable this remote check with setSkipPoolingCheck:

Declared In

ForeSee.h

+ logReplayPageChange:

Manually add a page break to the replay session

+ (void)logReplayPageChange:(NSString *)pageName

Parameters

pageName

The name that will be displayed in the player when this page is displayed.

Discussion

Calling this method will add a custom page change into the replay. This is not necessary in most cases as changes between UIViewControllers are detected automatically.

Declared In

ForeSee.h

Masking

+ maskView:

Mask a view in a recording

+ (void)maskView:(UIView *)view

Parameters

view

The view to mask

Discussion

You can use this method to mark a view as needing masking. Typically, this would be called from a view controller’s viewDidLoad method

See Also

Declared In

ForeSee.h

+ unmaskView:

Un-mask a view in a recording

+ (void)unmaskView:(UIView *)view

Parameters

view

The view to unmask

See Also

Declared In

ForeSee.h

+ autoMaskViewsWithinView:

Find and mask all auto-maskable views contained within a view

+ (void)autoMaskViewsWithinView:(UIView *)view

Parameters

view

The view to search within

Discussion

Auto-masking is carried out in the ViewWillAppear method of all UIViewControllers. This method is useful to fill any gaps where the views aren’t available when the ViewWillAppear method is called, eg for cells in UITableViews.

Declared In

ForeSee.h

+ maskAlertsForWebView:

Mask JavaScript alerts spawned from a web view in a recording

+ (void)maskAlertsForWebView:(UIWebView *)webView

Parameters

webView

The view to mask

Discussion

You can use this method to mark a view as needing masking. Typically, this would be called from a view controller’s viewDidLoad method

Declared In

ForeSee.h

+ unmaskAlertsForWebView:

Un-mask JavaScript alerts spawned from a web view in a recording

+ (void)unmaskAlertsForWebView:(UIWebView *)webView

Parameters

webView

The view to unmask

Declared In

ForeSee.h

+ maskedViews

Retrieve all the masked views

+ (NSArray *)maskedViews

Declared In

ForeSee.h

Local Notification

+ surveyIDForLocalNotification:

If using the local notification invite mode, you can use this method to obtain the surveyID of the measure that triggered the invite.

+ (NSString *)surveyIDForLocalNotification:(UILocalNotification *)note

Parameters

note

The local notification that was presented to the user.

Return Value

The surveyID of the measure that triggered the invitation. You can use the surveyID to display the survey by calling showSurveyForSurveyID:

Discussion

As well as returning the surveyID, this method will also cancel the notification and remove it from Notification Center.

Declared In

ForeSee.h

+ showSurveyForLocalNotification:

Shows the survey associated with a local notification.

+ (void)showSurveyForLocalNotification:(UILocalNotification *)note

Parameters

note

The local notification that was presented to the user.

Discussion

This method will also cancel the notification and remove it from Notification Center.

Declared In

ForeSee.h

+ isRecording

Check if SessionReplay is running.

+ (BOOL)isRecording

Return Value

YES if SessionReplay is running, NO otherwise

Declared In

ForeSee.h

Contact Details

+ setContactDetails:

Sets a user’s contact details.

+ (void)setContactDetails:(NSString *)contactDetails

Parameters

contactDetails

The customer’s phone number or email address.

Discussion

This method can be used to provide a user’s contact information, so that they do not need to enter it manually. When provided, the default invite will skip the user input screen. Only applies to CONTACT surveys.

Declared In

ForeSee.h

+ contactDetails

Retrieves a user’s contact details.

+ (NSString *)contactDetails

Declared In

ForeSee.h

Custom invites

+ customInviteAccepted

Tells the SDK that a custom invite was accepted.

+ (void)customInviteAccepted

Discussion

You should call this method whenever a user accepts a custom invite that you’ve presented.

Declared In

ForeSee.h

+ customInviteDeclined

Tells the SDK that a custom invite was declined.

+ (void)customInviteDeclined

Discussion

You should call this method whenever a user declines a custom invite that you’ve presented.

Declared In

ForeSee.h

+ customInviteAcceptedWithContactDetails:

Tells the SDK that a custom invite was accepted and provides a user’s contact details

+ (void)customInviteAcceptedWithContactDetails:(NSString *)contactDetails

Parameters

contactDetails

The customer’s phone number or email address.

Discussion

You should call this method whenever a user accepts a custom invite that you’ve presented and you want to provide information the SDK can use to contact the user later.

Declared In

ForeSee.h

User profile

+ setUserProfile:

Sets a user profile.

+ (void)setUserProfile:(FSUserProfile *)userProfile

Parameters

userProfile

an FSUserProfile object

Discussion

The provided user profile is used to associate a specific user with events during logging.

Declared In

ForeSee.h