Usercentrics · uc-brunosilva · Aug 25, 2026 · Aug 25, 2026
diff --git a/android/src/main/kotlin/com/usercentrics/sdk/flutter/serializer/OptionsSerializer.kt b/android/src/main/kotlin/com/usercentrics/sdk/flutter/serializer/OptionsSerializer.kt
@@ -35,6 +35,9 @@ internal fun Any?.deserializeOptions(): UsercentricsOptions {
     this["initTimeoutMillis"]?.let {
         options.initTimeoutMillis = (it as Int).toLong()
     }
+    this["controllerId"]?.let {
+        options.controllerId = it as String
+    }
     this["bannerCustomization"]?.let {
         options.bannerCustomization = it.deserializeBannerInitCustomization()
     }

diff --git a/android/src/test/java/com/usercentrics/sdk/flutter/bridge/InitializeBridgeUnitTest.kt b/android/src/test/java/com/usercentrics/sdk/flutter/bridge/InitializeBridgeUnitTest.kt
@@ -81,6 +81,10 @@ class InitializeBridgeUnitTest {
             InitializeMock.callWithDataInitTimeoutMillis,
             usercentricsProxy.initializeOptionsArgument?.initTimeoutMillis
         )
+        assertEquals(
+            InitializeMock.callWithDataControllerId,
+            usercentricsProxy.initializeOptionsArgument?.controllerId
+        )
         assertEquals(1, result.successCount)
         assertEquals(InitializeMock.expected, result.successResultArgument)
     }
@@ -118,6 +122,10 @@ class InitializeBridgeUnitTest {
             defaultOptions.networkMode,
             usercentricsProxy.initializeOptionsArgument?.networkMode
         )
+        assertEquals(
+            defaultOptions.controllerId,
+            usercentricsProxy.initializeOptionsArgument?.controllerId
+        )
         assertEquals(1, result.successCount)
         assertEquals(InitializeMock.expected, result.successResultArgument)
     }

diff --git a/android/src/test/java/com/usercentrics/sdk/flutter/mock/InitializeMock.kt b/android/src/test/java/com/usercentrics/sdk/flutter/mock/InitializeMock.kt
@@ -18,6 +18,7 @@ internal object InitializeMock {
             "version" to "1.2.3",
             "networkMode" to "EU",
             "initTimeoutMillis" to 1500,
+            "controllerId" to "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
         )
     )
     val callWithDataSettingsId = "AAAAA"
