Getting Started

Configures and initializes the SDK. Must be called once before using other methods. REST requests go through gateway.cmscure.com and WebSocket connects to wss://app.cmscure.com.

Parameters:

• projectId (string): Required. Your unique Project ID from the CMSCure dashboard.
• apiKey (string): Required. Your API Key for authenticating requests.
• projectSecret (string): Optional. Enables real-time WebSocket updates via Socket.IO.
• defaultLanguage (string): Optional. Preferred language code (e.g., 'en'). Falls back to browser language detection.

Returns:

Promise<void> — Resolves when authentication and initial sync are complete.

The primary API for reactive UI bindings. Subscribes to a content reference and calls the listener immediately with the current value, then again whenever the value changes (language switch, real-time update, sync). Returns an unsubscribe function.

Parameters:

• reference (string): Content reference: 'tab:key' (translations), 'color:key', 'image:key', 'store:identifier', 'meta:languages', or 'meta:language'.
• listener (function): Callback receiving (value, { reason }) on every update.
• options.defaultValue (any): Optional. Fallback value if content is not yet cached.

Returns:

() => void — Call to unsubscribe and stop receiving updates.

Synchronously resolves any content reference string. Supports translations ('tab:key'), colors ('color:key'), images ('image:key'), data stores ('store:name'), and metadata ('meta:language', 'meta:languages').

Parameters:

• reference (string): The content reference to resolve.
• defaultValue (any): Optional fallback if the content is not found.

Returns:

any — The resolved value (string, array, etc.) or the defaultValue.

Retrieves a localized string for the specified key and tab in the current language. Returns cached value immediately. Automatically subscribes the tab for syncing and real-time updates.

Parameters:

• key (string): The key for the desired string (e.g., 'welcome_title').
• tab (string): The tab/screen name (e.g., 'home_screen').
• defaultValue (string): Optional fallback if the key is not found.

Returns:

string | null — The localized string or null/defaultValue.

Retrieves a color hex value for the specified global color key. Automatically fetches all colors on first access.

Parameters:

• key (string): The color key (e.g., 'primary_color').
• defaultValue (string): Optional fallback hex value.

Returns:

string | null — The color hex value (e.g., '#3b82f6') or defaultValue.

Retrieves a CDN-optimized image URL for the specified image key. Automatically fetches all images on first access.

Parameters:

• key (string): The image key (e.g., 'hero_banner').
• defaultValue (string): Optional fallback URL.

Returns:

string | null — The image URL or defaultValue.

Retrieves items from a Data Store. Each item has _id, data (field values), createdAt, updatedAt, and optional ctaUrl. Field values in data may be plain types or localized objects.

Parameters:

• apiIdentifier (string): The API identifier of the Data Store (e.g., 'feature_products').
• defaultValue (Array): Optional fallback. Defaults to [].

Returns:

Array — Array of data store items.

Changes the active language. Triggers re-sync of all subscribed content and notifies all observe() listeners with updated values.

Parameters:

• languageCode (string): Language code (e.g., 'en', 'fr', 'ar').

Returns:

Promise<void>

Returns the currently active language code.

Returns:

string — Current language code (e.g., 'en').

Returns all language codes configured in your CMSCure project.

Returns:

string[] — Array of available language codes.

Manually triggers a full content re-sync with the CMSCure servers. All observe() listeners will be notified with fresh values.

Returns:

Promise<void>

Listens for content update events. The SDK extends EventTarget, so standard addEventListener/removeEventListener work. Fires on sync completion, language changes, and real-time pushes.

Parameters:

• handler (function): Receives a CustomEvent with event.detail containing { reason, timestamp, ... }.

Initializes internal storage and resources. Must be called once before configure(), typically in Application.onCreate().

Parameters:

• context (Context): Application context.

Configures the SDK with project credentials. Must be called after init(). Triggers authentication, initial sync, and Socket.IO connection.

Parameters:

• context (Context): Application context.
• projectId (String): Your Project ID from the CMSCure dashboard.
• apiKey (String): Your API Key for authenticating requests.
• projectSecret (String): Project Secret for Socket.IO real-time handshake.
• enableAutoRealTimeUpdates (Boolean): Optional. Enable automatic real-time sync. Defaults to true.

Synchronously retrieves a translation for a specific key and tab in the current language. Returns empty string if not found. Auto-subscribes the tab for real-time updates.

Parameters:

• forKey (String): The translation key (e.g., 'welcome_title').
• inTab (String): The tab/screen name (e.g., 'home_screen').

Returns:

