Skip to main content

App Feedback Android API Reference

Qualtrics Class​

The Qualtrics class lets your app communicate with Qualtrics App Feedback. The Qualtrics class is represented as a singleton, and the singleton is accessible through its instance() method. You can initialize the Qualtrics singleton with Brand ID, Project ID and Intercept IDs.

For more information about App Feedback and its key concepts, see App Feedback Basics.

Intercept IDs​

To utilize the SDK you'll need a Brand ID and a Project ID to initialize the Qualtrics class. This requires a Qualtrics account. If you do not have an account, please reach out to your Admin to have an account provisioned, or so they can relay the IDs required for moving forward.

Log into the Qualtrics account, navigate to the desired App Feedback Project and choose Intercepts near the top left of the screen. You should see a screen similar to the following:

Intercept ID

Click on the dropdown to the right of the desired intercept and choose Copy intercept IDs.

Usage​

The Android app first initializes the Qualtrics singleton with the current Context (as the context parameter with the initializeProject method). You can initialize the singleton in the app's MainActivity onCreate method.

When you want to display a creative, use the evaluateProject method to check the intercepts' display logic on the server asynchronously. After evaluation of the intercepts is complete, the method calls the completion callback (defined in a private subclass which implements the IQualtricsProjectEvaluationCallback interface) which returns a TargetingResults object to indicate to the app which creative should be displayed, if any.

Properties​

properties​

Signature
Properties properties

The properties object stores values that can be used throughout the app. Values placed in the map could include information such as the number of times the user has navigated to a specified view controller, location information, latency times, or other values that can be collected by the Android device. See Properties Class.

Methods​

display​

Signature
boolean display(Context context)
boolean display(Context context, boolean autoCloseAtEndOfSurvey)
boolean display(Context context, int layoutFlags, boolean autoCloseAtEndOfSurvey)

This method displays the specified creative(s). Typically, you need to check whether the creative should be displayed by evaluating an intercept's logic using the evaluateProject method. If a specific intercept is being evaluated using evaluateIntercept, then displayIntercept must be used rather than display.

Additionally, if the value for autoCloseAtEndOfSurvey is set true then after the survey associated with the intercept has been taken, the underlying survey view will be closed without user interaction.

Example​

Qualtrics.instance().display(context)
Qualtrics.instance().display(context);

displayIntercept​

Signature
boolean displayIntercept(Context context, String interceptId)
boolean displayIntercept(Context context, String interceptId, int layoutFlags)
boolean displayIntercept(Context context, String interceptID, int layoutFlags, boolean autoCloseAtEndOfSurvey)

This method displays the creative associated with the passing action set for the given intercept. Typically, you need to evaluate whether the creative should be displayed by evaluating an intercept's logic using the evaluateProject or evaluateIntercept methods.

Example​

Qualtrics.instance().displayIntercept(context, "INTERCEPT_ID")
Qualtrics.instance().displayIntercept(context, "INTERCEPT_ID");

displayTarget​

Signature
boolean displayTarget(Context context, String targetUrl)
boolean displayTarget(Context context, String targetUrl, boolean autoCloseAtEndOfSurvey)
boolean displayTarget(Context context, String targetUrl, int layoutFlags, boolean autoCloseAtEndOfSurvey)

Similar to display() but utilized to bypass the creative and only show the intercept target (typically a Qualtrics survey). autoCloseAtEndOfSurvey defaults to false.

Tip​

If you want to use Preventing Repeated Display with this function, you need to call targetingResult.setLastDisplayedTime(). Otherwise, the Prevent Repeated Display will not be respected.

Example​

Qualtrics.instance().displayTarget(context, "SURVEY_URL")
Qualtrics.instance().displayTarget(context, "SURVEY_URL");

evaluateProject​

Signature
void evaluateProject(IQualtricsProjectEvaluationCallback callback)

