ForeSee Developer Portal

Everything you need to configure and optimize your ForeSee products. Home of developer documentation, implementation guides, and release notes.

Blueprint

Configuration Options

Configuration of the ForeSee® SDK is defined in the foresee_configuration.json file that must be included with the your app. A simple configuration might look like this:

{
    "clientId": "<YOUR CLIENT ID>",
    "measures": [
        {
            "surveyId": "<YOUR SURVEY ID>",
            "launchCount": 4
        }
    ],
    "cppParameters": {
        "AppVersion": "<YOUR APP VERSION>",
        "AnotherCPP": "CPP 2"
    },
  // feedback block applies to Mobile SDK 5.2+  
  	"feedback":{  
    	"feedbackSurveys":[  
     			{  
        "name":"Sample 1",
        "feedbackId":"q9IvXiloOG"
    		  },
     		 {  
       	"name":"Sample 2",
       	"feedbackId":"gPzT3hhhSw",
        "surveyCompletionPageDelay":-1
    	  }
    ],
    "surveyCompletionPageDelay":3
    }
    "repeatDaysAfterDecline": 90,
    "repeatDaysAfterComplete": 90,
    "invite": {
        "logo": "<YOUR LOGO FILE NAME>",
        "header": "<YOUR HEADER FILE NAME>",
        "baseColor": [<RED>, <GREEN>, <BLUE>]
    },
    "notificationType": "CONTACT"
}

This shows ForeSee's recommended values, along with some you must add yourself (indicated by the triangular braces, e.g., <YOUR CLIENT ID>).

To configure the wording on the invitation, refer to the Localization article.

The definitions of these options are explained in detail below, along with all the other possible options. Please read through them to make sure you understand your configuration and the options available. As a general rule, if you leave an option out, it defaults to being disabled or ignored.

When considering a more complex configuration, please follow this JSON structure.

Configuration Options

Client ID

clientId - Required String

This is your unique ID which should have been set up and communicated to you by your ForeSee Satisfaction Research Analyst.


Measures

measures - Required Array

A measure is an abstraction for a survey and its triggering criteria. For each defined measure, you can optionally define the criteria the user must fulfill before being invited to take that measure’s survey.


surveyId - Required String

An identifier that, together with the clientId, represents a unique survey.


surveyStyle* - (Optional) String*
The style of the survey, which can be set to either modern or legacy.

Defaults to legacy.


Display Criteria

The following options determine the conditions under which a survey invitation is shown. These criteria are evaluated whenever eligibility is checked and, consequently, an invitation is shown whenever any one of them is met.

launchCount - (Optional) Number

The number of times the app is launched before the user is eligible for an invitation to participate in this measure’s survey. To ignore this criterion, simply leave this line out of the configuration.


pageViews(Optional) Number

The number of view controllers that the user must view in a single app session before they are eligible for an invitation to participate in this measure’s survey. This count is reset when the app is put into the background.


daysSinceFirstLaunch(Optional) Number

The number of days since the first time the app was launched before the user is eligible for an invitation to participate in this measure’s survey.


daysSinceLastLaunch(Optional) Number

The number of days since the last time the app was launched before the user is eligible for an invitation to participate in this measure’s survey.


significantEventThresholds - (Optional) Object

A collection of key-value pairs where the keys define custom events and the values are the number of times each specific event must occur before the user becomes eligible for an invitation. Unlike the built-in events (e.g. launchCount or daysSinceFirstLaunch), you are responsible for informing the SDK when these custom events occur by calling:

[ForeSee incrementSignficantEventCountForKey:];

This criterion can also be ignored by leaving this section out of the configuration.


combinedCriteria(Optional) Object

An array of objects each containing any of the above criteria. The user is eligible for an invitation to participate in the survey when every criterion is met in any of the combined criteria objects. This means that the user is eligible to be invited when any of the top-level criteria are met or when every criterion in any combined criteria is met. This structure can be used to create arbitrarily complex eligibility requirements.

For example:

   {
        "surveyId": "survey_id5",
        "launchCount": 20,
        "daysSinceFirstLaunch": 9,
        "combinedCriteria": [ {
            "pageViews": 6,
            "launchCount": 7
        },
        {
             "daysSinceLastLaunch": 6,
             "significantEventThresholds": {
                 "event5": 9
             }
        }]
    }

In the example measure above the user is eligible for an invitation to participate in the survey whenever any of the following are true:

>

  • The app has been launched 20 times.
  • It’s been at least nine days since the app was first launched.
  • The user has loaded six view controllers and launched the app seven times.
  • It’s been at least six days since the last launch and event5 has been triggered nine times.


Custom Parameters

