ForeSee Class Reference
| Inherits from | NSObject |
|---|---|
| Declared in | ForeSee.h ForeSee.m |
Overview
The ForeSee class provides the main interface to the ForeSee SDK. 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).
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.
(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.
Start-up
+ start
Starts the SDK.
+ (void)startDiscussion
Behavior of the module is defined in the foresee_configuration.json file.
Declared In
ForeSee.h
+ startWithConfigurationFile:
Starts the SDK using a custom configuration file.
+ (void)startWithConfigurationFile:(NSString *)configFileNameParameters
configFileName |
The name of the configuration file to use when loading modules |
|---|
Discussion
Behavior of the module is defined in the named configuration file in your project.
See Also
Declared In
ForeSee.h
+ startWithConfigurationJson:
Starts the SDK using custom configuration JSON.
+ (void)startWithConfigurationJson:(NSString *)jsonParameters
json |
The configuration JSON to use when loading modules |
|---|
Discussion
Behavior of the module is defined by the string provided.
See Also
Declared In
ForeSee.h
Debug
+ setDebugLogEnabled:
Sets whether or not to enable debug logging
+ (void)setDebugLogEnabled:(BOOL)enabledParameters
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)isDebugLogEnabledReturn Value
YES if enabled, NO otherwise
Declared In
ForeSee.h
+ setEventLogEnabled:
Sets whether or not to enable remote event logging
+ (void)setEventLogEnabled:(BOOL)enabledParameters
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)isEventLogEnabledReturn Value
YES if enabled, NO otherwise
Declared In
ForeSee.h
+ resetState
Erases all stored counts and state in the SDK; resets the SDK state 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)resetStateDeclared In
ForeSee.h
+ setSkipPoolingCheck:
Disables the pooling check.
+ (void)setSkipPoolingCheck:(BOOL)shouldSkipParameters
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)shouldSkipPoolingCheckReturn 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>)delegateParameters
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>)inviteHandlerParameters
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 (Deprecated: v4.2.0)
+ (void)addCPPValue:(NSString *)value forKey:(NSString *)keyParameters
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 *)keyParameters
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
+ 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 *)keyParameters
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 *)keyParameters
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
+ CPPValueForKey:
Retrieves the CPP value associated with the given key (or nil, if no such key exists)
+ (NSString *)CPPValueForKey:(NSString *)keyParameters
key |
The key to look for |
|---|
Return Value
the CPP’s value, if one exists; nil, if it doesn’t
Declared In
ForeSee.h
+ allCPPs
Retrieves a dictionary containing all existing CPPs, where the keys are each CPP’s key and the values are each CPP’s value as a string. If the key is assoicated with a list of values, then the value for that key will be a comma-separated list (exactly as they’re stored on the backend).
+ (NSDictionary *)allCPPsReturn Value
a dictionary containing all existing CPPs
Declared In
ForeSee.h
+ removeCPPValueForKey:
Remove a CPP
+ (void)removeCPPValueForKey:(NSString *)keyParameters
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 *)keyParameters
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 *)keyParameters
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)incrementPageViewsDeclared In
ForeSee.h
Manual Control
+ showSurveyForSurveyID:
Force a survey to display for a given surveyID
+ (void)showSurveyForSurveyID:(NSString *)surveyIDParameters
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 *)surveyIDParameters
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)checkIfEligibleForSurveyDiscussion
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
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. (Deprecated: v5.1.0)
+ (NSString *)surveyIDForLocalNotification:(UILocalNotification *)noteParameters
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. (Deprecated: v5.1.0)
+ (void)showSurveyForLocalNotification:(UILocalNotification *)noteParameters
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
+ surveyIdForNotificationResponse:
Returns the surveyId for the notification that triggered an invite.
+ (NSString *)surveyIdForNotificationResponse:(UNNotificationResponse *)responseParameters
response |
The notification that was sent to the user. |
|---|
Return Value
The surveyID of the measure that triggered the invitation. *
Discussion
Also, cancels the pending notification.
Declared In
ForeSee.h
+ showSurveyForNotificationResponse:
Shows the survey associated with a notification.
+ (void)showSurveyForNotificationResponse:(UNNotificationResponse *)responseParameters
response |
The notification that was presented to the user. |
|---|
Discussion
Also, cancels the pending notification.
Declared In
ForeSee.h
+ contactDetailsForType:
Retrieves a user’s contact details for the given contact type.
+ (NSString *)contactDetailsForType:(FSContactType)typeParameters
type |
an FSContactType |
|---|
Availability
v5.1.0
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 auto-populate the contact input field for CONTACT surveys.
Declared In
ForeSee.h
+ setContactDetails:forType:
Sets a user’s contact details.
+ (void)setContactDetails:(NSString *)contactDetails forType:(FSContactType)typeParameters
contactDetails |
The customer’s contact information (e.g. a phone number or email address) |
|---|---|
type |
an FSContactType that specifies the type of information prodvided in contactDetails |
Availability
v5.1.0
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 CONTACT invite will auto-populate the provided details for the user. Only valid for CONTACT surveys.
Declared In
ForeSee.h
+ setPreferredContactType:
Sets a preferred contact details type.
+ (void)setPreferredContactType:(FSContactType)typeParameters
type |
the preferred FSContactType |
|---|
Declared In
ForeSee.h
+ preferredContactType
Gets the preferred contact details type.
+ (FSContactType)preferredContactTypeDeclared In
ForeSee.h
+ allContactDetails
Retrieves all user contact details for every type.
+ (NSDictionary<NSNumber*,NSString*> *)allContactDetailsReturn Value
an NSDictionary where the keys are NSNumbers containing the FSContactType and the values are the actual contact details for that type
Availability
v5.1.0
Declared In
ForeSee.h
+ clearUserData
Clears any and all previously-set user data
+ (void)clearUserDataAvailability
v5.1.0
Declared In
ForeSee.h
+ setContactDetails:
Sets a user’s contact details. (Deprecated: v5.1.0)
+ (void)setContactDetails:(NSString *)contactDetailsParameters
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.
Warning: this method clears any previously-set values for any contact type. Use the typed contact details methods to support contact details with associated types.
Declared In
ForeSee.h
+ contactDetails
Retrieves a user’s contact details. (Deprecated: v5.1.0)
+ (NSString *)contactDetailsDeclared In
ForeSee.h
Custom invites
+ customInviteAccepted
Tells the SDK that a custom invite was accepted.
+ (void)customInviteAcceptedDiscussion
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)customInviteDeclinedDiscussion
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 *)contactDetailsParameters
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 *)userProfileParameters
userProfile |
an FSUserProfile object |
|---|
Discussion
The provided user profile is used to associate a specific user with events during logging.
Declared In
ForeSee.h