This method evaluates all intercepts that have been initialized and calls the specified completion callback with a map of TargetingResult objects. The TargetingResult object indicates the result of the evaluation for each intercept that has been initialized through the passed() method. See IQualtricsCallback Interface for more information about implementing the callback.

Tip​

This method should be called asynchronously for best performance, usually done by wrapping the invocation in a Runnable. Make sure that the evaluation resolves completely before display is invoked.

Example​

Qualtrics.instance().evaluateProject { targetingResults ->
    for ((_, value) in targetingResults) {
        if (value.passed()) {
            //...
        }
    }
}
Qualtrics.instance().evaluateProject(targetingResults -> {
    for (Map.Entry<String, TargetingResult> result : targetingResults.entrySet()) {
        if (result.getValue().passed()) {
            //...
        }
    }
});

evaluateIntercept​

Signature
void evaluateIntercept(String interceptId, IQualtricsCallback callback)

This method evaluates the specified intercept and calls the specified completion callback with a TargetingResult object. The TargetingResult object indicates the result of the evaluation through the passed() method. See IQualtricsCallback Interface for more information about implementing the callback.

Tip​

This method should be called asynchronously for best performance, usually done by wrapping the invocation in a Runnable. Make sure that the evaluation resolves completely before displayIntercept is invoked.

Example​

Qualtrics.instance().evaluateIntercept("INTERCEPT_ID") { targetingResult ->
    if (targetingResult.passed()) {
        // ...
    }
}
Qualtrics.instance().evaluateIntercept("INTERCEPT_ID", targetingResult -> {
    if (targetingResult.passed()) {
        // ...
    }
});

setLogLevel​

Signature
void setLogLevel(QualtricsLogLevel logLevel)

Method used to set the logging level of Qualtrics's okhttp, useful for debugging pre-prod app builds. Qualtrics will default to NONE unless overridden with this method. Takes QualtricsLogLevel.INFO or QualtricsLogLevel.NONE.

Tip​

You should set this before calling the initializeProject() method.

Example​

override fun onCreate(savedInstanceState: Bundle?) {
    // ...

    Qualtrics.instance().setLogLevel(QualtricsLogLevel.INFO)
    Qualtrics.instance().initializeProject("BRAND_ID", "PROJECT_ID", "EXT_REF_ID", context)
}
@Override
protected void onCreate(Bundle savedInstanceState) {
    // ...
    
    Qualtrics.instance().setLogLevel(QualtricsLogLevel.INFO);
    Qualtrics.instance().initializeProject("BRAND_ID", "PROJECT_ID", "EXT_REF_ID", context);
}

initializeProject​

Signature
void initializeProject(String brandId, String zoneId, Context context)
void initializeProject(String brandId, String zoneId, Context context, IQualtricsProjectInitializationCallback callback)
Signature (primed for XM Directory)
void initializeProject(String brandId, String zoneId, String extRefId, Context context)
void initializeProject(String brandId, String zoneId, String extRefId, Context context, IQualtricsProjectInitializationCallback callback)

This method initializes the Qualtrics singleton using the specified brand ID, project ID, optional external reference ID (for XM Directory functionality), context, and an optional callback function. Calling this method with an external reference ID primes the Qualtrics singleton for integration with XM Directory.

You should call this method asynchronously by defining a wrapper function at the application level, shown in the examples below. The method's InitializationResult map (returned in the callback) indicates the state of initialization for each intercept. See IQualtricsCallback Interface for more information about implementing the callback.

Tip​

This method should be called asynchronously for best performance. Make sure that the initializeProject function resolves completely before either evaluateProject or evaluateIntercept is invoked.

Tip​

If you are not using XMD functionality, simply omit the extRefId parameter in the examples below.

At the application level, define a function called initializeQualtrics that invokes the initializeProject function.

