Interface IClientSessionGyro

Method Details

• getSessionInstance

  static IClientSessionGyro getSessionInstance()

  Gets the runtime application instance for the current thread in a client session.

  Returns:

  The RuntimeApp instance when called from a thread of the client session, null otherwise.

• getSessionInstance

  static IClientSessionGyro getSessionInstance(SessionInfo sessionInfo)

  Gets the runtime application instance for the current thread in a client session.

  Parameters:

  sessionInfo - A session information instance, or null for none.

  Returns:

  The RuntimeApp instance when called from a thread of the client session, null otherwise.

• addDisposeListener

  boolean addDisposeListener(IClientSessionDisposeListener listener)

  Adds a dispose listener for the client session. Calling this method multiple times with the same listener will have no effect (but to return false).

  Parameters:

  listener - The listener to add.

  Returns:

  true if the listener was added, false otherwise.

  Throws:

  NullPointerException - If the listener is null.

• removeDisposeListener

  boolean removeDisposeListener(IClientSessionDisposeListener listener)

  Removes a dispose listener for the client session.

  Parameters:

  listener - The listener to remove.

  Returns:

  true if listener is successfully removed, false otherwise.

• dispose

  boolean dispose()

  Disposes of the Gyro instance so the client session ends.

  Returns:

  true for dispose success, false if already disposed of.

• isDisposed

  boolean isDisposed()

  Checks if the client session Gyro is disposed of.

  Returns:

  true if disposed, false otherwise.

• getAppSessionGyro

  IAppSessionGyro getAppSessionGyro()

  Gets the Gyro for the application session.

• getClientSessionInfo

  SessionInfo getClientSessionInfo()

  Gets the client sessions information.

  Returns:

  The session information instance.

• getEntryParameter

  String getEntryParameter(String name)

  Gets a parameter of the URL the client entered the application with: a query parameter of the connection the client made, other than the ones the server reads itself (app, user, k, sid and hash). The SignIn module reads the reset token of a mailed link this way, prt (CC-LOGIN-L10A1-SERVER-GAPS, SignIn flow D-16).

  Parameters:

  name - The parameter name, e.g. "prt".

  Returns:

  The value of the parameter, URL-decoded, or null when the entry URL carries none with that name, and when the client has not connected.

• getUIFocusEngine

  IFocusEngine getUIFocusEngine()

  Returns the UI focus engine instance for the specified component.

  Returns:

  The UI focus engine instance.

• getClientTimerEngine

  ITimerEngine getClientTimerEngine()

  Gets the client timer engine. All timer tasks as disposed of automatically when the client session exits.

  Returns:

  The client session implementation of the timeout engine.

• synchronizeCurrentFocusWithVS

  boolean synchronizeCurrentFocusWithVS()

  Updates the focus to the VS from the current focused UI component. This may be needed to synchronize the VS focus for a particular UI session to make sure it is synchronized.

  Returns:

  true for success, false if nothing was done.

• setPseudoActionFocusToVS

  void setPseudoActionFocusToVS(IUIFocusComp focusComp, IGProp<?> trigger)

  Called when a "pseudo UI action" is executed, making sure its VS counterpart has the current focus. This "pseudo action" can be e.g. a MLItemProp that has a context menu, as well as an direct action such as a UIButton.

  This method is not intended to be called but is used internally by the framework.

  Parameters:

  focusComp - The "pseudo action" focus component.

  trigger - The trigger component, null for none.

• getClientWorker

  Worker getClientWorker()

  Gets the Worker for the current Client session.

  Returns:

  The Client Worker, or null if the current thread is not associated to a Client.

• getKStringInfoProvider

  IPropMgrInfoProvider getKStringInfoProvider()

  Retrieves the IPropMgrInfoProvider for the client session.

  Specified by:

  getKStringInfoProvider in interface ILocaleString

  Returns:

  The KString information provider instance, or null if not possible. The instance also supports SVG caching and Custom CSS.

• getEnvironment

  EnvProps getEnvironment()

  Gets the current environment properties for Selector's or Value's.

  This is NOT the same instance as the one available from the IAppSessionGyro.getEnvironment().

  Returns:

  The current environment properties for selectors, null if client hasn't sent them yet.

