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 Android SDK is defined in the foresee_configuration.json file that must be included with 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"
    },
    "repeatDaysAfterDecline": 90,
    "repeatDaysAfterComplete": 90,
    "invite": {
        "logo": "<YOUR LOGO FILE NAME>",
        "header": "<YOUR HEADER FILE NAME>",
        "baseColor": [<RED>, <GREEN>, <BLUE>]
    },
    "feedback": {
        "feedbackSurveys": [
            {
                "name": "<YOUR FEEDBACK SURVEY NAME>",
                "feedbackId": "<YOUR FEEDBACK SURVEY ID>"
            },
            {
                "name": "<YOUR FEEDBACK SURVEY NAME>",
                "feedbackId": "<YOUR FEEDBACK SURVEY ID>",
                "surveyCompletionPageDelay": -1
            }
        ],
      "surveyCompletionPageDelay": 3
    },
    "notificationType": "CONTACT",
    "appName": "<YOUR APP NAME>"
}

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

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

The definitions of these options are explained in detail below, along with all 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.

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


  • 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 activities that the user must view in a single app session before they are eligible to be invited 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 app was first 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 app was last 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 that define custom events for your app that cause an invitation for this measure to display. 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 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 more arbitrarily complex eligibility requirements.

    For example:
"measures":[
        {
            "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 to be invited to participate in the survey whenever any of the following are true:

  • The app has been launched 20 times.
  • Nine days have passed since the app was first launched.
  • The user has loaded six view controllers and launched the app seven times.
  • Six days have passed since the last launch and event5 has been triggered nine times.


  • cppParameters - (Optional) Object
    Customer Passed Parameters (CPPs) are optional key-value pairs that are sent to ForeSee servers with a completed survey. CPPs provide additional data for analysis without increasing the number of questions in the survey. The keys of the CPPs must not contain any white spaces. CPPs can be defined statically in the configuration file or can be defined in your code by calling the ForeSee.addCPPValue() method.


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, in seconds, 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.


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

    Note: Ignoring a Contact or In-Session invitation by closing the app is counted as a decline on Android. See repeatDaysAfterAccept (below) for additional notes on Exit Survey and Exit Invitation modes.


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

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 the user followed the link they were 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 seven days.


  • 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]
}

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 resources. If not specified, the SDK attempts to load a file named fs_custom_logo in your app's resources. If no such file is found, the SDK loads a default image. The image file for this must be placed in the res/drawable folder of the project.

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 1:1.

Defaults to fs_custom_logo.

header(Optional) String

The location of the invitation's header in your app's resources. The header is colored using baseColor when no image is present. The image file for this header image must be placed in the res/drawable folder of the project.

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

The header image should have an aspect ratio no greater than 1:4.

Defaults to [0, 159, 255].

The SDK makes use of the standard drawable conventions to allow use of different resources for each screen size/density. You should consult Android documentation for information on providing 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 invitation modes 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. Instead, a local notification is given after the user closes the app. This takes them directly to the survey.


  • appName (Optional) String
    The name of your app that should be displayed on the invitation screens. If not specified, the SDK attempts to load a string keyed FORESEE_Misc_AppName in your app's resources. If no such string key is found, the SDK loads the default app name from package manager.


  • emailOnlyContactNotification (Optional) Boolean
    The parameter defines whether the email-only contact invitation mode is enabled. Valid values are:
  • true
    A Contact mode that accepts only E-Mail as a user’s contact.
  • false
    A Contact mode that accepts both E-Mail and Phone number as a user’s contacts. This is the default mode.

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.