fun initializeQualtrics(brandId: String, zoneId: String, extRefId: String) {
    Qualtrics.instance().initializeProject(
        brandId, zoneId, extRefId, this
    ) { initializationResults ->
        for ((_, value) in initializationResults) {
            if (value.passed()) {
                // ...
            }
        }
    }
}
public void initializeQualtrics(String brandId, String zoneId, String extRefId) {
    Qualtrics.instance().initializeProject(brandId, zoneId, extRefId, context, initializationResults -> {
        for (Map.Entry<String, InitializationResult> result : initializationResults.entrySet()) {
            if (result.getValue().passed()) {
                // ...
            }
        }
    });
}

Then, simply call the initializeQualtrics function you just defined in a Runnable. Do this wherever you want to perform the initialization, typically in an Activity's (or Application's) onCreate method.

fun onCreate() {
    // ...

    val application = this.application as YourApplication
    application.initializeQualtrics("BRAND_ID", "ZONE_ID", "EXT_REF_ID")
}
public void onCreate() {
    // ...

    YourApplication application = (YourApplication) this.getApplication();
    application.initializeQualtrics("BRAND_ID", "ZONE_ID", "EXT_REF_ID");
}

getInitializedIntercepts​

Signature
ArrayList getInitializedIntercepts()

This method returns an array of intercept IDs for all the intercepts in the project that have been successfully initialized (intercept is published and active). This list can be used to evaluate a specific intercept.

Example​

val initializedIntercepts = Qualtrics.instance().initializedIntercepts
for (interceptID in initializedIntercepts) {
  Qualtrics.instance().evaluateIntercept(interceptID, callback)
}
ArrayList<String> initializedIntercepts = Qualtrics.instance().getInitializedIntercepts();
for (String interceptID : initializedIntercepts) {
    Qualtrics.instance().evaluateIntercept(interceptID, callback);
}

getPassingIntercepts​

Signature
ArrayList getPassingIntercepts()

This method returns an array of intercept IDs for all the intercepts in the project that have been evaluated and determined as passing. This list can be used to display a specific intercept.

Example​

val passingIntercepts = Qualtrics.instance().passingIntercepts
for (interceptID in passingIntercepts) {
    Qualtrics.instance().displayIntercept(context, interceptID, callback)
}
ArrayList<String> passingIntercepts = Qualtrics.instance().getPassingIntercepts();
for (String interceptID : passingIntercepts) {
    Qualtrics.instance().displayIntercept(context, interceptID, callback);
}

getQualtricsContactId​

Signature
String getQualtricsContactId(String interceptId)

This method returns the contact ID (touchpoint ID) associated with the intercept for the current XM directory contact if one is present, else it returns null.

Example​

val contactId = Qualtrics.instance().getQualtricsContactId(interceptId)
String contactId = Qualtrics.instance().getQualtricsContactId(interceptId);

instance​

Signature
static Qualtrics instance()

Returns the Qualtrics singleton object.

Example​

Qualtrics.instance()
Qualtrics.instance();

registerViewVisit​

Signature
void registerViewVisit(String viewName)

You can use this method to record visits to a particular view. For more information about Intercept statistics, see: User Analytics with the Mobile App SDK.

Example​

Qualtrics.instance().registerViewVisit("ViewName")
Qualtrics.instance().registerViewVisit("ViewName");

resetTimer​

Signature
void resetTimer()

This method resets the usage timer that is available to the intercept on the server as Time Spent in App.

Example​

Qualtrics.instance().resetTimer()
Qualtrics.instance().resetTimer();

resetViewCounter​

Signature
void resetViewCounter()

This method resets the view count to zero. It is available to the intercept as the View Count value in the intercept display logic.

Example​

Qualtrics.instance().resetViewCounter()
Qualtrics.instance().resetViewCounter();

setEmbeddedFeedbackDialogCloseListener​

Signature
void setEmbeddedFeedbackDialogCloseListener IQualtricsEmbeddedFeedbackDialogCloseListener listener)

This method accepts an implementation of IQualtricsEmbeddedFeedbackDialogCloseListener which is invoked whenever the Mobile Embedded Feedback Dialog is closed. Once a listener is invoked once, it will not be invoked again and the function needs to be called again with a new or same listener.