• getAnalyticsConsent

  Boolean getAnalyticsConsent()

  Gets the user's Web Analytics consent as the client last reported it: the value of the EnvProps.PN_ANALYTICS_CONSENT boolean of this client's environment, set by a Browser client when its connection is established and again whenever the user decides.

  Never a cookie wall: the server may read this value, for example to decide what to log or to offer a privacy page, but no function of the application or of IIZI may ever depend on it. A user who declined must get exactly the same application as one who accepted.

  Returns:

  Boolean.TRUE when accepted, Boolean.FALSE when declined, or null when undecided, when the client is not a Browser running an application with a Measurement ID (iiziRun, the Designer pages), or when it has not reported yet.

• askAnalyticsConsent

  boolean askAnalyticsConsent()

  Asks the client to show IIZI's Web Analytics consent prompt now, even when a decision is already stored. The user's answer is written on the device, applied by the client without a page reload and reported back through getAnalyticsConsent(); this method does not wait for it.

  Only a Browser client running an application with a Measurement ID shows anything; iiziRun and the Designer pages ignore the request.

  Returns:

  true when the request was sent, false when the session is disposed of.

• setAnalyticsConsent

  boolean setAnalyticsConsent(boolean granted)

  Sets the user's Web Analytics consent directly, when the application asked the user itself (the App page's consent choice "the application asks"). The client writes the decision on the device, starts or stops Analytics accordingly without a page reload, and reports the new value back through getAnalyticsConsent(); this method does not wait for it.

  Only a Browser client running an application with a Measurement ID acts on it; iiziRun and the Designer pages ignore the request.

  Parameters:

  granted - true when the user accepted, false when the user declined.

  Returns:

  true when the decision was sent, false when the session is disposed of.

• getUIScheme

  UISchemes.Scheme getUIScheme()

  Gets the theme scheme this client SHOWS: the shipped theme family and the resolved mode, light or dark, never auto (UISchemes; THEME-DESIGN.md section 4.6). The client reports it at connect and on every change: a choice of the user in a Browser, an installed PWA or iiziRun, a theme= entry URL parameter, the OS switching between day and night under an auto mode, or a call of setUIScheme(UISchemes.Family,UISchemes.Mode).

  Returns:

  The scheme shown, or null when the client has not reported one: an older client, a Designer session before the Panel Editor sent its choice, or a report that is not a shipped family and mode.

• getUISchemeChoice

  UISchemes.Scheme getUISchemeChoice()

  Gets the theme scheme this client was told to show, the mode as CHOSEN: light, dark, UISchemes.Mode.AUTO (follow the OS, light when it cannot tell) or UISchemes.Mode.AUTO_DARK. getUIScheme() is what that choice resolved to.

  Returns:

  The choice, or null when the client has not reported one.

• setUIScheme

  boolean setUIScheme(UISchemes.Family family, UISchemes.Mode mode)

  Sets the theme scheme of this client: the family, the mode, or both. The client applies it without a page reload, PERSISTS it on the device - in a Browser or an installed PWA in its local storage, in iiziRun in the launcher's settings, so that the next start shows it - and reports the result back through getUIScheme() and getUISchemeChoice(); this method does not wait for it. A mode the application does not allow (the App page's "Appearance" choice, uiModes) is stored as chosen but shown as the mode the application allows.

  The value travels as the $scheme client property, so a value equal to the one last sent is not sent again: set another value first to re-apply the same one.

  Parameters:

  family - The family, or null to keep the client's family.

  mode - The mode, or null to keep the client's mode.

  Returns:

  true when the scheme was sent, false when the session is disposed of or the value equals the one last sent.

  Throws:

  IllegalArgumentException - If both the family and the mode are null.

• setUIMode

  boolean setUIMode(UISchemes.Mode mode)

  Sets the mode of this client's theme scheme, keeping its family: the convenience over setUIScheme(UISchemes.Family,UISchemes.Mode).

  Parameters:

  mode - The mode: light, dark, auto or auto_dark.

  Returns:

  true when the mode was sent, false when the session is disposed of or the value equals the one last sent.

  Throws:

  IllegalArgumentException - If the mode is null.

