Configuration - Configuration Options

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

    "clientId": "<YOUR CLIENT ID>",
    "measures": [
            "surveyId": "<YOUR SURVEY ID>",
            "launchCount": 4,
    "cppParameters": {
        "AppVersion": "<YOUR APP VERSION>",
        "AnotherCPP": "CPP #2"
    "cxReplayEnabled": true,
    "repeatDaysAfterDecline": 90,
    "repeatDaysAfterComplete": 90,
    "customLogoName": "<YOUR COMPANY LOGO IMAGE FILE>",
    "notificationType": "CONTACT"

This shows our recommended values, along with some you’ll need to add yourself, as indicated by the triangular braces, eg. <YOUR CLIENT ID>.

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 will default to being disabled or ignored.

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

Configuration Options

Client ID

clientIdRequired String

This is the unique ID for the client’s app which should have been set up and communicated to the client by their ForeSee Satisfaction Research Analyst.


measuresRequired 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.

surveyIdRequired String

An ID that, together with the clientId, identifies a unique survey.

Display Criteria

The following options determine the conditions under which a survey invite will be shown. These criteria are evaluated whenever eligibility is checked and an invite is shown whenever any one of them has been met.

launchCount(Optional) Number

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

pageViews(Optional) Number

The number of view controllers that the user must view in the app before they are eligible to be invited to participate in this measure’s survey.

daysSinceFirstLaunch(Optional) Number

The number of days since the first time the app was launched before the user is eligible to be invited 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 to be invited 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 that specific event must occur before the user becomes eligible to see an invite. 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 criteria 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 to be invited to participate in the survey when every criteria 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 criteria 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 will be eligible to be invited to participate in the survey whenever any of the following are true

  • the app has been launched 20 times
  • it’s been at least 9 days since the app was first launched
  • the user has loaded 6 view controllers and launched the app 7 times
  • it’s been at least 6 days since the last launch and event5 has been triggered 9 times.

Custom Parameters

cppParameters(Optional) Object

CPPs (Customer Passed Parameter) 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 they can be defined in the client’s code by calling…

[ForeSee addCPPValue:forKey:];


cxReplayEnabled – (Optional) Boolean

Key to enabled/disable cxReplay.

(Note: the sessionReplayEnabled parameter name used in previous versions is deprecated.)

Defaults to false.

cxReplayStorage – (Optional) Object

An object containing cxReplay configuration properties

cxReplayStorageLimitMegabytes – (Optional) Number

The maximum amount of storage (in megabytes) cxReplay will use to store sessions.

Defaults to 80. Valid only inside cxReplayStorage.

cxReplayStorageLimitAsPercentageOfTotalSpace – (Optional) Number

The required amount of disk space (as a percentage of the device’s total disk size) that must be available for cxReplay to continue recording. If the amount of space drops below this value, then recording will stop.

Defaults to 10%. Valid only inside cxReplayStorage.

cxReplayCellularTransmissionLimitMegabytes  – (Optional) Number

The maximum amount of data (in megabytes) that cxReplay will transmit over the user’s cellular network. Sessions will only be submitted over Wi-Fi once the user exceeds this limit.

Defaults to 20. Valid only inside cxReplayStorage.


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, they must fulfill the triggering criteria before being invited again.

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

repeatDaysAfterComplete(Optional) Number

Like repeatDaysAfterDecline except it 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 invite.

repeatDaysAfterAccept – (Optional) Number

This is only used in the LOCAL invitation mode 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 7 days.

customLogoName(Optional) String

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

It is recommended to include two 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 3 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 invite to appear poorly formatted. If you choose to use an image with non-standard dimensions, it is important to check if the invite displays correctly and adjust the image’s width and height if necessary.

notificationType(Optional) String

  • Defines which invite mode to use. Valid values are:
      In Session mode denotes that the survey is presented at the point where the user accepts the invitation.
      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 mode denotes that the user receives an invite in session, then a survey link as a local notification after they close the app.
      Exit Invite mode denotes that the user receives no invite during their app session – only a local notification after they close the app which takes them directly to the survey.

whitelistedHosts(Optional) Array

By default, the survey loads in a UIWebView inside the host app and the user is only permitted to navigate to pages within the domain and any other domains listed in this collection.

Other articles in this section:

  1. Configuration Options (current article)
  2. Configuration Structure
  3. Specifying Configuration Sources