Example​

Qualtrics.instance().setEmbeddedFeedbackDialogCloseListener {
    // ...
}
Qualtrics.instance().setEmbeddedFeedbackDialogCloseListener(() -> {
    // ...
});

getCreativeTheme/setCreativeTheme​

Signature
QualtricsTheme getCreativeTheme()
void setCreativeTheme(@NonNull QualtricsTheme creativeTheme)

Read more in Advanced theming capabilities on Android and iOS.

Example​

// get
Qualtrics.instance().creativeTheme

// set
Qualtrics.instance().creativeTheme = theme
// get
Qualtrics.instance().getCreativeTheme();

// set
Qualtrics.instance().setCreativeTheme(theme);

evaluateTargetingLogic​

This API call is part of our older version of the SDK. While still available to use, we recommend switching to evaluateProject() and evaluateIntercept().

Signature
void evaluateTargetingLogic(IQualtricsCallback callback)

This method asynchronously evaluates the current intercept and calls the specified completion callback with a TargetingResult object. The TargetingResult object indicates the result of the evaluation through the passed() method. See IQualtricsCallback Interface for more information about implementing the callback.

Example​

Qualtrics.instance().evaluateTargetingLogic { targetingResult ->
    // ...
}
Qualtrics.instance().evaluateTargetingLogic(targetingResult -> {
    // ...
});

initialize​

This API call is part of our older version of the SDK. While still available to use, we recommend switching to initializeProject().

Signature
void initialize(String brandId, String zoneId, String interceptId, Context context)
void initialize(String brandId, String zoneId, String interceptId, Context context, IQualtricsInitializationCallback callback)

This method initializes the Qualtrics singleton using the specified brand ID, project ID, intercept ID, context, and, optionally, callback. You typically call this method in an Activity's (or Application's) onCreate method. To find the necessary intercept ID, see Intercept ID for App Feedback.

Tip​

Calling the initialize function will make a network request to our back-end so this call should be made during onCreate of an Application or during an Activity's onCreate method. This is a one-time call required to fetch the details of the intercept.

Example​

override fun onCreate(savedInstanceState: Bundle?) {
    // ...

    Qualtrics.instance().initialize("BRAND_ID", "PROJECT_ID", "INTERCEPT_ID", context)
}
@Override
protected void onCreate(Bundle savedInstanceState) {
    // ...

    Qualtrics.instance().initialize("BRAND_ID", "PROJECT_ID", "INTERCEPT_ID", context);
}

InitializationResult Class​

Encapsulates the result of initialization of App Feedback. Implementers of the IQualtricsInitializationCallback.run() method have access to an instance of this class.

Methods​

getMessage​

Signature
String getMessage()

Returns a string that indicates the status of App Feedback initialization.

Example​

result.message
result.getMessage();

passed​

Signature
boolean passed()

Indicates whether initialization of App Feedback was successful.

Example​

result.passed()
result.passed();

IQualtricsCallback Interface​

You need to create a class that implements the IQualtricsCallback interface (or use a lambda function) in order to receive asynchronous notifications that indicate if evaluation of an intercept is complete. The only method you need to implement is run.

Methods​

run​

Signature
void run(TargetingResult targetingResult)

This method will be called when an intercept is triggered. Should be implemented to display a creative as shown in the following code example:

Example​
val myCallback = IQualtricsCallback { targetingResult ->
    if (targetingResult.passed()) {
        Qualtrics.instance().display(context)
    }
}
IQualtricsCallback myCallback = targetingResult -> {
    if (targetingResult.passed()) {
        Qualtrics.instance().display(context);
    }
};

IQualtricsInitializationCallback Interface​

Methods​

run​

Signature
void run(InitializationResult initializationResult)

Called upon completion of initialization of App Feedback and allows access to a map of InitializationResult objects. Initialization status can be obtained via initializationResult.