• setUIFamily

  boolean setUIFamily(UISchemes.Family family)

  Sets the family of this client's theme scheme, keeping its mode: the convenience over setUIScheme(UISchemes.Family,UISchemes.Mode).

  Parameters:

  family - The family.

  Returns:

  true when the family was sent, false when the session is disposed of or the value equals the one last sent.

  Throws:

  IllegalArgumentException - If the family is null.

• addUISchemeListener

  boolean addUISchemeListener(IUISchemeListener listener)

  Adds a theme scheme listener for this client session, told on the client session's Worker when the resolved scheme the client shows changes, once per distinct value. Calling this method multiple times with the same listener will have no effect (but to return false).

  Parameters:

  listener - The listener to add.

  Returns:

  true if the listener was added, false otherwise.

  Throws:

  NullPointerException - If the listener is null.

• removeUISchemeListener

  boolean removeUISchemeListener(IUISchemeListener listener)

  Removes a theme scheme listener for this client session.

  Parameters:

  listener - The listener to remove.

  Returns:

  true if listener is successfully removed, false otherwise.

• getUIModes

  default int getUIModes()

  Gets the appearance modes the application of this client session allows a client to show (CC-THEME-CHOOSER-UI): the App page's "Appearance" choice, ModuleApp.getUIModes(), UISchemes.MODES_BOTH (the user chooses), UISchemes.MODES_LIGHT or UISchemes.MODES_DARK. The theme chooser component (UIThemeChooser) hides itself when one mode only is allowed. The default answers UISchemes.MODES_BOTH, so that an implementation that does not carry the choice shows the chooser.

  Returns:

  The modes allowed.

• getWebEngineStatus

  default WebEngineStatus getWebEngineStatus()

  Gets the verdict on the web engine this client runs on: whether it still receives security updates, and since when it does not. The web engine is Android System WebView or Chrome on Android, and the operating system itself on iOS and iPadOS; any other client, a desktop Browser included, is WebEngineStatus.Status.NOT_ASSESSED.

  The server computes the verdict when the client session connects, from what the client says about itself, and again at every reconnect. IIZI never refuses or restricts a client because of it. An application may: it can read the verdict here and apply a stricter policy of its own, for example refuse a payment step on an WebEngineStatus.Status.ENDED engine. A client can make itself look patched, so the verdict is no proof of a safe device.

  Declared here in core and implemented by the server's client session gyro. The default answers "not assessed".

  Returns:

  The verdict, never null.

• showWebEngineWarning

  default boolean showWebEngineWarning()

  Shows the user IIZI's notice that the web engine of the device no longer receives security updates, now: the engine and its version, that it stopped receiving security updates, and since when. For an application whose "Unpatched web engine" choice on the App page is "the application decides"; with "IIZI warns" the notice is shown when the client session connects, and this call shows it again. The notice never blocks the application, and this method does not wait for it.

  Nothing is shown when the engine is patched or not assessed (WebEngineStatus.isUnpatched() is false), or when the choice on the App page is "never".

  Returns:

  true when the notice was sent to the client, false when there is nothing to warn about, the application never warns, or the session is disposed of.

• credentialsAccepted

  boolean credentialsAccepted(UIContainer form)

  Tells the client that the credentials the user typed in a form container were accepted, so that the password manager of the Browser offers to save them: the save-password signal of the SignIn module (UITEXT D-2 (a)). Call it once the sign-in, the sign-up or the change of password has succeeded, BEFORE the container is hidden, swapped out or its fields are cleared: the client reads the fields as they are in the page. Nothing typed travels in this call: only the path of the container does.

  It is EnvProps.credentialsAccepted(UIContainer) of this client's environment, which says what the client does; the call is here so that an application's code reaches it from the client session it works with, as it reaches every other call to its client.

  Parameters:

  form - The container holding the text fields of the credentials, as the client session has it.

  Returns:

  true when the signal was sent, false when the session or its environment is disposed of, or the client has not sent its environment yet.

  Throws:

  NullPointerException - If the container is null.

  IllegalArgumentException - If the container is not in the property tree of this client session.