@@ -28,6 +29,7 @@ internal object InitializeMock {
     val callWithDataVersion = "1.2.3"
     val callWithDataNetworkMode = NetworkMode.EU
     val callWithDataInitTimeoutMillis = 1500L
+    val callWithDataControllerId = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
     val callWithoutData = FakeFlutterMethodCall(
         method = "initialize",
         arguments = mapOf(

diff --git a/example/test/fake_usercentrics.dart b/example/test/fake_usercentrics.dart
@@ -18,6 +18,7 @@ class FakeUsercentrics extends UsercentricsPlatform {
     NetworkMode? networkMode,
     bool? consentMediation,
     int? initTimeoutMillis,
+    String? controllerId,
     // ignore: deprecated_member_use
     BannerInitCustomization? bannerCustomization,
   }) {

diff --git a/ios/usercentrics_sdk/Sources/usercentrics_sdk/Serializer/InitializeOptionsSerializer.swift b/ios/usercentrics_sdk/Sources/usercentrics_sdk/Serializer/InitializeOptionsSerializer.swift
@@ -44,6 +44,10 @@ extension UsercentricsOptions {
             options.initTimeoutMillis = Int64(initTimeoutMillis)
         }
 
+        if let controllerId = dict["controllerId"] as? String {
+            options.controllerId = controllerId
+        }
+
         if let consentMediation = dict["consentMediation"] as? Bool {
             options.consentMediation = consentMediation
         }

diff --git a/lib/src/internal/bridge/initialize_bridge.dart b/lib/src/internal/bridge/initialize_bridge.dart
@@ -18,6 +18,7 @@ abstract class InitializeBridge {
     NetworkMode? networkMode,
     bool? consentMediation,
     int? initTimeoutMillis,
+    String? controllerId,
     // ignore: deprecated_member_use_from_same_package
     BannerInitCustomization? bannerCustomization,
   });
@@ -40,6 +41,7 @@ class MethodChannelInitialize extends InitializeBridge {
     NetworkMode? networkMode,
     bool? consentMediation,
     int? initTimeoutMillis,
+    String? controllerId,
     // ignore: deprecated_member_use_from_same_package
     BannerInitCustomization? bannerCustomization,
   }) {
@@ -53,6 +55,7 @@ class MethodChannelInitialize extends InitializeBridge {
       networkMode: networkMode,
       consentMediation: consentMediation,
       initTimeoutMillis: initTimeoutMillis,
+      controllerId: controllerId,
       bannerCustomization: bannerCustomization,
     );
     channel.invokeMethod(_name, arguments);

diff --git a/lib/src/internal/platform/method_channel_usercentrics.dart b/lib/src/internal/platform/method_channel_usercentrics.dart
@@ -88,6 +88,7 @@ class MethodChannelUsercentrics extends UsercentricsPlatform {
     NetworkMode? networkMode,
     bool? consentMediation,
     int? initTimeoutMillis,
+    String? controllerId,
     // ignore: deprecated_member_use_from_same_package
     BannerInitCustomization? bannerCustomization,
   }) async {
@@ -116,6 +117,7 @@ class MethodChannelUsercentrics extends UsercentricsPlatform {
           networkMode: networkMode,
           consentMediation: consentMediation,
           initTimeoutMillis: initTimeoutMillis,
+          controllerId: controllerId,
           bannerCustomization: bannerCustomization);
 
       await status.then((value) => isReadyCompleter?.complete(null));

diff --git a/lib/src/internal/serializer/initialize_options_serializer.dart b/lib/src/internal/serializer/initialize_options_serializer.dart
@@ -17,6 +17,7 @@ class InitializeOptionsSerializer {
     NetworkMode? networkMode,
     bool? consentMediation,
     int? initTimeoutMillis,
+    String? controllerId,
     // ignore: deprecated_member_use_from_same_package
     BannerInitCustomization? bannerCustomization,
   }) =>
@@ -30,6 +31,7 @@ class InitializeOptionsSerializer {
         'networkMode': NetworkModeSerializer.serialize(networkMode),
         'consentMediation': consentMediation,
         'initTimeoutMillis': initTimeoutMillis,
+        'controllerId': controllerId,
         'bannerCustomization': BannerInitCustomizationSerializer.serialize(
           bannerCustomization,
         ),

diff --git a/lib/src/platform/usercentrics_platform.dart b/lib/src/platform/usercentrics_platform.dart
@@ -16,6 +16,7 @@ abstract class UsercentricsPlatform {
     NetworkMode? networkMode,
     bool? consentMediation,
     int? initTimeoutMillis,
+    String? controllerId,
     // ignore: deprecated_member_use_from_same_package
     BannerInitCustomization? bannerCustomization,
   });

diff --git a/lib/src/usercentrics.dart b/lib/src/usercentrics.dart
@@ -27,6 +27,14 @@ class Usercentrics {
   /// - The [networkMode] sets the network operation mode. Be careful, use this option only if we have confirmed that it is ready to use because it has a significant impact on the whole system's performance. The default value is "world".
   /// - The [consentMediation] enables the feature of consent mediation, this feature works with a set of selected SDKs that you can find in the documentation.
   /// - The [initTimeoutMillis] sets a timeout for the SDK to initialize. Minimum value is 5000ms. The default value is 10000ms.
+  /// - The [controllerId] can be used to inject a previously-issued controllerID at SDK
+  /// initialisation. Use this to preserve user identity across login/logout flows that clear
+  /// local consent storage. Store the controllerId server-side after the first successful init,
+  /// then pass it here on every subsequent login. The SDK will skip generating a new ID and use
+  /// this value instead. It is persisted to local storage, so subsequent re-initialisations
+  /// without this option continue to use it. The value must be a 64-character lowercase
+  /// hexadecimal string (the format produced internally by the SDK). Invalid values are ignored
+  /// with a warning log and the SDK falls back to its normal ID resolution (stored → generated).
   /// - The [bannerCustomization] enables further programmatic customization of the predefined Banner UI, applied at init-time.
   /// **Deprecated:** [bannerCustomization] is deprecated and will be removed in a future release. Configure banner appearance via the Usercentrics dashboard instead.
   static void initialize({
@@ -39,6 +47,7 @@ class Usercentrics {
     NetworkMode? networkMode,
     bool? consentMediation,
     int? initTimeoutMillis,
+    String? controllerId,
     @Deprecated(
         'BannerInitCustomization is deprecated and will be removed in a future release. Configure banner appearance via the Usercentrics dashboard instead.')
     BannerInitCustomization? bannerCustomization,
@@ -53,6 +62,7 @@ class Usercentrics {
           networkMode: networkMode,
           consentMediation: consentMediation,
           initTimeoutMillis: initTimeoutMillis,
+          controllerId: controllerId,
           // ignore: deprecated_member_use_from_same_package
           bannerCustomization: bannerCustomization);
 

diff --git a/test/internal/bridge/fake_initialize_bridge.dart b/test/internal/bridge/fake_initialize_bridge.dart
@@ -16,6 +16,7 @@ class FakeInitializeBridge extends InitializeBridge {
   NetworkMode? invokeNetworkModeArgument;
   bool? invokeConsentMediationArgument;
   int? invokeInitTimeoutMillisArgument;
+  String? invokeControllerIdArgument;
   // ignore: deprecated_member_use_from_same_package
   BannerInitCustomization? invokeBannerCustomizationArgument;
 
@@ -31,6 +32,7 @@ class FakeInitializeBridge extends InitializeBridge {
     NetworkMode? networkMode,
     bool? consentMediation,
     int? initTimeoutMillis,
+    String? controllerId,
     // ignore: deprecated_member_use_from_same_package
     BannerInitCustomization? bannerCustomization,
   }) {
@@ -45,6 +47,7 @@ class FakeInitializeBridge extends InitializeBridge {
     invokeNetworkModeArgument = networkMode;
     invokeConsentMediationArgument = consentMediation;
     invokeInitTimeoutMillisArgument = initTimeoutMillis;
+    invokeControllerIdArgument = controllerId;
     invokeBannerCustomizationArgument = bannerCustomization;
   }
 }
diff --git a/test/internal/bridge/initialize_bridge_test.dart b/test/internal/bridge/initialize_bridge_test.dart
@@ -18,6 +18,8 @@ void main() {
     "networkMode": "EU",
     'consentMediation': true,
     "initTimeoutMillis": 25000,
+    "controllerId":
+        "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
     "bannerCustomization": {
       'paddingTop': 16,
       'paddingBottom': null,
@@ -55,6 +57,8 @@ void main() {
   const mockDefaultLanguage = "en";
   const mockTimeoutMillis = 20000;
   const mockInitTimeoutMillis = 25000;
+  const mockControllerId =
+      "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
   const mockNetworkMode = NetworkMode.eu;
   const mockConsentMediation = true;
   // ignore: deprecated_member_use_from_same_package
@@ -94,6 +98,7 @@ void main() {
         networkMode: mockNetworkMode,
         consentMediation: mockConsentMediation,
         initTimeoutMillis: mockInitTimeoutMillis,
+        controllerId: mockControllerId,
         // ignore: deprecated_member_use
         bannerCustomization: mockBannerCustomization);
 

diff --git a/test/internal/platform/method_channel_usercentrics_test.dart b/test/internal/platform/method_channel_usercentrics_test.dart
@@ -51,6 +51,8 @@ void main() {
       const networkMode = NetworkMode.eu;
       const consentMediation = true;
       const initTimeoutMillis = 7000;
+      const controllerId =
+          "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
 
       instance.initialize(
           settingsId: settingsId,
@@ -61,7 +63,8 @@ void main() {
           version: version,
           networkMode: networkMode,
           consentMediation: consentMediation,
-          initTimeoutMillis: initTimeoutMillis);
+          initTimeoutMillis: initTimeoutMillis,
+          controllerId: controllerId);
       await instance.isReadyCompleter?.future;
 
       expect(initializeBridge.invokeCount, 1);
@@ -76,6 +79,7 @@ void main() {
       expect(initializeBridge.invokeConsentMediationArgument, consentMediation);
       expect(
           initializeBridge.invokeInitTimeoutMillisArgument, initTimeoutMillis);
+      expect(initializeBridge.invokeControllerIdArgument, controllerId);
 
       expect(isReadyBridge.invokeCount, 1);
       expect(isReadyBridge.invokeChannelArgument?.name, "usercentrics");

diff --git a/test/platform/fake_usercentrics_platform.dart b/test/platform/fake_usercentrics_platform.dart
@@ -71,6 +71,7 @@ class FakeUsercentricsPlatform extends UsercentricsPlatform {
   NetworkMode? networkModeArgument;
   bool? consentMediationArgument;
   int? initializeInitTimeoutMillisArgument;
+  String? initializeControllerIdArgument;
   // ignore: deprecated_member_use_from_same_package
   BannerInitCustomization? initializeBannerCustomizationArgument;
 
@@ -85,6 +86,7 @@ class FakeUsercentricsPlatform extends UsercentricsPlatform {
     NetworkMode? networkMode,
     bool? consentMediation,
     int? initTimeoutMillis,
+    String? controllerId,
     // ignore: deprecated_member_use_from_same_package
     BannerInitCustomization? bannerCustomization,
   }) {
@@ -98,6 +100,7 @@ class FakeUsercentricsPlatform extends UsercentricsPlatform {
     networkModeArgument = networkMode;
     consentMediationArgument = consentMediation;
     initializeInitTimeoutMillisArgument = initTimeoutMillis;
+    initializeControllerIdArgument = controllerId;
     initializeBannerCustomizationArgument = bannerCustomization;
   }