Example​
val myCallback = IQualtricsInitializationCallback { initializationResult ->
    if (initializationResult.passed()) {
        // ...
    }
}
IQualtricsInitializationCallback myCallback = initializationResult -> {
    if (initializationResult.passed()) {
        // ...
    }
};

IQualtricsProjectEvaluationCallback Interface​

You need to create a class that implements the IQualtricsProjectEvaluationCallback interface (or use a lambda function) in order to receive asynchronous notifications that project evaluation is complete. The only method you need to implement is run.

Methods​

run​

Signature
void run(Map<String, TargetingResult> targetingResults)

This method will be called when an intercept is triggered. Could be implemented to display a creative as shown in the following code example:

Example​
val myCallback = IQualtricsProjectEvaluationCallback { targetingResults ->
    targetingResults.forEach { (key, result) ->
        if (result.passed()) {
            Qualtrics.instance().displayIntercept(context, key)
        }
    }
}
IQualtricsProjectEvaluationCallback myCallback = targetingResults -> {
    for (Map.Entry<String, TargetingResult> entry : targetingResults.entrySet()) {
        if (entry.getValue().passed()) {
            Qualtrics.instance().displayIntercept(context, entry.getKey());
        }
    }
};

Properties Class​

The Properties class allows you to store values that are sent back to the server and can be used as embedded data in surveys. For more information about using property values in surveys, see Using Embedded Data.

Methods​

getNotificationIconAsset/setNotificationIconAsset​

Signature
int getNotificationIconAsset()
void setNotificationIconAsset(int asset)

This property gets or sets the Notification Icon for all Qualtrics generated Notifications.

Tip​

This must be called after initialization of the intercept.

Example​
// get
Qualtrics.instance().properties.notificationIconAsset

// set
Qualtrics.instance().properties.notificationIconAsset = R.drawable.your_notification_icon
// get
Qualtrics.instance().properties.getNotificationIconAsset();

// set
Qualtrics.instance().properties.setNotificationIconAsset(R.drawable.your_notification_icon);

removeNotificationIconAsset​

Signature
void removeNotificationIconAsset()

This method removes the Notification Icon for all Qualtrics generated Notifications

Example​
Qualtrics.instance().properties.removeNotificationIconAsset()
Qualtrics.instance().properties.removeNotificationIconAsset();

setString​

Signature
void setString(String key, String value)

Sets the string value for the specified key. The value is sent back to the server and can be used in the intercept. For an example, see: Using Embedded Data.

Example​
Qualtrics.instance().properties.setString("firstName", "John")
Qualtrics.instance().properties.setString("firstName", "John");

setNumber​

Signature
void setNumber(String key, Double value)

Sets the double value for the specified key. The value is sent back to the server and can be used in the intercept. For an example, see: Using Embedded Data.

Example​
Qualtrics.instance().properties.setNumber("age", 25.0)
Qualtrics.instance().properties.setNumber("age", 25.0);

setDateTime​

Signature
void setDateTime(String key)

Sets the current system time to the specified key. The value is sent back to the server and can be used in the intercept. For an example, see: Using Embedded Data.

Example​
Qualtrics.instance().properties.setDateTime("propertyKey")
Qualtrics.instance().properties.setDateTime("propertyKey");

TargetingResult Class​

Methods​

getCreativeType​

Signature
CreativeType getCreativeType()

This method returns the CreativeType of the passing action set, else null.

Example​
Qualtrics.instance().evaluateIntercept("INTERCEPT_ID") { targetingResult ->
    if (targetingResult.creativeType == CreativeType.MobilePopOver) {
        // ...
    }
}
Qualtrics.instance().evaluateIntercept("INTERCEPT_ID", targetingResult -> {
    if (targetingResult.getCreativeType() == CreativeType.MobilePopOver) {
        // ...
    }
});

getError​

Signature
Exception getError()

This method returns an Exception from the last evaluation of the intercept if applicable.