• getOpenNativeSettings

  default IOpenNativeSettings getOpenNativeSettings() throws NotFoundException

  Get the open native settings interface for the client-specific instance, supported only on iiziRun clients running iiziRun-based clients for Android and iOS.

  Returns:

  The open native settings interface. In order to test support for open native settings operations, use IOpenNativeSettings.isSupported().

  Throws:

  NotFoundException - In case the open native settings instance is not found, typically if the client session is under creation, or it has been disposed of.

• getFlashlight

  IFlashlight getFlashlight() throws NotFoundException

  Gets the flashlight client-specific instance, currently only supported for operations on iiziRun clients for Android and iOS.

  Returns:

  The flashlight instance. In order to test support of flashlight operations, use IFlashlight.isSupported().

  Throws:

  NotFoundException - In case the flashlight instance is not found, typically if the client session is under creation, or it has been disposed of.

• getLocationService

  ILocationService getLocationService()

  Returns an instance of the geolocation service.

  Returns:

  The instance, always non-null.

• getPushNotificationAPI

  default IPushNotificationAPI getPushNotificationAPI()

  Gets the Push Notification API of this client session: the device the user is on, its permission and subscriptions, and sends to this device only.

  Declared here in core and implemented by the server's client session gyro. The default answers null, which means "not a server", and is only ever seen by an implementation that is not the server's.

  Returns:

  The API, or null if this gyro is not a server client session.

• getFileUploadAPI

  default IClientUploadAPI getFileUploadAPI()

  Gets the file upload API of this client session: where a client's request to upload files is allowed or refused, and where the reservations made through this client are observed. A request is reserved against the upload service of the application session (IAppSessionGyro.getFileUploadService()), and its answer goes to this client.

  Declared here in core and implemented by the server's client session gyro, which always answers an API: one whose IClientUploadAPI.isEnabled() is false when the client has no upload channel or the server no upload service. The default answers null, which means "not a server", and is only ever seen by an implementation that is not the server's.

  Returns:

  The API, or null if this gyro is not a server client session.

• getPrettyLocaledTexts

  PrettyLocaledTexts getPrettyLocaledTexts()

  Gets the locale'd texts instance for the sessions language and text tables.

  Returns:

  The instance used to create locale'd strings for e.g. duration and distances.

• setLocale

  LocaleInfo setLocale(LocaleInfo locale)

  Changes or sets the LocaleInfo for the environment.

  Parameters:

  locale - localeInfo The locale information to use.

  Returns:

  The old LocaleInfo, or null if not set.

• getLanguageCode

  String getLanguageCode()

  Gets the language code to use for the client session, or if not defined, the application session language code.

  Returns:

  The language code, or null for default.

• getTopmostPanel

  UIPanelBase getTopmostPanel()

  Gets the current top-most panel.

  Returns:

  The panel, null if none has been created.

• getVirtualizedPanels

  UIPanelBase[] getVirtualizedPanels()

  Gets the cached and sorted array of panels that is currently displayed.

  The index 0 is the topmost panel and the higher the index, the more overlapped the panel is. The highest index is the top-level main panel covering the screen.

  Do not modify this array!

  Returns:

  The virtualized panels.

• getMatchingPanels

  UIPanelBase[] getMatchingPanels(VirtualSpace virtualSpace)

  Gets the panels that matches a VirtualSpace for this client session. The VirtualSpace can be virtualized or not, and the client session environment properties are used to determine the panels in question (i.e. depending on their selectors).

  This method is quite CPU intensive and should NOT be done too often. The return value is however cached during the focus handler mappings from VirtualSpace to the UI, so only one such call is done.

  The ordering is not significant and can be a mix of primary and secondary panels, however the matching panel is the virtualized instance if one is present, otherwise it is the non-virtualized instance.

  Note: The result from this method should not be cached because the matching panels may very well change during a client session due to e.g. a change in client capabilities or alike (that affects the result of the selectors used).

  Parameters:

  virtualSpace - The VirtualSpace to look-up the panels for.

  Returns:

  A cloned cached array of the matching panels.

  The array of matching panels, can be a mix of virtualized and non-virtualized panels!

