Skip to main content

App Feedback iOS 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 shared property. You can initialize the Qualtrics singleton with the Brand, Project and Intercept IDs.

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

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 either have an account provisioned or relay the IDs required to move forward.

Log into your 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 iOS app first initializes the Qualtrics singleton with the brand ID, project ID and completion handler. You can do this in the app delegate (in didFinishLaunchingWithOptions).

When you want to display a creative, use the evaluateProject or evaluateIntercept method to check the Intercept's display logic on the server asynchronously. After evaluation of the Intercept is complete, the method calls the completion block which returns a TargetingResult object to indicate to the app whether the creative should be displayed.

Property​

properties​

Swift
public var properties: Properties
Objective-C
@property (nonatomic, readonly, strong) Properties * _Nonnull properties;

The properties object stores values that can be used throughout the app. Values placed in the object 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 iOS device.

Methods​

display​

Swift
public func display(viewController: UIViewController, autoCloseSurvey: NSNumber?) -> Bool
Objective-C
- (BOOL)displayWithViewController:(UIViewController * _Nonnull)viewController autoCloseSurvey: (NSNumber)autoCloseSurvey;

This method displays the specified creative in the specified view controller. Typically, you need to evaluate 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 autoCloseSurvey is set to true, then after the survey associated with the intercept has been taken, the underlying survey view will be closed without user interaction.

Example​
let displayed = Qualtrics.shared.display(viewController: self, autoCloseSurvey: true)
BOOL displayResult = [[Qualtrics shared] displayWithViewController:self autoCloseSurvey: YES];

displayIntercept​