Example​
Qualtrics.instance().evaluateIntercept("INTERCEPT_ID") { targetingResult ->
    if (targetingResult.passed()) {
        // ...
    } else {
        val error = targetingResult.error
    }
}
Qualtrics.instance().evaluateIntercept("INTERCEPT_ID", targetingResult -> {
    if (targetingResult.passed()) {
        // ...
    } else {
        Exception error = targetingResult.getError();
    }
});

getSurveyUrl​

Signature
String getSurveyUrl()

This method returns the link to the survey in the current creative. The link can be used by app code to display the survey instead of calling displayWithCurrentView.

The following code example shows how to obtain the survey link from a returned TargetingResult and log it to the debug console.

Example​
Qualtrics.instance().evaluateIntercept("INTERCEPT_ID") { targetingResult ->
    if (targetingResult.passed()) {
        android.util.Log.d("DEBUG", targetingResult.surveyUrl);
    }
}
Qualtrics.instance().evaluateIntercept("INTERCEPT_ID", targetingResult -> {
    if (targetingResult.passed()) {
        android.util.Log.d("DEBUG", targetingResult.getSurveyUrl());
    }
});

getTargetingResultStatus​

Signature
TargetingResultStatus getTargetingResultStatus()

Returns the results of the evaluation as a TargetingResultStatus enum.

Example​
targetingResult.targetingResultStatus
targetingResult.getTargetingResultStatus();

passed​

Signature
boolean passed()

This method indicates the state of the server-side evaluation of the intercept. If it is true, evaluation was successful and the creative should be displayed.

The following code example shows a typical use of the passed property.

Example​
val myCallback = IQualtricsCallback { targetingResult ->
    if (targetingResult.passed()) {
        Qualtrics.instance().display(context)
    }
}
IQualtricsCallback myCallback = targetingResult -> {
    if (targetingResult.passed()) {
        Qualtrics.instance().display(context);
    }
};

recordClick​

Signature
void recordClick()

The method records a click that is reported back to the server. It is associated with the intercept that was used to initialize the Qualtrics singleton. You can view the click statistics in the View Stats tab for the intercept. For more information, see: User Analytics with the Mobile App SDK.

Example​
targetingResult.recordClick()
targetingResult.recordClick();

recordImpression​

Signature
void recordImpression()

This method reports an impression associated with the intercept when initializing the Qualtrics object (using the initializeWithIntercept method) back to the server. The impressions are reported in the View Stats tab for that intercept in the server user interface. For more information, see: User Analytics with the Mobile App SDK.

Example​
targetingResult.recordImpression()
targetingResult.recordImpression();

setLastDisplayedTime​

Signature
void setLastDisplayedTime()

Sets the last displayed time of a TargetingResult to the current time this function is called.

Tip​

This function is already called automatically when an intercept is displayed, but it can be used in custom use cases where the Qualtrics display function is not used to display the intercept.

Example​
Qualtrics.instance().evaluateIntercept("INTERCEPT_ID") { targetingResult ->
    targetingResult.setLastDisplayedTime()
}
Qualtrics.instance().evaluateIntercept("INTERCEPT_ID", targetingResult -> {
    targetingResult.setLastDisplayedTime();
});

CreativeType Enum​

Values​

ValueMeaning
NotificationUsing the Mobile Notification Creative.
PopOverUsing the Mobile PopOver Creative.
EmbeddedFeedbackUsing the Mobile Embedded Feedback Creative.

TargetingResultStatus Enum​

The TargetingResultStatus enum indicates the status of the evaluation of the specified intercept.

Values​

ValueMeaning
passedTargeting logic passed successfully.
failedLogicThe targeting logic did not pass.
sampledOutThe targeting logic passed, but the intercept sampling rate prevented the survey invitation from appearing.
multipleDisplayPreventedThe survey invitation has a Prevent Repeated Display option set. This prevents the survey invitation from appearing again for a specified time period.
errorAn error occurred when attempting to evaluate targeting logic. Use the getError method on the TargetingResult object to determine more about this error.