• getVirtualizedPropFromReference

  GProp<?> getVirtualizedPropFromReference(String reference)

  Attempts to look up a virtualized property from a reference by searching this instance.

  Parameters:

  reference - The reference to look-up.

  Returns:

  The virtualized instance of the property, null if not found.

• getClientContextMenuReference

  String getClientContextMenuReference(UIContextMenu contextMenu, boolean fullPropReference)

  Gets the reference to use for a context menu.

  Parameters:

  contextMenu - The context menu.

  fullPropReference - Flag indicating a full property reference string should be returned, false for short (used internally by the server).

  Returns:

  The reference to use, empty string for none (never null).

  Throws:

  IllegalArgumentException - If the context menu is not a stand-alone context menu but a child of a panel component.

• requestUILock

  ILockState requestUILock()

  Requests a UI lock state. The object returned can be used to set a message below the lock spinner. It can also be used to set a progress indicator, also below the spinner. A progress indicator can also be handled using the lock object.

  Note: You MUST call the objects {link @ILockState#release()} method to release the lock state.

  Returns:

  The lock state object.

  Throws:

  IllegalStateException - If the client session is disposed of.

• isUILocked

  default boolean isUILocked()

  Get the current UI lock state.

  This state is taken from the Application Session Gyro, and callin this method equals to calling getAppSessionGyro().isUILocked().

  Returns:

  true if busy state is on, false otherwise.

  Throws:

  IllegalStateException - If the client session is disposed of.

• setBusy

  void setBusy(KString msg, int delay, int progress)

  Sets the UI busy state and optionally updates the message and/or progress.

  This method is intended to be used with advanced UI programming where a message is used in conjunction with a progress.

  If this functionality is not required, it is recommended to let the AppSessionGyro handle the busy state.

  Parameters:

  msg - Optional message, null for none.

  delay - Delay of lock spinner: -2 for default (1.5 second), -1 disabled, 0=no delay, >0 wait time in milliseconds (1-20000, i.e. 20 seconds).

  progress - Progress value, -1 for none, otherwise a value between 0 and 100.

  Throws:

  IllegalArgumentException - If progress value is not -1 or 0 to 100, or delay is smaller than -2 or larger than 20_000.

• setReady

  void setReady()

  Sets the UI to "ready", i.e. clears busy state.

  Note: the state is not set to ready immediately, merely the busy state. The UI is triggered to be synchronized with the VirtualSpace in the Client Worker thread, and a change of panel may be the result.

  This method is intended to be used with advanced UI programming where a message is used in conjunction with a progress.

  If this functionality is not required, it is recommended to let the AppSessionGyro handle the busy state.

• setReady

  boolean setReady(Runnable runnable)

  Sets the UI to "ready", i.e. clears busy state.

  Note: the state is not set to ready immediately, merely the busy state. The UI is triggered to be synchronized with the VirtualSpace in the Client Worker thread, and a change of panel may be the result.

  Specify a runnable instance if you wish to be notified when the panel is unlocked. This runnable will be called at a later stage from the Client Worker thread.

  The runnable will be be called if the busy state is turned on or the client has been locked.

  This method is intended to be used with advanced UI programming where a message is used in conjunction with a progress.

  If this functionality is not required, it is recommended to let the AppSessionGyro handle the busy state.

  Parameters:

  runnable - The runnable to be notified, null for none.

  Returns:

  true if the runnable will be called (if present), false if it will not be called.

• getCurrentFocus

  UIComp getCurrentFocus()

  Returns the current focus in the UI. If no particular component is in focus, the topmost panel is returned.

  Returns:

  The component in focus, or null if not a single panel has yet been created.

• getNextPanelAnimation

  int getNextPanelAnimation()

  Returns the animation that will be used for next panel that replaces another panel.

  This animation only applies to full-page panels.

  This value is reset to IUIPanelAnimation.ANIMATION_DEFAULT as soon as a panel replacement has been made.

  Returns:

  The composite animation value, or IUIPanelAnimation.ANIMATION_DEFAULT for none.

• setNextPanelAnimation

  int setNextPanelAnimation(int nextAnimation)

  Sets the animation that will be used for next panel that replaces another panel.

  This animation only applies to full-page panels.

  This value is reset to IUIPanelAnimation.ANIMATION_DEFAULT as soon as a panel replacement has been made.

  Returns:

  The old "next panel animation" composite animation value, or IUIPanelAnimation.ANIMATION_DEFAULT for none.

• setNextPanelAnimation

  default int setNextPanelAnimation(IUIPanelAnimation.Type type, IUIPanelAnimation.Direction direction, IUIPanelAnimation.Speed speed)

  Sets the animation that will be used for next panel that replaces another panel.

  This animation only applies to full-page panels.

  This value is reset to IUIPanelAnimation.ANIMATION_DEFAULT as soon as a panel replacement has been made.

  Parameters:

  type - The animation type.

  direction - The animation direction.

  speed - The animation speed.

  Returns:

  The old "next panel animation" composite animation value, or IUIPanelAnimation.ANIMATION_DEFAULT for none.

• enterClientLock

  void enterClientLock(boolean isFromClient)

  Method called whenever the client lock state is enabled.

  Parameters:

  isFromClient - Flag indicating the state change is induced from client side. If this flag is false, the lock state

• exitClientLock

  void exitClientLock()

  Releases client lock state if the client is not in busy state. The lock state will be released when the VS has been synchronized at a later stage, but very quickly.

• getHistoryRequest

  HistoryRequest getHistoryRequest()

  Gets the history request instance for the client session.

  Returns:

  This client session's instance for history requests, never changes during the session's lifetime.

• addHistoryEntry

  IAppHistoryEntry addHistoryEntry()

  Adds a new focus entry at the current location for this client session. The VirtualSpace and UI location is recorded to the previous and forward locations in the entry.

  The entry is added at the current index and will clear all forward operations at that point to the end, i.e. IAppHistory.clearForwardEntries() is called before adding the entry and moving the index forward by one (1).

  Once added, the history entry forward and backward information can be set or adjusted.

  Returns:

  The newly added history entry, null if history operations are currently in progress (i.e. a forward or backward history operation is running).

• getScreenWidth

  int getScreenWidth()

  Gets the current screen width.

  Returns:

  The current screen width, or zero if not initialized.

• getScreenHeight

  int getScreenHeight()

  Gets the current screen height.

  Returns:

  The current screen height, or zero if not initialized.

• getScreenSize

  Size getScreenSize()

  Gets the current screen size.

  Returns:

  The current screen size, zero width and/or height if not initialized.

• addScreenSizeListener

  boolean addScreenSizeListener(IScreenSizeListener listener)

  Adds a screen size listener for the client session. Calling this method multiple times with the same listener will have no effect (but to return false).

  Parameters:

  listener - The listener to add.

  Returns:

  true if the listener was added, false otherwise.

  Throws:

  NullPointerException - If the listener is null.

• removeScreenSizeListener

  boolean removeScreenSizeListener(IScreenSizeListener listener)

  Removes a screen size listener for the client session.

  Parameters:

  listener - The listener to remove.

  Returns:

  true if listener is successfully removed, false otherwise.

• isScreenOrientationLockSupported

  boolean isScreenOrientationLockSupported()

  Checks if screen orientation locking is supported or not.

  Returns:

  true if the functions to lock or unlock screen orientation are supported, false otherwise.

• addScreenOrientationListener

  boolean addScreenOrientationListener(IScreenOrientationListener listener)

  Adds a screen orientation listener for the client session. Calling this method multiple times with the same listener will have no effect (but to return false).

  Parameters:

  listener - The listener to add.

  Returns:

  true if the listener was added, false otherwise.

  Throws:

  NullPointerException - If the listener is null.

• removeScreenOrientationListener

  boolean removeScreenOrientationListener(IScreenOrientationListener listener)

  Removes a screen orientation listener for the client session.

  Parameters:

  listener - The listener to remove.

  Returns:

  true if listener is successfully removed, false otherwise.

• getScreenOrientation

  ScreenOrientation getScreenOrientation()

  Gets the current screen orientation.

  Returns:

  The orientation, ScreenOrientation.unknown if not supported.

• setScreenOrientation

  boolean setScreenOrientation(ScreenOrientation orientation)

  Locks the screen orientation.

  Note that there may be a delay in the orientation change after calling this method. This could be due to slow client connection, disconnected client or just due to device lag.

  Parameters:

  orientation - The orientation.

  Returns:

  true for success, false for not supported.

  Throws:

  IllegalArgumentException - If orientation is ScreenOrientation.unknown.

• unlockScreenOrientation

  boolean unlockScreenOrientation()

  Unlocks the screen orientation.

  Note that there may be a delay in the orientation change after calling this method. This could be due to slow client connection, disconnected client or just due to device lag.

  Returns:

  true for success, false for not supported.

• sendStat

  void sendStat(String event, DeviceParameter... params)

  Sends an event to the analytics engine of the client, which logs it under its name.

  The event is sent to the client at once, and what happens to it there is the client's matter. A Browser hands it to Google Analytics only while Analytics runs: the application has a Measurement ID and, where consent is asked, only after the user's consent. iiziRun hands it to Firebase Analytics per its "Usage statistics" switch. Any other client drops it.

  The names follow the rules of Google Analytics 4 and Firebase, with ONE normalisation that every sender applies the same way - this API, the Browser client's sink in iz/analytics.js and iiziRun's own events in init.js (CC-FIX-GA4-V5): a hyphen in the event name or in a parameter name becomes an underscore, so js-exception is sent as js_exception. What is sent then starts with a letter and holds letters, digits and underscores only, 40 characters at most, does not start with one of the reserved prefixes firebase_, google_ or ga_, and is not one of the event names Google reserves (session_start, first_visit, page_view, error and the others of its documented lists): a name that fails this is refused with one WARNING in the log naming it, and nothing is sent. At most 25 parameters are sent with an event. A value longer than 100 characters is cut to 100, with a WARNING in the log that names the parameter and never the value. A sensitive parameter and a parameter whose value is null are not sent, and their names are not checked.

  Parameters:

  event - The event name.

  params - Parameters to send, null values and sensitive parameters are ignored.

  Throws:

  IllegalArgumentException - If the event name or the name of a parameter to send is not valid, the message naming it, or if more than 25 parameters are to be sent. Nothing is sent then.

  NullPointerException - If the event name or a parameter is null.

• saveClientStorage

  boolean saveClientStorage(DeviceParameter... params)

  Saves values in the client's storage for the current app (CC-CLIENT-STORAGE-V5): the settings of an iiziRun device, the localStorage of a Browser or an installed web app. Until IIZI version 5 a Browser kept them in cookies, which travelled on every HTTP request of the application for nothing: the values travel over the WebSocket only, in the DevParams container of the client environment, and the server never reads them from a request. The items are DeviceParameter instances, the class keeping its historical name ("device parameter").

  Sensitive values are encrypted with a key kept on the server side. The encrypted data is padded and sent to the client and no key is used on the client side. Only the fingerprint of the server key used is included in the encrypted data. This means that the sensitive value is virtually undecipherable on the client side.

  A sensitive value is sealed to the application and to the device (CC-PWA-APPBOUND-DEVICE-PARAMS): it is bound to the App ID of this session and to the device UUID, so that a value one application saved cannot be read by another application of the server, nor on another device.

  Parameters:

  params - Items to save. A DeviceParameter value of null means that the item and its value is removed from storage. Upon return of this method, each DeviceParameter of params is updated with a new state. Possible states are DeviceParameter.State.SUCCESS, DeviceParameter.State.UNAVAILABLE, DeviceParameter.State.NOT_FOUND or DeviceParameter.State.ENCRYPT_ERROR.

  Returns:

  true for success of at least one item, false for failure (or no items to save). In case of functional failure (i.e. not if an item is not found), an error is logged in the server.

• getClientStorage

  boolean getClientStorage(DeviceParameter... params)

  Retrieves values from the client's storage for the current app (CC-CLIENT-STORAGE-V5). The values and states are filled in before the return of this method call. The state indicates success, some error or if the item is not found. The state for each DeviceParameter is either DeviceParameter.State.SUCCESS, DeviceParameter.State.NOT_FOUND, DeviceParameter.State.UNAVAILABLE or DeviceParameter.State.DECRYPT_ERROR.

  A sensitive value is read only when it was sealed for this application on this device (CC-PWA-APPBOUND-DEVICE-PARAMS): one sealed for another application of the server is a DeviceParameter.State.DECRYPT_ERROR with a WARNING in the server log naming both App IDs, one sealed on another device a DeviceParameter.State.DECRYPT_ERROR with a SEVERE, and one saved by a server before the application binding (v4 and earlier) is DeviceParameter.State.NOT_FOUND and removed from the device: ask the user for it again and save it anew.

  Parameters:

  params - The items to retrieve.

  Returns:

  true for success, false if the client's storage is not present. The return code is true if at least one item was successfully retrieved. If false is returned and the DevParams instance is not found in EnvProps for the client, an error is logged in the server.

• saveDeviceParameters

  @Deprecated default boolean saveDeviceParameters(DeviceParameter... params)

  Deprecated.

  Since IIZI version 5 (CC-CLIENT-STORAGE-V5): use saveClientStorage(DeviceParameter...). Kept so that an application built against version 4 keeps working.

  Saves parameters on the client device for the current app: the name of saveClientStorage(DeviceParameter...) before IIZI version 5, which it calls.

  Parameters:

  params - Parameters to save.

  Returns:

  true for success of at least one parameter, false otherwise.

• getDeviceParameters

  @Deprecated default boolean getDeviceParameters(DeviceParameter... params)

  Deprecated.

  Since IIZI version 5 (CC-CLIENT-STORAGE-V5): use getClientStorage(DeviceParameter...). Kept so that an application built against version 4 keeps working.

  Retrieves parameters from the client device for the current app: the name of getClientStorage(DeviceParameter...) before IIZI version 5, which it calls.

  Parameters:

  params - The parameters to retrieve.

  Returns:

  true for success, false if the client's storage is not present.

• triggerRemoteOpenWindow

  default boolean triggerRemoteOpenWindow(String url, String target)

  Triggers opening of a browser window on the client.

  Parameters:

  url - The URL to open.

  target - The target, null for _blank.

  Returns:

  true for success, false if the window cannot be opened because another window already is open or that the session is disposed of. In case of failure, any callback close listener will not be invoked.

• triggerRemoteOpenWindow

  @Deprecated default boolean triggerRemoteOpenWindow(String url, String target, Runnable closeListener)

  Deprecated.

  Use triggerRemoteOpenWindow(String, String, WindowOptions, IWindowCloseListener) instead.

  Triggers opening of a browser window on the client.

  Parameters:

  url - The URL to open.

  target - The target, null for _blank.

  closeListener - Callback to listen to close window, null for none.

  Returns:

  true for success, false if the window cannot be opened because another window already is open or that the session is disposed of. In case of failure, any callback close listener will not be invoked.

• triggerRemoteOpenWindow

  boolean triggerRemoteOpenWindow(String url, String target, WindowOptions options, IWindowCloseListener windowListener)

  Triggers opening of a browser window on the client.

  Parameters:

  url - The URL to open.

  target - The target, null for _blank.

  options - Options to use, null for "new tab" for a browser client.

  windowListener - Callback to listen to blocked or user close window, null for none. When "spawn mode" is used in the options, this parameter is ignored, i.e. as if set to null.

  Returns:

  true for success, false if the window cannot be opened because another window already is open or that the session is disposed of. In case of failure, any callback close listener will not be invoked.

• triggerRemoteCloseWindow

  default boolean triggerRemoteCloseWindow()

  Triggers closing of the window on the client that was opened with triggerRemoteOpenWindow.

  Returns:

  true for success, false if no open window is present.

• triggerRemoteCloseWindow

  boolean triggerRemoteCloseWindow(boolean ignoreCallbackListener)

  Triggers closing of the window on the client that was opened with triggerRemoteOpenWindow.

  Parameters:

  ignoreCallbackListener - Flag to ignore calling a potential callback listener.

  Returns:

  true for success, false if no open window is present.

• restartRemoteClient

  void restartRemoteClient()

  Restarts the remote client. This is done without asking anything: it will just restart the iiziRun or browser by disconnecting from server and reloading the page directly. For iiziRun Developer/Custom sessions, this will bring up that interface.