String — The translated string or empty string.

Synchronously retrieves a hex color string for a given key. Auto-subscribes to color updates on first access.

Parameters:

• forKey (String): The color key (e.g., 'primary_color').

Returns:

String? — Hex color (e.g., "#3b82f6") or null.

Synchronously retrieves a CDN image URL for a given global image key. Auto-subscribes to image updates on first access.

Parameters:

• forKey (String): The image key (e.g., 'hero_banner').

Returns:

String? — Image URL or null.

Synchronously retrieves items from a Data Store. Each DataStoreItem has id, data (Map<String, JSONValue>), createdAt, updatedAt, and typed accessors: .string(key), .int(key), .double(key), .bool(key), .ctaURL.

Parameters:

• forIdentifier (String): The API identifier of the Data Store.

Returns:

List<DataStoreItem> — Array of data store items with typed field accessors.

Sets the active language. Triggers full content re-sync when changed.

Parameters:

• languageCode (String): Language code (e.g., 'en', 'ar').
• force (Boolean): Optional. Force refresh even if unchanged. Defaults to false.

Returns the currently active language code.

Returns:

String — Current language code (e.g., "en").

Asynchronously fetches available language codes. Calls completion on the main thread.

Parameters:

• completion ((List<String>) → Unit): Callback receiving the list of available language codes.

Manually triggers sync for a specific tab. Use constants COLORS_UPDATED or IMAGES_UPDATED for specialized syncs.

Parameters:

• screenName (String): Tab name, or CMSCureSDK.COLORS_UPDATED / IMAGES_UPDATED.
• completion (((Boolean) → Unit)?): Optional callback with success status.

Kotlin Coroutines SharedFlow that emits screen/store identifiers when content updates. Collect in a coroutine scope to react to updates. Special values: ALL_SCREENS_UPDATED, COLORS_UPDATED, IMAGES_UPDATED.

Returns:

SharedFlow<String> — Reactive stream of update identifiers.

Wrap your app root with this provider. It initializes the SDK, loads colors and images, and provides context for all hooks. Shows a loading state during initialization.

Parameters:

• projectId (string): Your Project ID from the CMSCure dashboard.
• apiKey (string): Your API Key.
• projectSecret (string): Project Secret for real-time updates.
• enableAutoRealTimeUpdates (boolean): Optional. Enable auto real-time sync. Defaults to true.

Returns a reactive translated string that auto-updates on content or language changes. Auto-subscribes the tab on first access.

Parameters:

• key (string): Translation key (e.g., 'welcome_title').
• tab (string): Tab/screen name (e.g., 'home_screen').
• defaultValue (string): Optional fallback text.

Returns:

string — Reactive translated string.

Returns a reactive hex color string that auto-updates on content changes.

Parameters:

• key (string): Color key (e.g., 'primary_color').
• defaultValue (string): Optional fallback hex (e.g., '#007AFF'). Defaults to '#000000'.

Returns:

string — Hex color string (e.g., "#3b82f6").

Returns a reactive image URL. If tab is provided, retrieves from tab translations instead of global images.

Parameters:

• key (string): Image key (e.g., 'hero_banner').
• tab (string | null): Optional tab for tab-based images.
• defaultValue (string): Optional fallback URL.

Returns:

string | null — Image URL or null.

Returns reactive data store items with loading state. Initial sync runs once per identifier; subsequent updates come from real-time events. Items have typed accessors: .string(key), .int(key), .double(key), .bool(key), .ctaURL.

Parameters:

• apiIdentifier (string): The Data Store API identifier.

Returns:

{ items: DataStoreItem[], isLoading: boolean }

Returns reactive language info that updates on language changes. Includes direction, flag emoji, and human-readable name.

Returns:

{ code: string, isRTL: boolean, flag: string, displayName: string }

Renders a CMS-managed image. Wraps React Native's Image component. Returns null if url is falsy.

Parameters:

• url (string | null): The image URL (typically from useCureImage).
• style (StyleProp<ImageStyle>): Optional style prop for the image.

Configures the SDK with your project credentials and server details. This MUST be called once, early in your application's lifecycle (e.g., in AppDelegate or App struct initializer). It triggers internal setup, including legacy authentication and socket connection attempts.

Parameters:

• projectId (String): Your unique Project ID from the CMSCure dashboard.
• apiKey (String): Your API Key for authenticating API requests.
• projectSecret (String): Your Project Secret, used for legacy encryption and socket handshake.
• serverUrlString (String): Optional. Base URL for the CMSCure API. Defaults to 'https://app.cmscure.com'.
• socketIOURLString (String): Optional. URL for the CMSCure Socket.IO server. Defaults to 'wss://app.cmscure.com'.

