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 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"
    },
    "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.

  • clientIdRequired String
    This is your unique ID which should have been set up and communicated to you by your 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.


  • 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 criteria, simply leave this line out of the configuration.


  • pageViews(Optional) NumberThe number of activities that the user must view in the app before they are eligible to be invited to participate in this measure’s survey.


  • daysSinceLaunch(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. This criteria can also be ignored by leaving it out of the configuration.


  • significantEventThresholds(Optional) Object
    A collection of key-value pairs that define custom events defined for your app that cause an invitation for this measure to appear. Unlike launchCount and daysSinceFirstLaunch, you are responsible for informing Trigger when these custom events occur through calls to the ForeSee.incrementSignificantEventCountWithKey() method. If this setting is omitted, the invitation never shows based on significant events.


  • 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 more 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.


  • 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 can be defined in your code by calling the ForeSee.addCPPValue() method.


  • 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.If a value for this key is not specified, 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.

    Note
    In the CONTACT invitation mode, the user is assumed to have completed the survey as soon as they accept the invitation since there is no way for the SDK to know if they follow the link they have been sent.

    If a value for this key is not specified, the user is never re-invited after completing a survey.


  • repeatDaysAfterAccept(Optional) Number
    This is only used in the EXIT_SURVEY and EXIT_INVITE 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 invitation. The image file for this logo should be placed in the res/drawable folder of the project. If this setting is omitted, no custom logo is shown. All logos are resized to fit the invitation by scaling the images to a particular height. To avoid logos taking up too much lateral space, the logo should have an aspect ratio no greater than 2:1.The following list shows the scale heights for different densities:

    • mdpi: 50px
    • hdpi: 75px
    • xhdpi: 100px
    • xxhdpi: 150px
    • xxxhdpi: 200px
    • Other: 75px

    The SDK makes use of the standard drawable conventions to allow use of different resources for each screen size/density. You should consult the Android documentation to see how to provide resources for each screen size / density.


  • notificationIcon (Optional) String
    The name of the icon that should be displayed with the notification for the EXIT_SURVEY and EXIT_INVITE notification types. By default, the SDK looks for a drawable named ic_notification in (res/drawable).


  • localNotificationDelay(Optional) Integer
    The time elapsed (in seconds) between a user exiting the app, and the local notification appearing.


  • notificationType(Optional) String
    Defines which invite 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 invite in session, then a survey link as a local notification after they close the app.
    • EXIT_INVITE
      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 WebView inside the host app and the user is only permitted to navigate to pages within the www.foresee.com domain and any other domains listed in this collection.

Replay

  • cxReplayEnabled – (Optional) BooleanKey to enabled/disable cxReplay.(Note: the sessionReplayEnabled parameter name used in previous versions is deprecated.)Defaults to false.


  • cxReplayStorage – (Optional) ObjectAn object containing cxReplay configuration properties


  • cxReplayStorageLimitMegabytes – (Optional) NumberThe maximum amount of storage (in megabytes) cxReplay will use to store sessions.Defaults to 80. Valid only inside cxReplayStorage.


  • cxReplayStorageLimitAsPercentageOfTotalSpace – (Optional) NumberThe 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) NumberThe 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.

Other articles in this section:

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