@kontextso/sdk-react-native 3.3.0 → 3.4.0-rc.0

package/android/build.gradle

@@ -86,4 +86,5 @@ dependencies {
   implementation "com.facebook.react:react-android"
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
   implementation "androidx.preference:preference:1.2.1"
+  implementation "com.google.android.gms:play-services-ads-identifier:18.0.1"
 }

package/android/src/main/AndroidManifest.xml

@@ -1,2 +1,3 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
-</manifest>
+    <uses-permission android:name="com.google.android.gms.permission.AD_ID" />
+</manifest>

package/android/src/main/java/so/kontext/react/RNKontextModuleImpl.kt

@@ -1,16 +1,50 @@
 package so.kontext.react
 
 import android.content.Context
+import android.os.Handler
+import android.os.Looper
 import android.media.AudioManager
 import androidx.preference.PreferenceManager
 import com.facebook.react.bridge.Arguments
 import com.facebook.react.bridge.Promise
 import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.bridge.WritableMap
+import com.google.android.gms.ads.identifier.AdvertisingIdClient
+import java.util.concurrent.Executors
 
 
 class RNKontextModuleImpl(private val reactContext: ReactApplicationContext) {
 
+  private val mainHandler = Handler(Looper.getMainLooper())
+  private val executor = Executors.newSingleThreadExecutor()
+
+  fun getAdvertisingId(promise: Promise?) {
+    if (promise == null) return
+    executor.execute {
+      val id = try {
+          val info = AdvertisingIdClient.getAdvertisingIdInfo(reactContext.applicationContext)
+          if (info.isLimitAdTrackingEnabled) null else info.id
+      } catch (_: Exception) {
+          null
+      }
+      mainHandler.post { promise.resolve(id) }
+    }
+  }
+
+  // Android has no IDFV equivalent — iOS only
+  fun getVendorId(promise: Promise?) {
+    promise?.resolve(null)
+  }
+
+  // Android has no ATT — iOS only
+  fun getTrackingAuthorizationStatus(promise: Promise?) {
+    promise?.resolve(4) // TrackingStatus.NotSupported
+  }
+
+  fun requestTrackingAuthorization(promise: Promise?) {
+    promise?.resolve(4) // TrackingStatus.NotSupported
+  }
+
   fun isSoundOn(promise: Promise?) {
     val audioManager = reactContext.getSystemService(Context.AUDIO_SERVICE) as AudioManager
     val current = audioManager.getStreamVolume(AudioManager.STREAM_MUSIC)

package/android/src/newarch/java/so/kontext/react/RNKontextModule.kt

@@ -12,6 +12,22 @@ class RNKontextModule(reactContext: ReactApplicationContext) :
 
   override fun getName(): String = NAME
 
+  override fun getAdvertisingId(promise: Promise?) {
+    impl.getAdvertisingId(promise)
+  }
+
+  override fun getVendorId(promise: Promise?) {
+    impl.getVendorId(promise)
+  }
+
+  override fun getTrackingAuthorizationStatus(promise: Promise?) {
+    impl.getTrackingAuthorizationStatus(promise)
+  }
+
+  override fun requestTrackingAuthorization(promise: Promise?) {
+    impl.requestTrackingAuthorization(promise)
+  }
+
   override fun isSoundOn(promise: Promise?) {
     impl.isSoundOn(promise)
   }

package/android/src/oldarch/java/so/kontext/react/RNKontextModule.kt

@@ -14,6 +14,26 @@ class RNKontextModule(reactContext: ReactApplicationContext) :
 
   override fun getName(): String = NAME
 
+  @ReactMethod
+  fun getAdvertisingId(promise: Promise?) {
+      impl.getAdvertisingId(promise)
+  }
+
+  @ReactMethod
+  fun getVendorId(promise: Promise?) {
+      impl.getVendorId(promise)
+  }
+
+  @ReactMethod
+  fun getTrackingAuthorizationStatus(promise: Promise?) {
+      impl.getTrackingAuthorizationStatus(promise)
+  }
+
+  @ReactMethod
+  fun requestTrackingAuthorization(promise: Promise?) {
+      impl.requestTrackingAuthorization(promise)
+  }
+
   @ReactMethod
   fun isSoundOn(promise: Promise?) {
     impl.isSoundOn(promise)

package/dist/index.js

@@ -57,14 +57,16 @@ function handleIframeMessage(handler, opts) {
 // src/formats/Format.tsx
 var import_sdk_react = require("@kontextso/sdk-react");
 var import_react2 = require("react");
-var import_react_native4 = require("react-native");
+var import_react_native5 = require("react-native");
 
 // src/frame-webview.tsx
 var import_react = require("react");
+var import_react_native = require("react-native");
 var import_react_native_webview = require("react-native-webview");
 var import_jsx_runtime = require("react/jsx-runtime");
 var FrameWebView = (0, import_react.forwardRef)(
   ({ iframeUrl, onMessage, style, onError, onLoad }, forwardedRef) => {
+    const isLoadedRef = (0, import_react.useRef)(false);
     return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
       import_react_native_webview.WebView,
       {
@@ -89,9 +91,25 @@ var FrameWebView = (0, import_react.forwardRef)(
               window.ReactNativeWebView.postMessage(JSON.stringify(event.data));
             }
           }, false);
+
       `,
-        onError,
-        onLoad
+        onError: (event) => onError(
+          new Error(`${event.nativeEvent.title}: ${event.nativeEvent.description} [${event.nativeEvent.url}]`),
+          true
+        ),
+        onLoad: () => {
+          isLoadedRef.current = true;
+          onLoad();
+        },
+        onShouldStartLoadWithRequest: (request) => {
+          if (!isLoadedRef.current || request.url.match(/^about:/) || request.url.startsWith(iframeUrl)) {
+            return true;
+          }
+          import_react_native.Linking.openURL(request.url).catch((err) => {
+            onError(new Error(`Failed to open URL: ${request.url} [${err.message}]`));
+          });
+          return false;
+        }
       }
     );
   }
@@ -99,11 +117,11 @@ var FrameWebView = (0, import_react.forwardRef)(
 var frame_webview_default = FrameWebView;
 
 // src/services/SkOverlay.ts
-var import_react_native2 = require("react-native");
+var import_react_native3 = require("react-native");
 
 // src/NativeRNKontext.ts
-var import_react_native = require("react-native");
-var NativeRNKontext_default = import_react_native.TurboModuleRegistry.getEnforcing("RNKontext");
+var import_react_native2 = require("react-native");
+var NativeRNKontext_default = import_react_native2.TurboModuleRegistry.getEnforcing("RNKontext");
 
 // src/services/utils.ts
 var isValidAppStoreId = (id) => {
@@ -115,7 +133,7 @@ var isValidPosition = (p) => {
   return p === "bottom" || p === "bottomRaised";
 };
 async function presentSKOverlay(params) {
-  if (import_react_native2.Platform.OS !== "ios") {
+  if (import_react_native3.Platform.OS !== "ios") {
     return false;
   }
   let { appStoreId, position, dismissible } = params;
@@ -131,16 +149,16 @@ async function presentSKOverlay(params) {
   return NativeRNKontext_default.presentSKOverlay(appStoreId, position, dismissible);
 }
 async function dismissSKOverlay() {
-  if (import_react_native2.Platform.OS !== "ios") {
+  if (import_react_native3.Platform.OS !== "ios") {
     return false;
   }
   return NativeRNKontext_default.dismissSKOverlay();
 }
 
 // src/services/SkStoreProduct.ts
-var import_react_native3 = require("react-native");
+var import_react_native4 = require("react-native");
 async function presentSKStoreProduct(appStoreId) {
-  if (import_react_native3.Platform.OS !== "ios") {
+  if (import_react_native4.Platform.OS !== "ios") {
     return false;
   }
   if (!isValidAppStoreId(appStoreId)) {
@@ -149,7 +167,7 @@ async function presentSKStoreProduct(appStoreId) {
   return NativeRNKontext_default.presentSKStoreProduct(appStoreId);
 }
 async function dismissSKStoreProduct() {
-  if (import_react_native3.Platform.OS !== "ios") {
+  if (import_react_native4.Platform.OS !== "ios") {
     return false;
   }
   return NativeRNKontext_default.dismissSKStoreProduct();
@@ -194,7 +212,7 @@ var Format = ({ code, messageId, wrapper, onEvent, ...otherParams }) => {
   const messageStatusRef = (0, import_react2.useRef)("none" /* None */);
   const modalInitTimeoutRef = (0, import_react2.useRef)(null);
   const isModalInitRef = (0, import_react2.useRef)(false);
-  const { height: windowHeight, width: windowWidth } = (0, import_react_native4.useWindowDimensions)();
+  const { height: windowHeight, width: windowWidth } = (0, import_react_native5.useWindowDimensions)();
   const keyboardHeightRef = (0, import_react2.useRef)(0);
   const isAdViewVisible = showIframe && iframeLoaded;
   const reset = () => {
@@ -205,7 +223,6 @@ var Format = ({ code, messageId, wrapper, onEvent, ...otherParams }) => {
     setIframeLoaded(false);
     resetModal();
     context?.resetAll();
-    context?.captureError(new Error("Processing iframe error"));
   };
   const resetModal = () => {
     if (modalInitTimeoutRef.current) {
@@ -316,7 +333,7 @@ var Format = ({ code, messageId, wrapper, onEvent, ...otherParams }) => {
       return;
     }
     try {
-      await import_react_native4.Linking.openURL(`${context?.adServerUrl}${message.data.url}`);
+      await import_react_native5.Linking.openURL(`${context?.adServerUrl}${message.data.url}`);
     } catch (e) {
       console.error("error opening url", e);
     }
@@ -451,7 +468,6 @@ var Format = ({ code, messageId, wrapper, onEvent, ...otherParams }) => {
             case "error-component-iframe":
             case "error-iframe":
               resetModal();
-              context?.captureError(new Error("Processing modal iframe error"));
               break;
             case "open-skoverlay-iframe":
               openSkOverlay(
@@ -550,10 +566,10 @@ var Format = ({ code, messageId, wrapper, onEvent, ...otherParams }) => {
     return () => clearInterval(interval);
   }, [isAdViewVisible]);
   (0, import_react2.useEffect)(() => {
-    const showSubscription = import_react_native4.Keyboard.addListener("keyboardDidShow", (e) => {
+    const showSubscription = import_react_native5.Keyboard.addListener("keyboardDidShow", (e) => {
       keyboardHeightRef.current = e?.endCoordinates?.height ?? 0;
     });
-    const hideSubscription = import_react_native4.Keyboard.addListener("keyboardDidHide", () => {
+    const hideSubscription = import_react_native5.Keyboard.addListener("keyboardDidHide", () => {
       keyboardHeightRef.current = 0;
     });
     return () => {
@@ -578,9 +594,14 @@ var Format = ({ code, messageId, wrapper, onEvent, ...otherParams }) => {
         borderWidth: 0,
         ...iframeStyles
       },
-      onError: () => {
-        debug("iframe-error");
-        reset();
+      onError: (error, shouldReset) => {
+        debug("iframe-error", {
+          error: error.toString()
+        });
+        context?.captureError(error);
+        if (shouldReset) {
+          reset();
+        }
       },
       onLoad: () => {
         debug("iframe-load");
@@ -589,7 +610,7 @@ var Format = ({ code, messageId, wrapper, onEvent, ...otherParams }) => {
     }
   );
   const interstitialContent = /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
-    import_react_native4.Modal,
+    import_react_native5.Modal,
     {
       visible: modalOpen,
       transparent: true,
@@ -597,7 +618,7 @@ var Format = ({ code, messageId, wrapper, onEvent, ...otherParams }) => {
       animationType: "slide",
       statusBarTranslucent: true,
       children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
-        import_react_native4.View,
+        import_react_native5.View,
         {
           style: {
             flex: 1,
@@ -616,9 +637,14 @@ var Format = ({ code, messageId, wrapper, onEvent, ...otherParams }) => {
                 width: "100%",
                 borderWidth: 0
               },
-              onError: () => {
-                debug("modal-error");
-                resetModal();
+              onError: (error, shouldReset) => {
+                debug("modal-error", {
+                  error: error.toString()
+                });
+                context?.captureError(error);
+                if (shouldReset) {
+                  resetModal();
+                }
               },
               onLoad: () => {
                 debug("modal-load");
@@ -632,7 +658,7 @@ var Format = ({ code, messageId, wrapper, onEvent, ...otherParams }) => {
   );
   return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(import_jsx_runtime2.Fragment, { children: [
     /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
-      import_react_native4.View,
+      import_react_native5.View,
       {
         style: isAdViewVisible ? containerStyles : {
           height: 0,
@@ -658,13 +684,92 @@ var InlineAd_default = InlineAd;
 // src/context/AdsProvider.tsx
 var import_sdk_react2 = require("@kontextso/sdk-react");
 var import_netinfo = require("@react-native-community/netinfo");
-var import_react_native5 = require("react-native");
+var import_react_native7 = require("react-native");
 var import_react_native_device_info = __toESM(require("react-native-device-info"));
 
 // package.json
-var version = "3.3.0";
+var version = "3.4.0-rc.0";
+
+// src/services/Att.ts
+var import_react_native6 = require("react-native");
+var ZERO_UUID = "00000000-0000-0000-0000-000000000000";
+var didRunStartupFlow = false;
+var startupFlowPromise = null;
+function requestTrackingAuthorization() {
+  if (didRunStartupFlow) {
+    return startupFlowPromise ?? Promise.resolve();
+  }
+  didRunStartupFlow = true;
+  startupFlowPromise = _runStartupFlow();
+  return startupFlowPromise;
+}
+async function getTrackingAuthorizationStatus() {
+  if (import_react_native6.Platform.OS !== "ios") {
+    return 4 /* NotSupported */;
+  }
+  try {
+    const raw = await NativeRNKontext_default.getTrackingAuthorizationStatus();
+    return _mapRawStatus(raw);
+  } catch (error) {
+    console.error(error);
+    return 4 /* NotSupported */;
+  }
+}
+async function getAdvertisingId() {
+  try {
+    const id = await NativeRNKontext_default.getAdvertisingId();
+    return _normalizeId(id);
+  } catch (error) {
+    console.error(error);
+    return null;
+  }
+}
+async function getVendorId() {
+  if (import_react_native6.Platform.OS !== "ios") {
+    return null;
+  }
+  try {
+    const id = await NativeRNKontext_default.getVendorId();
+    return _normalizeId(id);
+  } catch (error) {
+    console.error(error);
+    return null;
+  }
+}
+async function resolveIds(fallbacks) {
+  const [vendorId, advertisingId] = await Promise.all([getVendorId(), getAdvertisingId()]);
+  return {
+    vendorId: vendorId ?? _normalizeId(fallbacks?.vendorId),
+    advertisingId: advertisingId ?? _normalizeId(fallbacks?.advertisingId)
+  };
+}
+async function _runStartupFlow() {
+  if (import_react_native6.Platform.OS !== "ios") return;
+  try {
+    if (!_isVersionAtLeast145(import_react_native6.Platform.Version)) return;
+    const status = await getTrackingAuthorizationStatus();
+    if (status !== 0 /* NotDetermined */) return;
+    await NativeRNKontext_default.requestTrackingAuthorization();
+  } catch (error) {
+    console.error(error);
+  }
+}
+function _isVersionAtLeast145(version2) {
+  const [major = 0, minor = 0] = version2.split(".").map(Number);
+  return major > 14 || major === 14 && minor >= 5;
+}
+function _mapRawStatus(raw) {
+  if (raw >= 0 && raw <= 4) return raw;
+  return 4 /* NotSupported */;
+}
+function _normalizeId(id) {
+  if (!id || id.trim() === "") return null;
+  if (id.toLowerCase() === ZERO_UUID) return null;
+  return id;
+}
 
 // src/context/AdsProvider.tsx
+var import_react3 = require("react");
 var import_jsx_runtime4 = require("react/jsx-runtime");
 ErrorUtils.setGlobalHandler((error, isFatal) => {
   if (!isFatal) {
@@ -683,7 +788,7 @@ var getDevice = async () => {
     const powerState = await import_react_native_device_info.default.getPowerState();
     const deviceType = import_react_native_device_info.default.getDeviceType();
     const soundOn = await NativeRNKontext_default.isSoundOn();
-    const screen = import_react_native5.Dimensions.get("screen");
+    const screen = import_react_native7.Dimensions.get("screen");
     const networkInfo = await (0, import_netinfo.fetch)();
     const mapDeviceTypeToHardwareType = () => {
       switch (deviceType) {
@@ -720,14 +825,14 @@ var getDevice = async () => {
         detail: networkInfo.type === import_netinfo.NetInfoStateType.cellular && networkInfo.details.cellularGeneration || void 0
       },
       os: {
-        name: import_react_native5.Platform.OS,
+        name: import_react_native7.Platform.OS,
         version: import_react_native_device_info.default.getSystemVersion(),
         locale: Intl.DateTimeFormat().resolvedOptions().locale,
         timezone: Intl.DateTimeFormat().resolvedOptions().timeZone
       },
       screen: {
-        darkMode: import_react_native5.Appearance.getColorScheme() === "dark",
-        dpr: import_react_native5.PixelRatio.get(),
+        darkMode: import_react_native7.Appearance.getColorScheme() === "dark",
+        dpr: import_react_native7.PixelRatio.get(),
         height: screen.height,
         width: screen.width,
         orientation: screen.width > screen.height ? "landscape" : "portrait"
@@ -760,7 +865,7 @@ var getApp = async () => {
 };
 var getSdk = async () => ({
   name: "sdk-react-native",
-  platform: import_react_native5.Platform.OS === "ios" ? "ios" : "android",
+  platform: import_react_native7.Platform.OS === "ios" ? "ios" : "android",
   version
 });
 var getTcf = async () => {
@@ -778,7 +883,38 @@ var getTcf = async () => {
   }
 };
 var AdsProvider = (props) => {
-  return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(import_sdk_react2.AdsProviderInternal, { ...props, getDevice, getSdk, getApp, getTcf });
+  const [advertisingId, setAdvertisingId] = (0, import_react3.useState)();
+  const [vendorId, setVendorId] = (0, import_react3.useState)();
+  const initializeIfa = async () => {
+    try {
+      if (import_react_native7.Platform.OS === "ios") {
+        await requestTrackingAuthorization();
+      }
+      const ids = await resolveIds({
+        advertisingId: props.advertisingId ?? void 0,
+        vendorId: props.vendorId ?? void 0
+      });
+      setAdvertisingId(ids.advertisingId);
+      setVendorId(ids.vendorId);
+    } catch (error) {
+      console.error(error);
+    }
+  };
+  (0, import_react3.useEffect)(() => {
+    initializeIfa();
+  }, []);
+  return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+    import_sdk_react2.AdsProviderInternal,
+    {
+      ...props,
+      advertisingId,
+      vendorId,
+      getDevice,
+      getSdk,
+      getApp,
+      getTcf
+    }
+  );
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.mjs

@@ -25,15 +25,17 @@ import {
   useBid,
   useIframeUrl
 } from "@kontextso/sdk-react";
-import { useContext, useEffect, useRef, useState } from "react";
-import { Keyboard, Linking, Modal, useWindowDimensions, View } from "react-native";
+import { useContext, useEffect, useRef as useRef2, useState } from "react";
+import { Keyboard, Linking as Linking2, Modal, useWindowDimensions, View } from "react-native";
 
 // src/frame-webview.tsx
-import { forwardRef } from "react";
+import { forwardRef, useRef } from "react";
+import { Linking } from "react-native";
 import { WebView } from "react-native-webview";
 import { jsx } from "react/jsx-runtime";
 var FrameWebView = forwardRef(
   ({ iframeUrl, onMessage, style, onError, onLoad }, forwardedRef) => {
+    const isLoadedRef = useRef(false);
     return /* @__PURE__ */ jsx(
       WebView,
       {
@@ -58,9 +60,25 @@ var FrameWebView = forwardRef(
               window.ReactNativeWebView.postMessage(JSON.stringify(event.data));
             }
           }, false);
+
       `,
-        onError,
-        onLoad
+        onError: (event) => onError(
+          new Error(`${event.nativeEvent.title}: ${event.nativeEvent.description} [${event.nativeEvent.url}]`),
+          true
+        ),
+        onLoad: () => {
+          isLoadedRef.current = true;
+          onLoad();
+        },
+        onShouldStartLoadWithRequest: (request) => {
+          if (!isLoadedRef.current || request.url.match(/^about:/) || request.url.startsWith(iframeUrl)) {
+            return true;
+          }
+          Linking.openURL(request.url).catch((err) => {
+            onError(new Error(`Failed to open URL: ${request.url} [${err.message}]`));
+          });
+          return false;
+        }
       }
     );
   }
@@ -157,14 +175,14 @@ var Format = ({ code, messageId, wrapper, onEvent, ...otherParams }) => {
   const [modalLoaded, setModalLoaded] = useState(false);
   const [containerStyles, setContainerStyles] = useState({});
   const [iframeStyles, setIframeStyles] = useState({});
-  const containerRef = useRef(null);
-  const webViewRef = useRef(null);
-  const modalWebViewRef = useRef(null);
-  const messageStatusRef = useRef("none" /* None */);
-  const modalInitTimeoutRef = useRef(null);
-  const isModalInitRef = useRef(false);
+  const containerRef = useRef2(null);
+  const webViewRef = useRef2(null);
+  const modalWebViewRef = useRef2(null);
+  const messageStatusRef = useRef2("none" /* None */);
+  const modalInitTimeoutRef = useRef2(null);
+  const isModalInitRef = useRef2(false);
   const { height: windowHeight, width: windowWidth } = useWindowDimensions();
-  const keyboardHeightRef = useRef(0);
+  const keyboardHeightRef = useRef2(0);
   const isAdViewVisible = showIframe && iframeLoaded;
   const reset = () => {
     setHeight(0);
@@ -174,7 +192,6 @@ var Format = ({ code, messageId, wrapper, onEvent, ...otherParams }) => {
     setIframeLoaded(false);
     resetModal();
     context?.resetAll();
-    context?.captureError(new Error("Processing iframe error"));
   };
   const resetModal = () => {
     if (modalInitTimeoutRef.current) {
@@ -285,7 +302,7 @@ var Format = ({ code, messageId, wrapper, onEvent, ...otherParams }) => {
       return;
     }
     try {
-      await Linking.openURL(`${context?.adServerUrl}${message.data.url}`);
+      await Linking2.openURL(`${context?.adServerUrl}${message.data.url}`);
     } catch (e) {
       console.error("error opening url", e);
     }
@@ -420,7 +437,6 @@ var Format = ({ code, messageId, wrapper, onEvent, ...otherParams }) => {
             case "error-component-iframe":
             case "error-iframe":
               resetModal();
-              context?.captureError(new Error("Processing modal iframe error"));
               break;
             case "open-skoverlay-iframe":
               openSkOverlay(
@@ -547,9 +563,14 @@ var Format = ({ code, messageId, wrapper, onEvent, ...otherParams }) => {
         borderWidth: 0,
         ...iframeStyles
       },
-      onError: () => {
-        debug("iframe-error");
-        reset();
+      onError: (error, shouldReset) => {
+        debug("iframe-error", {
+          error: error.toString()
+        });
+        context?.captureError(error);
+        if (shouldReset) {
+          reset();
+        }
       },
       onLoad: () => {
         debug("iframe-load");
@@ -585,9 +606,14 @@ var Format = ({ code, messageId, wrapper, onEvent, ...otherParams }) => {
                 width: "100%",
                 borderWidth: 0
               },
-              onError: () => {
-                debug("modal-error");
-                resetModal();
+              onError: (error, shouldReset) => {
+                debug("modal-error", {
+                  error: error.toString()
+                });
+                context?.captureError(error);
+                if (shouldReset) {
+                  resetModal();
+                }
               },
               onLoad: () => {
                 debug("modal-load");
@@ -630,13 +656,92 @@ import {
   log
 } from "@kontextso/sdk-react";
 import { fetch as fetchNetworkInfo, NetInfoStateType } from "@react-native-community/netinfo";
-import { Appearance, Dimensions, PixelRatio, Platform as Platform3 } from "react-native";
+import { Appearance, Dimensions, PixelRatio, Platform as Platform4 } from "react-native";
 import DeviceInfo from "react-native-device-info";
 
 // package.json
-var version = "3.3.0";
+var version = "3.4.0-rc.0";
+
+// src/services/Att.ts
+import { Platform as Platform3 } from "react-native";
+var ZERO_UUID = "00000000-0000-0000-0000-000000000000";
+var didRunStartupFlow = false;
+var startupFlowPromise = null;
+function requestTrackingAuthorization() {
+  if (didRunStartupFlow) {
+    return startupFlowPromise ?? Promise.resolve();
+  }
+  didRunStartupFlow = true;
+  startupFlowPromise = _runStartupFlow();
+  return startupFlowPromise;
+}
+async function getTrackingAuthorizationStatus() {
+  if (Platform3.OS !== "ios") {
+    return 4 /* NotSupported */;
+  }
+  try {
+    const raw = await NativeRNKontext_default.getTrackingAuthorizationStatus();
+    return _mapRawStatus(raw);
+  } catch (error) {
+    console.error(error);
+    return 4 /* NotSupported */;
+  }
+}
+async function getAdvertisingId() {
+  try {
+    const id = await NativeRNKontext_default.getAdvertisingId();
+    return _normalizeId(id);
+  } catch (error) {
+    console.error(error);
+    return null;
+  }
+}
+async function getVendorId() {
+  if (Platform3.OS !== "ios") {
+    return null;
+  }
+  try {
+    const id = await NativeRNKontext_default.getVendorId();
+    return _normalizeId(id);
+  } catch (error) {
+    console.error(error);
+    return null;
+  }
+}
+async function resolveIds(fallbacks) {
+  const [vendorId, advertisingId] = await Promise.all([getVendorId(), getAdvertisingId()]);
+  return {
+    vendorId: vendorId ?? _normalizeId(fallbacks?.vendorId),
+    advertisingId: advertisingId ?? _normalizeId(fallbacks?.advertisingId)
+  };
+}
+async function _runStartupFlow() {
+  if (Platform3.OS !== "ios") return;
+  try {
+    if (!_isVersionAtLeast145(Platform3.Version)) return;
+    const status = await getTrackingAuthorizationStatus();
+    if (status !== 0 /* NotDetermined */) return;
+    await NativeRNKontext_default.requestTrackingAuthorization();
+  } catch (error) {
+    console.error(error);
+  }
+}
+function _isVersionAtLeast145(version2) {
+  const [major = 0, minor = 0] = version2.split(".").map(Number);
+  return major > 14 || major === 14 && minor >= 5;
+}
+function _mapRawStatus(raw) {
+  if (raw >= 0 && raw <= 4) return raw;
+  return 4 /* NotSupported */;
+}
+function _normalizeId(id) {
+  if (!id || id.trim() === "") return null;
+  if (id.toLowerCase() === ZERO_UUID) return null;
+  return id;
+}
 
 // src/context/AdsProvider.tsx
+import { useEffect as useEffect2, useState as useState2 } from "react";
 import { jsx as jsx4 } from "react/jsx-runtime";
 ErrorUtils.setGlobalHandler((error, isFatal) => {
   if (!isFatal) {
@@ -692,7 +797,7 @@ var getDevice = async () => {
         detail: networkInfo.type === NetInfoStateType.cellular && networkInfo.details.cellularGeneration || void 0
       },
       os: {
-        name: Platform3.OS,
+        name: Platform4.OS,
         version: DeviceInfo.getSystemVersion(),
         locale: Intl.DateTimeFormat().resolvedOptions().locale,
         timezone: Intl.DateTimeFormat().resolvedOptions().timeZone
@@ -732,7 +837,7 @@ var getApp = async () => {
 };
 var getSdk = async () => ({
   name: "sdk-react-native",
-  platform: Platform3.OS === "ios" ? "ios" : "android",
+  platform: Platform4.OS === "ios" ? "ios" : "android",
   version
 });
 var getTcf = async () => {
@@ -750,7 +855,38 @@ var getTcf = async () => {
   }
 };
 var AdsProvider = (props) => {
-  return /* @__PURE__ */ jsx4(AdsProviderInternal, { ...props, getDevice, getSdk, getApp, getTcf });
+  const [advertisingId, setAdvertisingId] = useState2();
+  const [vendorId, setVendorId] = useState2();
+  const initializeIfa = async () => {
+    try {
+      if (Platform4.OS === "ios") {
+        await requestTrackingAuthorization();
+      }
+      const ids = await resolveIds({
+        advertisingId: props.advertisingId ?? void 0,
+        vendorId: props.vendorId ?? void 0
+      });
+      setAdvertisingId(ids.advertisingId);
+      setVendorId(ids.vendorId);
+    } catch (error) {
+      console.error(error);
+    }
+  };
+  useEffect2(() => {
+    initializeIfa();
+  }, []);
+  return /* @__PURE__ */ jsx4(
+    AdsProviderInternal,
+    {
+      ...props,
+      advertisingId,
+      vendorId,
+      getDevice,
+      getSdk,
+      getApp,
+      getTcf
+    }
+  );
 };
 export {
   AdsProvider,

package/ios/KontextSDK.swift

@@ -3,6 +3,8 @@ import AVFoundation
 import StoreKit
 import UIKit
 import React
+import AdSupport
+import AppTrackingTransparency
 
 @objc(KontextSDK)
 public class KontextSDK: NSObject {
@@ -134,4 +136,49 @@ public class KontextSDK: NSObject {
         return out
     }
 
+    // MARK: - ATT / IFA
+
+    private static let notSupportedStatus = 4
+
+    @objc
+    public static func getTrackingAuthorizationStatus() -> NSNumber {
+        if #available(iOS 14, *) {
+            return NSNumber(value: ATTrackingManager.trackingAuthorizationStatus.rawValue)
+        }
+        return NSNumber(value: notSupportedStatus)
+    }
+
+    @objc
+    public static func requestTrackingAuthorization(
+        _ resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        if #available(iOS 14, *) {
+            TrackingAuthorizationManager.shared.requestTrackingAuthorization { statusRaw in
+                resolve(NSNumber(value: statusRaw))
+            }
+        } else {
+            resolve(NSNumber(value: notSupportedStatus))
+        }
+    }
+
+    @objc
+    public static func getAdvertisingId() -> String? {
+        let manager = ASIdentifierManager.shared()
+        if #available(iOS 14.0, *) {
+            guard ATTrackingManager.trackingAuthorizationStatus == .authorized else {
+                return nil
+            }
+            return manager.advertisingIdentifier.uuidString
+        }
+        return manager.isAdvertisingTrackingEnabled
+            ? manager.advertisingIdentifier.uuidString
+            : nil
+    }
+
+    @objc
+    public static func getVendorId() -> String? {
+        return UIDevice.current.identifierForVendor?.uuidString
+    }
+
 }

package/ios/PrivacyInfo.xcprivacy

@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+
+  <key>NSPrivacyTracking</key><true/>
+
+  <key>NSPrivacyTrackingDomains</key>
+  <array>
+    <string>megabrain.co</string>
+  </array>
+
+  <key>NSPrivacyCollectedDataTypes</key>
+  <array>
+
+    <dict>
+      <key>NSPrivacyCollectedDataType</key>
+      <string>NSPrivacyCollectedDataTypeDeviceID</string>
+      <key>NSPrivacyCollectedDataTypeLinked</key><true/>
+      <key>NSPrivacyCollectedDataTypeTracking</key><true/>
+      <key>NSPrivacyCollectedDataTypePurposes</key>
+      <array>
+        <string>NSPrivacyCollectedDataTypePurposeThirdPartyAdvertising</string>
+      </array>
+    </dict>
+
+    <dict>
+      <key>NSPrivacyCollectedDataType</key>
+      <string>NSPrivacyCollectedDataTypeOtherAppInfo</string>
+      <key>NSPrivacyCollectedDataTypeLinked</key><false/>
+      <key>NSPrivacyCollectedDataTypeTracking</key><false/>
+      <key>NSPrivacyCollectedDataTypePurposes</key>
+      <array>
+        <string>NSPrivacyCollectedDataTypePurposeAnalytics</string>
+      </array>
+    </dict>
+
+    <dict>
+      <key>NSPrivacyCollectedDataType</key>
+      <string>NSPrivacyCollectedDataTypeOtherDiagnosticData</string>
+      <key>NSPrivacyCollectedDataTypeLinked</key><false/>
+      <key>NSPrivacyCollectedDataTypeTracking</key><false/>
+      <key>NSPrivacyCollectedDataTypePurposes</key>
+      <array>
+        <string>NSPrivacyCollectedDataTypePurposeAnalytics</string>
+      </array>
+    </dict>
+
+  </array>
+
+  <key>NSPrivacyAccessedAPITypes</key>
+  <array>
+    <dict>
+      <key>NSPrivacyAccessedAPIType</key>
+      <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
+      <key>NSPrivacyAccessedAPITypeReasons</key>
+      <array>
+        <string>CA92.1</string>
+      </array>
+    </dict>
+  </array>
+
+</dict>
+</plist>

package/ios/RNKontext.mm

@@ -56,6 +56,26 @@ RCT_EXPORT_MODULE()
   resolve([KontextSDK getTcfData]);
 }
 
+- (void)getTrackingAuthorizationStatus:(RCTPromiseResolveBlock)resolve
+                                reject:(RCTPromiseRejectBlock)reject {
+    resolve([KontextSDK getTrackingAuthorizationStatus]);
+}
+
+- (void)requestTrackingAuthorization:(RCTPromiseResolveBlock)resolve
+                              reject:(RCTPromiseRejectBlock)reject {
+    [KontextSDK requestTrackingAuthorization:resolve rejecter:reject];
+}
+
+- (void)getAdvertisingId:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject {
+    resolve([KontextSDK getAdvertisingId]);
+}
+
+- (void)getVendorId:(RCTPromiseResolveBlock)resolve
+             reject:(RCTPromiseRejectBlock)reject {
+    resolve([KontextSDK getVendorId]);
+}
+
 #else
 
 RCT_EXPORT_METHOD(isSoundOn : (RCTPromiseResolveBlock)resolve
@@ -103,6 +123,26 @@ RCT_EXPORT_METHOD(getTcfData:(RCTPromiseResolveBlock)resolve
   resolve([KontextSDK getTcfData]);
 }
 
+RCT_EXPORT_METHOD(getTrackingAuthorizationStatus:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject) {
+    resolve([KontextSDK getTrackingAuthorizationStatus]);
+}
+
+RCT_EXPORT_METHOD(requestTrackingAuthorization:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject) {
+    [KontextSDK requestTrackingAuthorization:resolve rejecter:reject];
+}
+
+RCT_EXPORT_METHOD(getAdvertisingId:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject) {
+    resolve([KontextSDK getAdvertisingId]);
+}
+
+RCT_EXPORT_METHOD(getVendorId:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject) {
+    resolve([KontextSDK getVendorId]);
+}
+
 #endif
 
 @end

package/ios/TrackingAuthorizationManager.swift

@@ -0,0 +1,46 @@
+import Foundation
+import AppTrackingTransparency
+import UIKit
+
+@available(iOS 14, *)
+final class TrackingAuthorizationManager {
+    static let shared = TrackingAuthorizationManager()
+    private var observer: NSObjectProtocol?
+
+    deinit {
+        removeObserver()
+    }
+
+    func requestTrackingAuthorization(completion: @escaping (Int) -> Void) {
+        removeObserver()
+        ATTrackingManager.requestTrackingAuthorization { [weak self] status in
+            // Race condition: OS returned .denied but system status is still
+            // .notDetermined — the dialog couldn't show (app wasn't fully active).
+            // Wait for the next foreground activation and retry.
+            if status == .denied
+                && ATTrackingManager.trackingAuthorizationStatus == .notDetermined {
+                self?.addObserver(completion: completion)
+                return
+            }
+            completion(Int(status.rawValue))
+        }
+    }
+
+    private func addObserver(completion: @escaping (Int) -> Void) {
+        removeObserver()
+        observer = NotificationCenter.default.addObserver(
+            forName: UIApplication.didBecomeActiveNotification,
+            object: nil,
+            queue: .main
+        ) { [weak self] _ in
+            self?.requestTrackingAuthorization(completion: completion)
+        }
+    }
+
+    private func removeObserver() {
+        if let observer = observer {
+            NotificationCenter.default.removeObserver(observer)
+            self.observer = nil
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextso/sdk-react-native",
-  "version": "3.3.0",
+  "version": "3.4.0-rc.0",
   "description": "Kontext SDK for React Native",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -54,7 +54,7 @@
     "react-native-webview": "^13.10.0"
   },
   "dependencies": {
-    "@kontextso/sdk-react": "^3.0.7"
+    "@kontextso/sdk-react": "^3.0.8-rc.0"
   },
   "files": [
     "dist/*",

package/src/NativeRNKontext.ts

@@ -3,11 +3,25 @@ import { TurboModuleRegistry } from 'react-native'
 
 export interface Spec extends TurboModule {
   isSoundOn(): Promise<boolean>
+
+  // SKOverlay
   presentSKOverlay(appStoreId: string, position: string, dismissible: boolean): Promise<boolean>
   dismissSKOverlay(): Promise<boolean>
+
+  // SKStoreProduct
   presentSKStoreProduct(appStoreId: string): Promise<boolean>
   dismissSKStoreProduct(): Promise<boolean>
+
+  // TCF
   getTcfData(): Promise<{ gdprApplies: 0 | 1 | null; tcString: string | null }>
+
+  // ATT
+  getTrackingAuthorizationStatus(): Promise<number>
+  requestTrackingAuthorization(): Promise<number>
+
+  // IFA
+  getAdvertisingId(): Promise<string | null>
+  getVendorId(): Promise<string | null>
 }
 
 export default TurboModuleRegistry.getEnforcing<Spec>('RNKontext')

package/src/context/AdsProvider.tsx

@@ -12,6 +12,8 @@ import { Appearance, Dimensions, PixelRatio, Platform } from 'react-native'
 import DeviceInfo, { type DeviceType } from 'react-native-device-info'
 import { version } from '../../package.json'
 import NativeRNKontext from '../NativeRNKontext'
+import { requestTrackingAuthorization, resolveIds } from '../services/Att'
+import { useEffect, useState } from 'react'
 
 ErrorUtils.setGlobalHandler((error, isFatal) => {
   if (!isFatal) {
@@ -142,5 +144,35 @@ const getTcf = async (): Promise<Pick<RegulatoryConfig, 'gdpr' | 'gdprConsent'>>
 }
 
 export const AdsProvider = (props: AdsProviderProps) => {
-  return <AdsProviderInternal {...props} getDevice={getDevice} getSdk={getSdk} getApp={getApp} getTcf={getTcf} />
+  const [advertisingId, setAdvertisingId] = useState<string | null | undefined>()
+  const [vendorId, setVendorId] = useState<string | null | undefined>()
+
+  const initializeIfa = async () => {
+    try {
+      if (Platform.OS === 'ios') {
+        await requestTrackingAuthorization()
+      }
+      const ids = await resolveIds({
+        advertisingId: props.advertisingId ?? undefined,
+        vendorId: props.vendorId ?? undefined,
+      })
+      setAdvertisingId(ids.advertisingId)
+      setVendorId(ids.vendorId)
+    } catch (error) {
+      console.error(error)
+    }
+  }
+
+  useEffect(() => {
+    initializeIfa()
+  }, [])
+  return <AdsProviderInternal 
+    {...props} 
+    advertisingId={advertisingId}
+    vendorId={vendorId}
+    getDevice={getDevice}
+    getSdk={getSdk}
+    getApp={getApp}
+    getTcf={getTcf}
+  />
 }

package/src/formats/Format.tsx

@@ -18,8 +18,8 @@ import { useContext, useEffect, useRef, useState } from 'react'
 import { Keyboard, Linking, Modal, useWindowDimensions, View } from 'react-native'
 import type { WebView, WebViewMessageEvent } from 'react-native-webview'
 import FrameWebView from '../frame-webview'
-import { presentSKOverlay, dismissSKOverlay, type SKOverlayPosition } from '../services/SkOverlay'
-import { presentSKStoreProduct, dismissSKStoreProduct } from '../services/SkStoreProduct'
+import { dismissSKOverlay, presentSKOverlay, type SKOverlayPosition } from '../services/SkOverlay'
+import { dismissSKStoreProduct, presentSKStoreProduct } from '../services/SkStoreProduct'
 
 const sendMessage = (
   webViewRef: React.RefObject<WebView>,
@@ -97,7 +97,6 @@ const Format = ({ code, messageId, wrapper, onEvent, ...otherParams }: FormatPro
     setIframeLoaded(false)
     resetModal()
     context?.resetAll()
-    context?.captureError(new Error('Processing iframe error'))
   }
 
   const resetModal = () => {
@@ -380,7 +379,6 @@ const Format = ({ code, messageId, wrapper, onEvent, ...otherParams }: FormatPro
             case 'error-component-iframe':
             case 'error-iframe':
               resetModal()
-              context?.captureError(new Error('Processing modal iframe error'))
               break
 
             case 'open-skoverlay-iframe':
@@ -532,9 +530,14 @@ const Format = ({ code, messageId, wrapper, onEvent, ...otherParams }: FormatPro
         borderWidth: 0,
         ...iframeStyles,
       }}
-      onError={() => {
-        debug('iframe-error')
-        reset()
+      onError={(error, shouldReset) => {
+        debug('iframe-error', {
+          error: error.toString(),
+        })
+        context?.captureError(error)
+        if (shouldReset) {
+          reset()
+        }
       }}
       onLoad={() => {
         debug('iframe-load')
@@ -568,9 +571,14 @@ const Format = ({ code, messageId, wrapper, onEvent, ...otherParams }: FormatPro
             width: '100%',
             borderWidth: 0,
           }}
-          onError={() => {
-            debug('modal-error')
-            resetModal()
+          onError={(error, shouldReset) => {
+            debug('modal-error', {
+              error: error.toString(),
+            })
+            context?.captureError(error)
+            if (shouldReset) {
+              resetModal()
+            }
           }}
           onLoad={() => {
             debug('modal-load')

package/src/frame-webview.tsx

@@ -1,17 +1,19 @@
-import { forwardRef } from 'react'
-import type { StyleProp, ViewStyle } from 'react-native'
+import { forwardRef, useRef } from 'react'
+import { Linking, type StyleProp, type ViewStyle } from 'react-native'
 import { WebView, type WebViewMessageEvent } from 'react-native-webview'
 
 interface FrameWebViewProps {
   iframeUrl: string
   onMessage: (event: WebViewMessageEvent) => void
   style: StyleProp<ViewStyle>
-  onError: () => void
+  onError: (error: Error, shouldReset?: boolean) => void
   onLoad: () => void
 }
 
 const FrameWebView = forwardRef<WebView, FrameWebViewProps>(
   ({ iframeUrl, onMessage, style, onError, onLoad }, forwardedRef) => {
+    const isLoadedRef = useRef(false)
+
     return (
       <WebView
         ref={forwardedRef}
@@ -35,9 +37,28 @@ const FrameWebView = forwardRef<WebView, FrameWebViewProps>(
               window.ReactNativeWebView.postMessage(JSON.stringify(event.data));
             }
           }, false);
+
       `}
-        onError={onError}
-        onLoad={onLoad}
+        onError={(event) =>
+          onError(
+            new Error(`${event.nativeEvent.title}: ${event.nativeEvent.description} [${event.nativeEvent.url}]`),
+            true
+          )
+        }
+        onLoad={() => {
+          isLoadedRef.current = true
+          onLoad()
+        }}
+        onShouldStartLoadWithRequest={(request) => {
+          if (!isLoadedRef.current || request.url.match(/^about:/) || request.url.startsWith(iframeUrl)) {
+            return true
+          }
+
+          Linking.openURL(request.url).catch((err) => {
+            onError(new Error(`Failed to open URL: ${request.url} [${err.message}]`))
+          })
+          return false
+        }}
       />
     )
   }

package/src/services/Att.ts

@@ -0,0 +1,117 @@
+import { Platform } from 'react-native'
+import NativeRNKontext from '../NativeRNKontext'
+
+const ZERO_UUID = '00000000-0000-0000-0000-000000000000'
+
+// Mirrors TrackingStatus enum from Flutter / ATTrackingManager raw values
+export enum TrackingStatus {
+  NotDetermined = 0,
+  Restricted = 1,
+  Denied = 2,
+  Authorized = 3,
+  NotSupported = 4, // iOS < 14 or non-iOS
+}
+
+let didRunStartupFlow = false
+let startupFlowPromise: Promise<void> | null = null
+
+/**
+ * Requests ATT authorization on iOS >= 14.5.
+ * On iOS 14.0–14.4 we intentionally skip the request: the dialog is not
+ * required to read IDFA on those versions, and asking only to get denied
+ * would permanently revoke access.
+ * Guaranteed to run only once per app session regardless of call count.
+ */
+export function requestTrackingAuthorization(): Promise<void> {
+  if (didRunStartupFlow) {
+    return startupFlowPromise ?? Promise.resolve()
+  }
+  didRunStartupFlow = true
+  startupFlowPromise = _runStartupFlow()
+  return startupFlowPromise
+}
+
+export async function getTrackingAuthorizationStatus(): Promise<TrackingStatus> {
+  if (Platform.OS !== 'ios') {
+    return TrackingStatus.NotSupported
+  }
+  try {
+    const raw = await NativeRNKontext.getTrackingAuthorizationStatus()
+    return _mapRawStatus(raw)
+  } catch (error) {
+    console.error(error)
+    return TrackingStatus.NotSupported
+  }
+}
+
+export async function getAdvertisingId(): Promise<string | null> {
+  try {
+    const id = await NativeRNKontext.getAdvertisingId()
+    return _normalizeId(id)
+  } catch (error) {
+    console.error(error)
+    return null
+  }
+}
+
+export async function getVendorId(): Promise<string | null> {
+  if (Platform.OS !== 'ios') {
+    return null
+  }
+  try {
+    const id = await NativeRNKontext.getVendorId()
+    return _normalizeId(id)
+  } catch (error) {
+    console.error(error)
+    return null
+  }
+}
+
+export async function resolveIds(fallbacks?: {
+  vendorId?: string | undefined
+  advertisingId?: string | undefined
+}): Promise<{ vendorId: string | null; advertisingId: string | null }> {
+  const [vendorId, advertisingId] = await Promise.all([getVendorId(), getAdvertisingId()])
+
+  return {
+    vendorId: vendorId ?? _normalizeId(fallbacks?.vendorId),
+    advertisingId: advertisingId ?? _normalizeId(fallbacks?.advertisingId),
+  }
+}
+
+// ─── internal ────────────────────────────────────────────────────────────────
+
+async function _runStartupFlow(): Promise<void> {
+  if (Platform.OS !== 'ios') return
+
+  try {
+    if (!_isVersionAtLeast145(Platform.Version)) return
+
+    const status = await getTrackingAuthorizationStatus()
+    if (status !== TrackingStatus.NotDetermined) return
+
+    await NativeRNKontext.requestTrackingAuthorization()
+  } catch (error) {
+    console.error(error)
+  }
+}
+
+/**
+ * iOS 14.0–14.4: ATT dialog not required for IDFA access.
+ * Requesting it risks permanent denial, so we only request on >= 14.5.
+ */
+function _isVersionAtLeast145(version: string): boolean {
+  const [major = 0, minor = 0] = version.split('.').map(Number)
+  return major > 14 || (major === 14 && minor >= 5)
+}
+
+function _mapRawStatus(raw: number): TrackingStatus {
+  if (raw >= 0 && raw <= 4) return raw as TrackingStatus
+  return TrackingStatus.NotSupported
+}
+
+function _normalizeId(id: string | null | undefined): string | null {
+  if (!id || id.trim() === '') return null
+  if (id.toLowerCase() === ZERO_UUID) return null
+  return id
+}