Swift
public func displayIntercept(for interceptID: String, viewController: UIViewController) -> Bool
Objective-C
[Qualtrics.shared displayInterceptFor:<#(NSString * _Nonnull)#> viewController:<#(UIViewController * _Nonnull)#>]

This method displays the creative associated with the passing Action Set for the given Intercept in the specified view controller. 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.shared.displayIntercept(for: “interceptID”, viewController: self)
[Qualtrics.shared displayInterceptFor:@"interceptID" viewController: self];

displayTarget​

Swift
public func displayTarget(viewController: UIViewController, targetUrl: String, autoCloseSurvey: Bool) -> Bool
Objective-C
[Qualtrics.shared displayTargetWithTargetViewController:<#(UIViewController * _Nonnull)#>viewController targetUrl: (NSString)targetUrl autoCloseSurvey: (NSNumber)autoCloseSurvey]

This method is used to bypass the creative and only show the target survey in the Qualtrics webview.

Tip​

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

Example​
Qualtrics.shared.evaluateProject { (targetingResults) in 
  for (interceptID, targetingResult) in targetingResults {
    if targetingResult.passed() {
      guard let surveyUrl = result.getSurveyUrl() else{
        return
      }
      let displayed = Qualtrics.shared.displayTarget(targetViewController: self, targetUrl: surveyUrl)
    }
  }
}
[Qualtrics.shared evaluateProjectWithCompletion:^(NSDictionary<NSString *, TargetingResult *>* targetingResults) {
    for (NSString* interceptID in targetingResults) {
      if ([result passed]) {
          [[Qualtrics shared] displayTargetWithTargetViewController:self targetUrl:[result getSurveyUrl]];
        }
    }


### evaluateProject

|Swift|
|---|
|public func evaluateProject(completion: @escaping ((_ targetingResults: [String: TargetingResult]) -> Void))|

|Objective-C|
|---|
|[Qualtrics.shared evaluateProjectWithCompletion:<#^(NSDictionary<NSString *,TargetingResult *> * _Nonnull)completion#>]|

This method asynchronously evaluates all Intercepts that have been initialized and calls the specified completion block with a dictionary of **TargetingResult** objects. The **TargetingResult** object indicates the result of the evaluation for each Intercept that has been initialized.

<!-- theme: info -->
>### Tip
>This method should be called asynchronously for best performance, usually done by wrapping the invocation in a DispatchGroup. Make sure that the evaluation resolves completely before `display` is invoked.

###### Example

<!--
title: Swift 
lineNumbers: true
-->
```swift
Qualtrics.shared.evaluateProject(completion: {(targetingResults) -> Void in
    DispatchQueue.main.async {
        for (interceptID, result) in targetingResults {
            if result.passed() {
                ...
            }
        }
    }
})
[Qualtrics.shared evaluateProjectWithCompletion:^(NSDictionary<NSString *,TargetingResult *>* targetingResults) {
        for (NSString* interceptID in targetingResults) {
            TargetingResult *result = targetingResults[interceptID];
            if ([result passed]) {
                [[Qualtrics shared] displayWithViewController:self];
            }
        }
    }];

evaluateIntercept​

Swift
[Qualtrics.shared evaluateInterceptFor:<#(NSString * _Nonnull)#> completion:<#^(TargetingResult * _Nonnull)completion#>]
Objective-C
public func evaluateIntercept(interceptID, completion: @escaping ((_ targetingResult: [String: TargetingResult]) -> Void))

This method asynchronously evaluates the given Intercept and calls the specified completion block with a TargetingResult object. The TargetingResult object indicates the result of the evaluation for the given Intercept.

Tip​

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

Example​
Qualtrics.shared.evaluateIntercept(for: "interceptId", completion: {(targetingResult) -> Void in
    DispatchQueue.main.async {
        if targetingResult.passed() {
            ...
        }
    }
})
[Qualtrics.shared evaluateInterceptFor:@"interceptID" completion:^(TargetingResult* targetingResult) {
        if ([targetingResult passed]) {
            [Qualtrics.shared displayWithViewController:self];
        }
    }];

evaluateTargetingLogicWithCompletion​

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

Swift
public func evaluateTargetingLogic(completion: @escaping ((Qualtrics.TargetingResult) -> Swift.Void))
Objective-C
- (void)evaluateTargetingLogicWithCompletion:(void (^ _Nonnull)(TargetingResult * _Nonnull))completion;

This method asynchronously evaluates the current Intercept and calls the specified completion block with a TargetingResult object. The TargetingResult object indicates the result of the evaluation through the passed property.

Example​
Qualtrics.shared.evaluateTargetingLogic { (result) in
    if(result.passed())
    {
        let displayed = Qualtrics.shared.display(currentView: self.view)
    }
}
[[Qualtrics shared] evaluateTargetingLogicWithCompletion:^(TargetingResult * _Nonnull result)
{
  if(result.passed)
  {
      BOOL displayResult = [[Qualtrics shared] displayWithCurrentView:self.view];
  }
}];

initializeProject​

Swift
public func initializeProject(brandId: String, projectId: String, extRefId: String?, completion: ((_ InitializationResult: [String: InitializationResult]) -> Void)? = nil )
Objective-C
- (void)initializeProjectWithBrandId:(NSString * _Nonnull)brandId projectId:(NSString * _Nonnull)projectId extRefId:(NSString * _Nullable)extRefId completion:(void (^ _Nullable)(NSDictionary<NSString *, InitializationResult *> * _Nonnull))completion

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.

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

Example​

func initializeQualtrics(brandId: String, projectId: String, <optional> extRefId: String) {
    Qualtrics.shared.initializeProject(brandId: brandId, projectId: projectId, extRefId: extRefId, completion: nil)
}
- (void)initializeQualtrics:(NSString * _Nonnull)brandId projectId:(NSString * _Nonnull)projectId extRefId:(NSString * _Nullable)extRefId;
{
    [Qualtrics.shared initializeProjectWithBrandId:@"brandID" projectId:@"projectID" extRefId:@"extRefID" completion:^(NSDictionary<NSString *,InitializationResult *>* initializationResults) {
        ...
    }];
}

Then, simply call the initializeQualtrics function you just defined in a DispatchQueue. Do this wherever you want to perform the initialization, typically in your application's view controller.

let appDelegate: AppDelegate = UIApplication.shared.delegate as! AppDelegate
DispatchQueue.global(qos: .background).async {
    appDelegate.initializeQualtrics(brandId: "BRAND_ID", projectId: "PROJECT_ID", extRefId: "EXT_REF_ID")
}
dispatch_queue_t myQueue = dispatch_queue_create(@"my_global_queue", DISPATCH_QUEUE_SERIAL);
dispatch_async(myQueue, ^{
  [Qualtrics.shared initializeQualtrics:@"brandID" projectId:@"projectID" extRefId:@"extRefID")];
});

getInitializedIntercepts​

Swift
public func getInitializedIntercepts() -> [String]
Objective-C
- (NSString * _Nullable)getInitializedIntercepts;

This method returns an array of interceptIDs for all the Intercepts in the project that have been successfully initialized (i.e. the Intercept is published and active). This list can be used to evaluate a specific Intercept.

Example​

let initializedIntercepts = Qualtrics.shared.getInitializedIntercepts()
for interceptID in initializedIntercepts {
    Qualtrics.shared.evaluateIntercept(for: interceptID, ...)
 }
[Qualtrics.shared getInitializedIntercepts]

getPassingIntercepts​

Swift
public func getPassingIntercepts() -> [String]
Objective-C
- (NSString * _Nullable)getPassingIntercepts;

This method returns an array of interceptIDs 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​

let passingIntercepts = Qualtrics.shared.getPassingIntercepts()
for intercept in passingIntercepts {
    Qualtrics.shared.displayIntercept(for: intercept, ...)
}
[Qualtrics.shared getPassingIntercepts];

getQualtricsContactId​

Swift
public func getQualtricsContactId(interceptId: String) -> [String]
Objective-C
- (NSString * _Nullable)getQualtricsContactId;

This method returns the contact id associated with the Intercept for the current XM directory contact if one is present, else it returns null.

Example​

let contactId = Qualtrics.shared.getQualtricsContactId(interceptId)
[Qualtrics.shared getQualtricsContactIdWithInterceptId(interceptId)];

initialize​

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

Swift
public func initialize(brandId: String, zoneId: String, interceptId: String, completion: ((Qualtrics.InitializationResult) -> Swift.Void)? = default)
Objective-C
- (void)initializeWithBrandId:(NSString * _Nonnull)brandId zoneId:(NSString * _Nonnull)zoneId interceptId:(NSString * _Nonnull)interceptId completion:(void (^ _Nullable)(InitializationResult * _Nonnull))completion;

This method initializes the Qualtrics singleton using the specified brand ID, project ID, Intercept ID and completion handler. You typically call this method in the app delegate's applicationDidBecomeActive method.

The method's InitializationResult (returned in the completion handler) indicates the state of initialization. See InitializationResult Class for more information.

Example​

func applicationDidBecomeActive(_ application: UIApplication) {

   Qualtrics.shared.initialize(brandId: "Brand ID", zoneId: "Project ID", interceptId: "Intercept ID") { (initializationResult) in
           // completion handler 
        }
}
- (void)applicationDidBecomeActive:(UIApplication *)application {
    
 [Qualtrics.shared initializeWithBrandId:@"Brand ID" zoneId:@"Project ID" interceptId:@"Intercept ID" completion:^(InitializationResult * initializationResult) {
        // completion handler code
    }];
}

registerViewVisitWithViewName​

Swift
public func registerViewVisit(viewName: String)
Objective-C
- (void)registerViewVisitWithViewName:(NSString * _Nonnull)viewName;

You can use this method to record visits to a particular view.

Example​
Qualtrics.shared.registerViewVisit(viewName: @"MainView")
[Qualtrics.shared registerViewVisitWithViewName:@"MainView"];

resetTimer​

Swift
public func resetTimer()
Objective-C
- (void)resetTimer;

This method resets the usage timer that is available to the Intercept on the server as Time Spent in App since the Qualtrics Initialisation.

resetViewCounter​

Swift
public func resetViewCounter()
Objective-C
- (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.

shared​

Swift
class var shared: Qualtrics { get }
Objective-C
- (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.

shared​

Returns the Qualtrics singleton object.

handleLocalNotificationWithResponse​

Swift
@available(iOS 10.0, *) public func handleLocalNotification(response: UNNotificationResponse, displayOn viewController: UIViewController) -> Bool

This method accepts the Notification Response, passes it to the SDK to process, and generates the webView to display the target. This must be called in UNUserNotificationCenterDelegate didReceive function.

Objective-C
[Qualtrics.shared handleLocalNotificationWithResponse:(UNNotificationResponse * _Nonnull) displayOn:(UIViewController * _Nonnull)];

This method accepts the Notification Response, passes it to the SDK to process, and generates the webView to display the target. This must be called in UNUserNotificationCenterDelegate didReceiveNotificationResponse function. Note: This API is used on iOS 10 and greater.

Example​

let _ = Qualtrics.shared.handleLocalNotification(response: response, displayOn: self.window!.rootViewController!)
[Qualtrics.shared handleLocalNotificationWithResponse:response displayOn:self.window.rootViewController];

handleLocalNotification​

Swift
public func handleLocalNotification(_ notification: UILocalNotification, displayOn viewController: UIViewController) -> Bool
Objective-C
[Qualtrics.shared handleLocalNotification:(UILocalNotification * _Nonnull) displayOn:(UIViewController * _Nonnull)];

This method accepts the Notification Response, passes it to the SDK to process, and generates the webView to display the target. This must be called in UNUserNotificationCenterDelegate didReceiveLocalNotification function. Note: This API is used on iOS 9.

This method accepts the Notification Response, passes it to the SDK to process, and generates the webView to display the target. This must be called in UNUserNotificationCenterDelegate willPresent function.

Example​

let _ = Qualtrics.shared.handleLocalNotification(notification, displayOn: self.window!.rootViewController!)
[Qualtrics.shared handleLocalNotification:notification displayOn:self.window.rootViewController];

setEmbeddedFeedbackDialogCloseListener​

Swift
public func setEmbeddedFeedbackDialogCloseListener(listener: (() -> Void)?)
Objective-C
public func setEmbeddedFeedbackDialogCloseListener(listner: @escaping (() -> Void))

This method accepts a callback 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.shared.setEmbeddedFeedbackDialogCloseListener(listener: {
    //Add your logic here.
})
[Qualtrics.shared setEmbeddedFeedbackDialogCloseListenerWithListener:^{
    //Add your logic here.
}];

setCreativeTheme​

@objc public func setCreativeTheme(to qualtricsTheme: QualtricsTheme)

Read more in Advanced theming capabilities on Android and iOS

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​

setString​

Swift
public func setString(string: String, for key: String)
Objective-C
- (void)setStringWithString:(NSString * _Nonnull)string for:(NSString * _Nonnull)key;

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.shared.properties.setString(string: "John", for: "firstName")
[Qualtrics.shared.properties setStringWithString:@"John" for:@"firstName"];

setNumber​

Swift
public func setNumber(number: Number, for key: String)
Objective-C
- (void)setNumberWithNumber:(double)string for:(NSString * _Nonnull)key;

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.shared.properties.setNumber(number: 25.0, for: "age")
[Qualtrics.shared.properties setNumberWithNumber:25.0 for:@"age"] ;

setDateTime​

Swift
public func setDateTime(for key: String)
Objective-C
- (void)setDateTimeFor:(NSString * _Nonnull)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.shared.properties.setDateTime(for: "propertyKey")
[[[Qualtrics shared] properties] setDateTimeFor:@"propertyKey"];

QualtricsSurveyViewController Class​

The QualtricsSurveyViewController class creates a new view controller and displays the survey from the URL when the view controller is initialized.

Method​

init​

Swift
public init(url: String)
Objective-C
- (nonnull instancetype)initWithUrl:(NSString * _Nonnull)url;

This method is the default initializer for this view controller. The URL is typically obtained from the getSurveyUrl method in the TargetingResult class.

InitializationResult Class​

The InitializationResult class encapsulates information about Qualtrics App Feedback initialization.

Methods​

getMessage​

Swift
public func getMessage() -> String?
Objective-C
- (NSString * _Nullable)getMessage;

Returns the initialization message. You can use this message to determine App Feedback SDK initialization status.

passed;​

Swift
public func passed() -> Bool
Objective-C
- (BOOL)passed;

Indicates whether initialization of the App Feedback SDK was successful.

TargetingResult Class​

Methods​

getError​

Swift
func getError() -> Qualtrics.TargetingResultError?
Objective-C
This method is not available in Objective C.

This method returns a TargetingResultError (a subclass of Error) if the Intercept failed to evaluate.

getSurveyUrl​

Swift
public func getSurveyUrl() -> String?
Objective-C
- (NSString * _Nullable)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 in a UIWebView instead of calling displayWithCurrentView.

Example​
Qualtrics.shared.evaluateProject { (results) in
  for (interceptID, result) in results {
    if result.passed() {
      let surveyURL = result.getSurveyUrl()
      print("Survey URL: \\(surveyURL!)")
    }
  }
}
[[Qualtrics shared] evaluateProjectWithCompletion:^(NSDictionary<NSString *,TargetingResult *>* targetingResults) {
  for (NSString* interceptID in targetingResults) {
    TargetingResult *result = targetingResults[interceptID];
    if ([result passed]) {
        NSString *survey = [result getSurveyUrl];
        NSLog(@"Survey URL: %@", survey);
    }
  }
}];

getTargetingResult​

Swift
public func getTargetingResult() -> Qualtrics.targetingResultStatus?
Objective-C
Not available

Returns the status of the targeting logic as a TargetingResultStatus value. See TargetingResultStatus Enum for more information.

passed​

Swift
public func passed() -> Bool
Objective-C
- (BOOL)passed;

This property indicates the state of the server-side evaluation of the Intercept. If it is YES (Objective-C) or true (Swift), the creative should be displayed.

Example​
Qualtrics.shared.evaluateIntercept(for: "interceptID", completion: { (result) in
    if(result.passed())
    {
        let displayed = Qualtrics.shared.display(currentView: self)
    }
})
[Qualtrics.shared evaluateInterceptFor:@"interceptID" completion: ^(TargetingResult * _Nonnull targetingResult) {
    if ([targetingResult passed]) {
        [Qualtrics.shared displayWithViewController:self];
    }
}];

recordClick​

Swift
public func recordClick()
Objective-C
- (void)recordClick;

This 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​

Swift
public func recordImpression()
Objective-C
- (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​

Swift
public func setLastDisplayedTime() -> Void {}
Objective-C
- (void)setLastDisplayedTime();

Sets the last displayed time of a TargetingResult to the current time this function is called. 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​
TargetingResult.setLastDisplayTime()
[TargetingResult setLastDisplayTime];

CreativeType Enum​

Values​

ValueMeaning
NotificationUsing the Mobile Notification Creative.
PopOverUsing the Mobile PopOver Creative.
EmbeddedFeedbackUsing the Mobile Embedded Feedback Creative.
Example​
Qualtrics.shared.evaluateIntercept(for: "interceptId", completion: {(targetingResult) -> Void in
    DispatchQueue.main.async {
        if targetingResult.getCreativeType() == CreativeType.PopOver {
            ...
        }
    }
})

TargetingResultStatus Enum​

The TargetingResultStatus enum returns a status in the TargetingResult returned from the evaluateTargetingLogicWithCompletion method. It is accesed using the TargetingResult.getTargetingResult method.

Not Available in Objective-C​

This enum and the getTargetingResult method are not available in Objective C.

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.