Skip to content

Upgrading from Legacy? (v1.12.7 or lower)

Hello again!

We are happy that you are interested in upgrading to v2. We've kept you in mind during this transition, and have created this migration guide to give you transparency on all the changes we've made, and make it as simple as possible for you to upgrade 🚀.

We are very exited for you to see all the improvements we have been working on, and are always open for feedback.

If you are currently using a legacy version, and have upgraded to v2, you will see several compilation errors. This is to be expected. We have been working hard to simplify our API and reduce complexity, which means we had to break a couple of things.💥

With v2.6.1 we are now offering a much more robust and easy to integrate API, so that you can spend less time implementing a CMP, and more time on the things that matter to you. 💪

Here is an overview of the main changes:

☝️ SDK Singleton

Forget about initializing instances everywhere. Just initialize the SDK with your SettingsID once. We recommend doing so immediately after app launch, as you probably already do for other SDKs. e.g. In your AppDelegate/Application or Manager class.

// Legacy
// View Controller or Manager
let userOptions = UserOptions(controllerId: nil, defaultLanguage: "en", version: nil, predefinedUI: true, timeoutMillis: nil, noCache:false, loggerLevel: .none)
let usercentrics = Usercentrics(settingsId: <SettingsID>, options: userOptions)

// -- vs --

// v2.6.1
// App Delegate or Manager
let options: UsercentricsOptions = UsercentricsOptions(settingsId: <SettingsID>)
options.loggerLevel = .debug // Advance options
UsercentricsCore.configure(options: options)

// Legacy
// Activity or Manager
val userOptions = UserOptions(predefinedUI = true)
val usercentrics = Usercentrics(settingsId = <SettingsID>, options = userOptions)

// -- vs --

// v2.6.1
// Application or Manager
val options: UsercentricsOptions = UsercentricsOptions(settingsId = <SettingsID>)
Usercentrics.initialize(context = this, options = options)

Resetting the SDK

Initializing the SDK twice will lead to a crash. If you need to reset the configuration, please use UsercentricsCore.reset(). This will clean all memory storage and release the initialized instance. You may initialize the SDK again after this. We provided this method mostly for testing reasons and some special use cases. Please make sure you know what you are doing when using it on production.

For more information, see Configure the SDK and Initialize the SDK.

🤷‍♀️ To show or not to show

To know if you should show the CMP or not, is now way simpler. You don't need to initialize the SDK again nor evaluate enums. You can now know this directly with the response of isReady.

// Legacy
let usercentrics = Usercentrics(settingsId: <SettingsID>, options: <UserOptions>)
usercentrics.initialize { initialValues in
    switch initialView.initialLayer {
    case .firstLayer:
        // Show CMP
    case .none:
        // Apply stored consent (Don't show CMP)
    }
} onFailure: { error in
    // Handle non-localized error
}

// -- vs --

// v2.6.1
UsercentricsCore.isReady { status in
    if status.shouldCollectConsent {
        // Show CMP
    } else {
        // Apply stored consent (Don't show CMP)
    }
} onFailure: { error in
    // Handle non-localized error
}

// Legacy
val usercentrics = Usercentrics(settingsId = <SettingsID>, options = <UserOptions>)
usercentrics.initialize(
    callback = { initialValues ->
        when (initialValues.initialLayer) {
            InitialView.FIRST_LAYER -> // Show CMP
            InitialView.NONE -> // Apply stored consent (Don't show CMP)
        }
    }, onFailure = { error ->
        // Handle non-localized error
    }
)

// -- vs --

// v2.6.1
Usercentrics.isReady({ status ->
    if (status.shouldCollectConsent) {
        // Show CMP
    } else {
        // Apply stored consent (Don't show CMP)
    }
},{ error ->
    // Handle non-localized error
})

For more information, see Initialize the SDK.

🧠 Smarter UI

Using the Usercentrics UI is now easier than ever, no more userOptions flag, less callbacks, no need to handle "dismiss" and with the user's response ready to apply.

// Legacy
let userOptions = UserOptions(..., predefinedUI: true, ...)

var predefinedUI: UIViewController?
predefinedUI = usercentrics?.getPredefinedUI(settings: nil) {
    // Dismiss UI
    self.predefinedUI?.dismiss(animated: true, completion: nil)
}

// Present UI
guard let ui = self.predefinedUI else { return }
self.navigationController?.present(ui, animated: true, completion: nil)

// -- vs --

// v2.6.1
let banner = UsercentricsBanner()
banner.showFirstLayer(hostView: self,
                        layout: .sheet) { userResponse in
    // UserResponse provides:

    // consents: [UsercentricsServiceConsent]
    self.applyConsent(with: userResponse.consents) // Apply Consent 

    // userInteraction: Enum (.acceptAll, .denyAll, .granular & .noInteraction)
    self.handleUserInteraction(with: userResponse.userInteraction) // Use for user flow decisions, Analytics or A/B Testing

    // controllerID: String
    self.store(userResponse.controllerID) // Remotely store ControllerID, only if you are using the Cross-Device feature.
}

// Legacy
val userOptions = UserOptions(..., predefinedUI = true, ...)

var predefinedUI: View? = null
predefinedUI = usercentrics.getPredefinedUI(viewContext = myActivity) {
    // Dismiss UI
    layout.removeView(this.predefinedUI)
    predefinedUI = null
}

// Present UI
layout.addView(predefinedUI)

// -- vs --

// v2.6.1

val banner = UsercentricsBanner(this)
banner.showFirstLayer(layout) { userResponse ->
    // UserResponse provides:

    // consents: [UsercentricsServiceConsent]
    applyConsent(userResponse.consents) // Apply Consent 

    // userInteraction: Enum
    handleUserInteraction(userResponse.userInteraction) // Use for user flow decisions, Analytics or A/B Testing

    // controllerID: String
    store(userResponse.controllerID) // Remotely store ControllerID, only if you are using the Cross-Device feature.
}

Wait for 'isReady'

When presenting the UsercentircsUI, always make sure you do so in the isReady callback, which indicates the initialization of the SDK has been successful.

For more information, see Presenting the CMP.

👷‍♂️ Build your own UI

If you have built your own UI using our SDK as a data source. You will now find everything you need way easier.

// Legacy
guard let settings: UCSettings? = usercentrics.getSettings(),
let categories: [UCCategory]? = usercentrics.getCategories(),
let services: [UCService]? = usercentrics.getServices() else { return }

// -- vs --

// v2.6.1
let data = UsercentricsCore.shared.getCMPData()
let settings = data.settings
let services = data.services
let categories = data.categories

// Legacy
val settings = usercentrics.getSettings()
val categories = usercentrics.getCategories()
val services = usercentrics.getServices()

// -- vs --

// v2.6.1
val data = Usercentrics.instance.getCMPData()
val settings = data.settings
val services = data.services
val categories = data.categories

Wait for 'isReady'

When presenting the UsercentircsUI, always make sure you do so in the isReady callback, which indicates the initialization of the SDK has been successful.

For more information, see Build your own UI.