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)startWithConfiguration:(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
+ setMaskingDebugEnabled:
Sets whether or not to enable masking debug for cxReplay
+ (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 cxReplay 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:
Add 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:
Add 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.
See Also
Declared In
ForeSee.h
+ removeCPPValueForKey:
Remove a CPP
+ (void)removeCPPValueForKey:(NSString *)key
Parameters
key |
The key of the value to remove. |
---|
See Also
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:
- 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.
- The user has met the loyalty threshold defined in your foresee_configuration.json file.
- 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
See Also
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 |
---|
See Also
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