Skip to main content

Migration Guide from Mobile App SDK v2

Qualtrics has released our new Experience SDK, allowing you the ability to curate exactly when to engage with your customers, launch new intercepts easier, and provide more streamlined features and functionalities. As you move from our v2 SDK to the Experience SDK, Qualtrics is committed to making the migration as effortless as possible. Below provides guidance on the migration for your teams.

What's New?​

The Experience SDK follows a different model than Mobile App SDK v2. In v2 it was required to call evaluateProject(), evaluateIntercept(), and displayIntercept() directly. In the Experience SDK, most display logic is configured in App Insights through targeting and sequencing, while the SDK handles evaluation and display automatically. Our investments in this step-up will create an easier long-term management of the SDK. Intercepts will now be created and updated directly on the Qualtrics platform, no longer requiring changes in code for updates/shifts.

Summary of key changes​

Mobile App SDK v2Experience SDK
initializeProject(...)Remove the old call. Use Automatic Initialization by default, or Manual Initialization if you need to control when the SDK starts. Qualtrics recommends you use our automatic initialization capabilities.
evaluateProject() or evaluateIntercept()Replace the evaluation based on the use case. For user actions, call reportEvent(...). For screen-based flows, use Screen Name Auto Capture or Manual Screen Changes for every screen you want to use in sequencing, then configure Sequencing.
displayIntercept()Remove it. The Experience SDK handles display automatically when the configured sequencing and targeting conditions are met.
Custom properties and Embedded Data valuesCreate Custom Properties in App Insights, then set them in code with setStringProperty(...), setBoolProperty(...), setNumberProperty(...), or setDateProperty(...). Use Embedded Data when those values should be sent with intercept responses.
Theme objects and setCreativeTheme(...)Configure Native App Feedback colors in Look & Feel in App Insights. There is no replacement theming API in the Experience SDK. See Migrate Theming below.

Migrate initializeProject(...)​

In Mobile App SDK v2, initialization used brand and project identifiers. When migrating to the Experience SDK, remove the old initializeProject(...) call. The standard Experience SDK setup uses an SDK Key and Automatic Initialization.

Use Automatic Initialization as the default setup unless you need to initialize at a specific moment in the app lifecycle or choose the project at runtime. If you need that level of control, follow Manual Initialization.

Migrate Evaluation Calls​

In Mobile App SDK v2, many integrations were using evaluateProject() or evaluateIntercept() from a specific place in the app, then called displayIntercept() if the evaluation passed.

In the Experience SDK, this should be migrated based on what the code was trying to represent:

  • If the evaluation represented a user action, replace it with reportEvent(...).
  • If the evaluation represented a screen being shown, replace it with screen-based sequencing.
info

displayIntercept() no longer exists in the Experience SDK. Remove the call. The SDK handles display automatically when the configured sequence is met.

Use case: evaluation after a button tap or user action​

If your v2 code evaluated an intercept after a specific user action, such as tapping a checkout button, submitting a form, completing onboarding, or finishing a purchase, replace that evaluation call with reportEvent(...).

info

Add reportEvent(...) to every relevant button or user action that you want to use in App Insights sequencing.

For example:

// Mobile App SDK v2
Qualtrics.instance().evaluateIntercept("CHECKOUT_INTERCEPT_ID", callback)

// Experience SDK
Qualtrics.reportEvent("checkout_started")

Then configure Sequencing in App Insights to react to the checkout_started custom event.

Use case: evaluation when a screen appears​

If your v2 code evaluated an intercept when a screen appeared, remove the evaluation call and configure the automatically captured screen name in Sequencing.

For example:

// Mobile App SDK v2
Qualtrics.instance().evaluateIntercept("SETTINGS_INTERCEPT_ID", callback)

// Experience SDK
// No direct replacement call is needed if the screen is captured automatically.
// Use the captured screen name in App Insights sequencing.

Use Screen Name Auto Capture where it is supported:

  • iOS: UIViewController-based navigation and SwiftUI
  • Android: Activities, Fragments, NavControllers, and Compose Navigation
  • React Native: React Navigation 5.0.0 or later

If automatic screen capture is not available for your app stack, use Manual Screen Changes.

info

Report screen appearance and disappearance for every relevant screen. Only screens that are reported by the SDK will be available for App Insights sequencing.

Migrate Custom Properties​

info

Experience SDK adds Boolean and Date custom properties. See Custom Properties for examples and API Reference for method definitions.

Custom properties in the Experience SDK must first be configured in App Insights, and then set in your app code.

If your Mobile App SDK v2 integration used legacy property setters, replace them with the new Experience SDK methods:

Mobile App SDK v2:

import Qualtrics

Qualtrics.shared.properties.setString(string: "John", for: "firstName")
Qualtrics.shared.properties.setNumber(number: 25.0, for: "age")
Qualtrics.shared.properties.setDateTime(for: "currentDate")

Experience SDK:

import QualtricsExperience

Qualtrics.setStringProperty(key: "firstName", value: "John")
Qualtrics.setNumberProperty(key: "age", value: 25.0)
Qualtrics.setDateProperty(key: "currentDate", value: Date())
Qualtrics.setBoolProperty(key: "isTrialPeriod", value: true)

If you want a custom property to be sent with intercept responses and available for reporting, you must also configure it as Embedded Data.

Migrate Theming​

Mobile App SDK v2 allowed Android and iOS apps to construct theme objects from app resources and apply them with setCreativeTheme(...). The Experience SDK does not provide a public replacement for this API. Instead, configure Native App Feedback colors in Look & Feel in your App Insights Project.

To migrate a v2 theme:

  1. Open the Native App Feedback intercept in your App Insights Project and select Look & Feel.
  2. Use the existing v2 light and dark themes as a visual reference when configuring the Light and Dark appearances.
  3. Use the preview to review every page and supported Native App Feedback question type. There is no one-to-one mapping between v2 theme properties and Look & Feel colors because their use can vary by question type.
  4. Publish the intercept.
  5. Once all v2 intercepts are migrated, remove the old theme objects and the setCreativeTheme(...) call. Delete any theme resources your app no longer uses.
info

Look & Feel currently supports colors only. Font customization is planned in one of the future releases. Until then, font overrides from Mobile App SDK v2 have no equivalent in the Experience SDK.

warning

If your app still uses Mobile App SDK v2 for any intercepts, keep the v2 theme code and resources until those intercepts have been migrated.

For the complete list of configurable colors, see Theming.

For Advanced Legacy Integrations​

Some integrations are more advanced than the standard Experience SDK flow described above. Please review our documentation to see new ways you can cover existing use cases. If your use case is not covered by this guide, describe it in this survey so we can improve the migration guidance:

Migration use case survey