cppParameters(Optional) Object

Customer Passed Parameters (CPPs) are optional key-value pairs that are sent to the ForeSee servers with a completed survey. They provide additional data for analysis without increasing the number of questions in the survey.

CPPs can be defined statically in the configuration file, or defined in your code by calling:

[ForeSee setCPPValue:forKey:];


Feedback

  • feedbackID - Required only if using Feedback (requires Mobile SDK 5.2+) String

The unique identifier given to each Feedback Survey in CX Suite. Instructions for finding the Feedback ID can be found under Feedback .


  • name - Required only if using Feedback (requires Mobile SDK 5.2+) String

The descriptive label given to the Feedback Survey. This is used with the commands to invoke the survey.


  • *surveyCompletionPageDelay* - Optional and applies only if using Feedback (requires Mobile SDK 5.2+) Integer

The amount of delay before closing the Feedback survey thank you page. Default is 3 seconds. Use -1 to prevent an auto-close. This can be set at the Survey level or the Global level. If set for both, the more specific setting governs.

General

repeatDaysAfterDecline - (Optional) Number

This parameter defines the number of days after the user has declined an invitation before they are able to be re-invited. Once the specified number of days has passed, the user must fulfill the triggering criteria before being invited again.

Note:
Ignoring the invitation by closing the app does not count as a decline on iOS). See repeatDaysAfterAccept (below) for additional information.

If you do not specify a value for this key, the user is never re-invited after declining an invitation.


repeatDaysAfterComplete - (Optional) Number

Similar to repeatDaysAfterDecline, this option specifies the number of days after completing a survey before the user is eligible to be re-invited.

If you do not specify a value for this key, the user is never re-invited after declining an invitation.


repeatDaysAfterAccept - (Optional) Number

This is only used in the Exit Invite and Exit Survey invitation modes and corresponds to the length of time a local notification can be ignored before the SDK moves into the DECLINED state. If a value for this key is not specified, this defaults to seven days.


customLogoName - (Only relevant for SDK version 5.0.3 and below) String

A custom logo to include in the top left corner of the default invitation.

It is recommended to include three image files in the app package - a standard definition version 40 pixels high and a maximum of 100 pixels wide, along with a version twice that size which should be suffixed with “@2x” (e.g., “custom_logo@2x.png”), and another version three times the size suffixed with "@3x".

If the image is not the correct height, it is resized to fit while maintaining the aspect ratio of the original image. Depending on the width of the original image, the resizing may cause the image to be too wide and the invitation to appear poorly formatted. If you choose to use an image with non-standard dimensions, it is important to check if the invitation displays correctly and adjust the image’s width and height as necessary.


notificationType - (Optional) String

Defines which invitation mode to use. Valid values are:

  • IN_SESSION
    In Session mode denotes that the survey is presented at the point where the user accepts the invitation.
  • CONTACT
    Contact mode denotes that the user can enter in an email address/mobile number to receive a link to the survey at a later time.
  • EXIT_SURVEY
    Exit Survey mode denotes that the user receives an invitation in session, then a survey link as a local notification after they close the app.
  • EXIT_INVITE
    Exit Invitation mode denotes that the user receives no invitation during their app session - only a local notification after they close the app which takes them directly to the survey.


enableWhitelist - (Optional) Boolean

When true, this option limits the set of URLs that can be loaded by the ForeSee survey to ForeSee URLs and to the domains listed in whitelistedHosts.

Defaults to false.


whitelistedHosts - (Optional) Array

The set of domains the ForeSee survey can load. Only observed when enableWhitelist is true.

Defaults to an empty list.


invite(Optional) Object

An object with keys defined for specifying a custom logo, a custom header image, and a custom base color for the invitation. All values are optional.

"invite": {
    "logo": "bitmap.png",
    "header": "masthead.png",
    "baseColor": [0, 159, 255]
}

Warning

Although the "header" and "logo" images are both optional, it is a common practice to supply values for these fields. If missing, the "logo" image defaults to an image reading "Your logo here;" and the "header" is empty.

logo(Optional) String

The location of the invitation's center logo. If specified, the SDK first looks for an image with this name in your app's main bundle. If not specified, the SDK attempts to load a file named fs_custom_logo in your app's main bundle. If no such file is found, the SDK loads a default image.

Defaults to fs_custom_logo.

header(Optional) String

The location of the invitation's header in your app's main bundle. The header is colored using baseColor if no image is present.

No default.

baseColor(Optional) Array

An array of numbers representing a color's RGB values. This color is used on the invitation's links, buttons, and header (when no header image is specified).

Defaults to [0, 159, 255].


Configuration Options


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.