Controls whether detailed SDK diagnostic messages are printed to the console. Defaults to true. Set to false for production builds.

The interval (in seconds) at which the SDK periodically polls for content updates if socket connection is unavailable or as a fallback. Defaults to 300 seconds (5 minutes). Min: 60s, Max: 600s.

Sets the current active language for retrieving translations. Persists the preference and triggers content updates for the new language.

Parameters:

• language (String): The language code to set (e.g., "en", "fr").
• force (Bool): Optional. If true, forces updates even if the language is unchanged. Defaults to false.
• completion ((() -> Void)?): Optional. A closure called after all tabs have attempted to sync for the new language.

Retrieves the currently active language code.

Returns:

The current language code (e.g., "en").

Asynchronously fetches the list of available language codes from the backend. Falls back to languages inferred from the local cache if the server request fails.

Parameters:

• completion (([String]) -> Void): A closure called with an array of language code strings.

Retrieves a translation for a specific key within a given tab (screen name), using the currently set language. Returns an empty string if the translation is not found in the cache.

Parameters:

• key (String): The key for the desired translation.
• screenName (String): The name of the tab/screen where the translation key is located.

Returns:

The translated string for the current language, or an empty string if not found.

Retrieves a color hex string for a given global color key. Colors are typically stored in a special tab named `__colors__`. Returns nil if the color key is not found.

Parameters:

• key (String): The key for the desired color (e.g., "primary_brand_color").

Returns:

The color hex string (e.g., "#RRGGBB") or nil if not found.

Retrieves a URL for an image associated with a given key and tab, in the current language. The underlying translation for the key is expected to be a valid URL string. Returns nil if not found, empty, or not a valid URL.

Parameters:

• key (String): The key for the desired image URL.
• screenName (String): The name of the tab/screen where the image URL key is located.

Returns:

A URL object if a valid URL string is found, otherwise nil.

Manually triggers a network fetch for the latest content of a specific screen name (tab). Updates the local cache and notifies handlers upon completion.

Parameters:

• screenName (String): The name of the tab/screen to synchronize.
• completion ( (Bool) -> Void): A closure called with true if synchronization was successful (even if no new data), false otherwise.

Checks if the specified tab's content exists in the local cache, indicating it has been synced at least once and has data.

Parameters:

• tabName (String): The name of the tab/screen to check.

Returns:

True if the tab has cached content, false otherwise.

Clears all cached data from memory and disk, including translations, colors, known tabs list, and any persisted legacy configuration. Also resets the runtime SDK configuration, requiring `configure()` to be called again for subsequent use. Stops active socket connections and polling.

Attempts to establish or re-establish the Socket.IO connection if the SDK is configured and necessary credentials (like projectSecret for legacy handshake) are available. Called automatically after successful configuration and when the app becomes active.

Explicitly disconnects the Socket.IO client and releases related resources.

Returns true if the Socket.IO client is currently connected to the server, false otherwise.

Returns:

A Boolean indicating the connection status.

Registers a handler to be called when translations for a specific screen name (tab) are updated. The handler is called immediately with cached data upon registration and then subsequently when that tab's content changes due to sync or socket events.

Parameters:

• screenName (String): The name of the tab/screen to observe.
• handler (([String: String]) -> Void): A closure that receives a dictionary of key-value translations for the current language.

An ObservableObject that provides a reactive translated string. Initialize with a key and tab name. Access the string via its `value` property.

An ObservableObject that provides a reactive `SwiftUI.Color?`. Initialize with a color key (from the `__colors__` tab). Access the color via its `value` property.

An ObservableObject that provides a reactive `URL?` for an image. Initialize with a key and tab name. Access the URL via its `value` property, typically used with `AsyncImage`.

A convenience extension on `String` to directly get a translation within SwiftUI views. This also triggers view updates when the underlying translation changes.

Parameters:

• tab (String): The name of the tab/screen where the key is located.

Returns:

The translated string.

An initializer for `SwiftUI.Color` that attempts to create a color from a hexadecimal string (e.g., "#RRGGBB" or "RRGGBB").

Parameters:

• hex (String?): The hexadecimal color string.

Returns:

A `SwiftUI.Color` instance, or `nil` if the hex string is invalid.

Defines common errors encountered by the SDK, such as configuration issues, network problems, decoding failures, or sync errors. Conforms to `LocalizedError` for user-friendly descriptions.