Documentation

Getting started

CMSCure delivers text, colors, images and structured data to your live apps. You change content in the dashboard and your apps show it within seconds, with no new build or store release.

Changing a label, a banner image or a button color normally means a code change, a build, a review and a release. With CMSCure, developers, designers, product managers and marketers can make those changes themselves and publish them right away.

Add the SDK to your iOS, Android, React Native, Flutter, Unity or web app. Define your content keys in the dashboard. Then update text, colors, images, numbers, flags and more whenever you need to.

This guide covers the core concepts and the setup for each platform.

How it works

  1. 1

    Set up the dashboard

    • Create tabs (for example home_screen, settings, product_details). A tab groups related content.
    • Add keys inside each tab (for example welcome_title, welcome_subtitle, cta_button). A key identifies one piece of content.
    • Add a value for each key in every language you support.
    • Optionally add global colors, images and data stores.
    • Publish your changes.
  2. 2

    Add the SDK

    Install the SDK for your platform:

    • iOS: Swift Package Manager
    • Android: Gradle with JitPack
    • React Native: npm with native linking
    • Web: npm or CDN

    Initialize it early in your app's lifecycle with the Project ID, API key and project secret from the dashboard.

    Swift
    // Swift (iOS)
    import CMSCureSDK
    Cure.shared.configure(
        projectId: "YOUR_PROJECT_ID",
        apiKey: "YOUR_API_KEY",
        projectSecret: "YOUR_PROJECT_SECRET"
    )
    JavaScript
    // JavaScript (Web)
    const cure = new CMSCureSDK();
    await cure.configure({
        projectId: 'YOUR_PROJECT_ID',
        apiKey: 'YOUR_API_KEY',
        projectSecret: 'YOUR_PROJECT_SECRET',
        defaultLanguage: 'en'
    });
  3. 3

    Show content

    • SwiftUI: use reactive wrappers such as @StateObject var myText = CureString("key", tab: "tab") or the "key".cure(tab: "tab") extension.
    • JavaScript: use cure.observe('tab:key', callback) for live bindings, or cure.translation(key, tab) for direct access.
    • Other platforms: each SDK has matching wrappers, hooks or fetch methods.
    • The SDK caches content and fetches the latest version for you.
  4. 4

    Get real time updates

    • When you publish, every connected SDK receives the change over WebSocket.
    • UI bound to CMSCure updates on its own. No polling or manual refresh.
  5. 5

    Ship content without a release

    Text, color, image and data store changes are live in your app seconds after you publish. No new build and no store review.

Core concepts

These are the building blocks you work with in CMSCure:

  • Tabs: containers for your content, often one per app screen or feature (for example "home_screen", "user_profile", "settings"). You create them in the CMSCure dashboard.
  • Keys: unique names inside a tab for single content items such as text, numbers or booleans (for example "welcome_title", "welcome_subtitle", "cta_button").
  • Values and translations: each key holds a value per language. The SDK returns the value for the active language. On the web, use cure.observe('tab:key', callback) for live updates.
  • Colors and images: global colors (for example color:primary_color) and images (for example image:hero_banner) are managed separately and read through their own methods or reactive bindings.
  • Data stores: structured collections of items, such as products or features. Each item has an _id, data (field values) and an optional ctaUrl. Field values can be plain types or localized objects.
  • SDK configuration: initialize each platform SDK once with your Project ID, API Key and, optionally, Project Secret (turns on real time WebSocket updates).
  • Real time sync: WebSockets push dashboard changes to connected apps right away. Reactive UI pieces (SwiftUI CureString, web observe()) update on their own.
  • Caching: content is cached on the device (localStorage on the web, UserDefaults on iOS). Rate limiting prevents duplicate API calls: each resource syncs at most once every 2 seconds.

General SDK pseudocode

// --- Initialization & Configuration (Early in App Lifecycle) ---

// Swift (iOS)
// Cure.shared.configure(
//     projectId: "YOUR_PROJECT_ID",
//     apiKey: "YOUR_API_KEY",
//     projectSecret: "YOUR_PROJECT_SECRET"
// )

// JavaScript (Web)
// const cure = new CMSCureSDK();
// await cure.configure({
//   projectId: 'YOUR_PROJECT_ID',
//   apiKey: 'YOUR_API_KEY',
//   projectSecret: 'YOUR_PROJECT_SECRET',  // enables real-time updates
//   defaultLanguage: 'en'
// });


// --- Fetching Content ---

// Swift (reactive SwiftUI wrappers)
// @StateObject var welcomeText = CureString("welcome_title", tab: "home_screen")
// @StateObject var primaryColor = CureColor("primary_button_bg")
// Text(welcomeText.value)

// JavaScript (reactive observe bindings)
// cure.observe('home_screen:welcome_title', value => {
//   document.getElementById('title').textContent = value;
// }, { defaultValue: 'Welcome' });
//
// cure.observe('color:primary_color', value => {
//   document.documentElement.style.setProperty('--primary', value);
// });
//
// cure.observe('image:hero_banner', url => {
//   document.getElementById('hero').src = url;
// });

// JavaScript (direct access)
// const title = cure.translation('welcome_title', 'home_screen', 'Welcome');
// const color = cure.color('primary_color', '#3B82F6');
// const banner = cure.image('hero_banner');
// const products = cure.dataStore('feature_products', []);


// --- Data Stores ---
// Structured collections of items (e.g., products, features).
// Each item has an `_id`, `data` (field values), and optional `ctaUrl`.
// Field values may be plain types or localized objects.

// JavaScript
// cure.observe('store:feature_products', items => {
//   items.forEach(item => {
//     const title = item.data?.title;  // plain string or {en:"…", ar:"…"}
//     const price = item.data?.price;  // number
//   });
// });


// --- Language Switching ---

// Swift
// Cure.shared.setLanguage("fr")

// JavaScript
// await cure.setLanguage('fr');
// All observe() bindings update automatically when language changes.


// --- Real-time Updates ---
// SDKs connect via WebSocket when projectSecret is provided.
// Reactive wrappers (CureString, observe()) update UI automatically.
// No polling or manual refresh needed.

// JavaScript event listener:
// cure.addEventListener('contentUpdated', event => {
//   console.log('Content updated:', event.detail.reason);
// });

iOS SDK

Native Swift SDK for iOS 14+ and macOS. It delivers translations, colors, images and structured data stores from your CMSCure dashboard and updates in real time over WebSocket.

iOS 14+SwiftUIUIKit

1. Installation

Add the SDK with Swift Package Manager in Xcode, using the repository URL shown in the code panel. Dependencies (Socket.IO, Kingfisher) resolve automatically.

2. Configuration

Initialize the SDK once at app launch. Get your credentials from app.cmscure.com → Project Settings. Real time updates are on by default.

3. Key features

  • Translations: translation(for:inTab:) for multi language content with RTL support.
  • Colors: colorValue(for:) for dynamic theme colors, with built in Color(hex:) and UIColor(hex:).
  • Images: Cure.ManagedImage (SwiftUI) or imageURL(forKey:) (UIKit with Kingfisher).
  • Data stores: dataStoreRecords(for:) with typed accessors, visibility control and CTA URLs.

4. SwiftUI reactive wrappers

Use @StateObject wrappers so your UI updates when CMS content changes. No manual observers needed.

  • CureString("key", tab: "tab"): reactive translated text
  • CureColor("key"): reactive SwiftUI Color
  • CureDataStore(apiIdentifier: "id"): reactive data store records
  • "key".cure(tab: "tab"): inline String extension

5. UIKit integration

Implement cmsContentDidUpdate() on any view controller. The SDK calls it when content changes. Use Kingfisher to load images.

6. Language management

50+ built in languages with RTL support, flag emojis and display name helpers.

  • setLanguage("ar") and getLanguage()
  • languageDirection: use .isRTL to adapt the layout
  • CureLanguageDisplay.flag(for:) and .displayName(for:)
  • availableLanguages { codes in … }

7. Data store visibility

You can hide or show items from the dashboard. Hidden items are left out of SDK responses, so there is no filtering to do in the app. Changes apply after you publish.

Get started in under 5 minutes

The SDK repository includes full working examples for SwiftUI and UIKit.

Integration examples

# Swift Package Manager (Xcode)
# File → Add Packages…
# Paste the repository URL:

https://github.com/cmscure/ios-sdk.git

# Dependency rule: Up to Next Major Version
# Click Add Package: SocketIO & Kingfisher resolve automatically.

Android SDK

Native Kotlin SDK for Android 7+ (API 24). It delivers translations, colors, images and structured data stores from your CMSCure dashboard and updates in real time over WebSocket. Works with Jetpack Compose and classic XML layouts.

Jetpack ComposeXML widgetsKotlin

1. Installation

Add the JitPack repository to your settings.gradle.kts, then add the SDK dependency to your module level build.gradle.kts. Every tagged release on GitHub is available on JitPack right away, with no extra packaging. Coil handles image loading in both the Compose and XML helpers.

2. Configuration

Initialize the SDK once in your custom Application class. Get your credentials from app.cmscure.com → Project Settings. Add the INTERNET permission to your AndroidManifest.xml. Real time updates are on by default through enableAutoRealTimeUpdates.

3. Key features

  • Translations: Cure.translation(forKey, inTab) for multi language content with RTL support.
  • Colors: Cure.colorValue(forKey) returns hex colors from the dashboard, parsed to Color.
  • Images: CureImage (Compose) or CureImageView (XML) for managed images via Coil.
  • Data stores: Cure.getStoreItems(forIdentifier) with typed accessors for strings, numbers, booleans and CTA URLs.

4. Compose reactive helpers

Built in Compose helpers react to CMS changes through contentUpdateFlow. No manual observers or coroutine boilerplate: just replace your literals.

  • rememberCureString("key", "tab", "default"): reactive translated text
  • rememberCureColor("key", Color.Gray): reactive Compose Color
  • cureDataStore("apiIdentifier"): reactive data store records
  • CureImage(key = "hero_banner"): managed image in one line
  • CureText(key = "title", tab = "home"): managed text in one line
  • CureLayoutDirection { /* content */ }: automatic RTL layout wrapping

5. XML widget integration

Drop CMS backed widgets into your XML layouts. They subscribe to real time updates when cureAutoStart="true" is set, or you can control them with bind() and unbind().

  • CureTextView: app:cureKey, app:cureTab, app:cureDefault
  • CureImageView: app:cureImageKey for global images
  • CureColorView: app:cureColorKey for dynamic backgrounds

6. Language management

50+ built in languages with RTL support, flag emojis and display name helpers. Changing the language triggers a full re-sync.

  • Cure.setLanguage("ar") and Cure.getLanguage()
  • LanguageDirection.direction(code): use .isRTL to adapt the layout
  • CureLanguageDisplay.flag(code) and .displayName(code)
  • availableLanguages { codes -> … }

7. Data store records

A data store is a collection of structured records. Each record has typed fields that you read with helper methods on DataStoreItem. Hidden items are left out of SDK responses, so there is no filtering to do in the app.

  • item.string("field"): returns String?
  • item.int("field"), item.double("field"), item.bool("field")
  • item.ctaURL: optional CTA or deep link URL
  • item.id: unique identifier for list keys

8. Offline caching and manual sync

Translations, colors, images and data stores are saved to disk. Cold starts show the last known content immediately. For manual control, use the sync APIs:

  • Cure.sync("screen_name"): sync one screen or tab
  • Cure.syncStore("api_id"): sync one data store
  • Cure.sync(CMSCureSDK.COLORS_UPDATED): sync global colors
  • CMSCureSDK.contentUpdateFlow: Kotlin Flow that emits on every content change

Get started in under 5 minutes

The SDK repository includes full working sample apps for Jetpack Compose and XML.

Integration examples

// settings.gradle.kts: add JitPack repository
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven(url = "https://jitpack.io")
    }
}

// app/build.gradle.kts: add SDK + Coil
dependencies {
    implementation("com.github.cmscure:android-sdk:1.0.19")
    implementation("io.coil-kt:coil-compose:2.5.0")
}

React Native SDK

React Native SDK for iOS 14+ and Android 7+ (API 24). It delivers translations, colors, images and structured data stores from your CMSCure dashboard and updates in real time over WebSocket. Use the reactive hooks API, or the imperative API for full control.

React Native 0.71+iOS 14+Android API 24+TypeScript

1. Installation

Install with npm or yarn. On iOS, add use_frameworks! :linkage => :static to your Podfile for Swift pod compatibility, then run pod install. On Android, set minSdkVersion to at least 24. The library links automatically on both platforms.

2. Configuration

Wrap your app in <CMSCureProvider>. It initializes the SDK, syncs colors and images, and provides context to all hooks. Get your credentials from app.cmscure.com → Project Settings. Real time updates are on by default.

3. Key features

  • Translations: useCureString(key, tab) for multi language content with RTL support.
  • Colors: useCureColor(key) returns hex colors from the dashboard.
  • Images: useCureImage(key) returns CMS managed image URLs, rendered with the <CureSDKImage> component.
  • Data stores: useCureDataStore(id) with typed accessors for strings, numbers, booleans and CTA URLs.

4. Hooks API

The built in hooks react to CMS changes over WebSocket, so you do not need observers or subscriptions. Use every hook inside <CMSCureProvider>.

  • useCureString("key", "tab", "default"): reactive translated text
  • useCureColor("key", "#007AFF"): reactive hex color string
  • useCureImage("key"): reactive image URL
  • useCureDataStore("apiIdentifier"): reactive data store with { items, isLoading }
  • useCureLanguage(): current language code, RTL flag, flag emoji and display name
  • <CureSDKImage url={url} />: CMS managed image component in one line

5. Imperative API

The Cure object gives direct access to every SDK function. Use it outside hooks, for manual control, or in code that is not React.

  • Cure.translation(key, tab): async translation lookup
  • Cure.colorValue(key) and Cure.imageURL(key)
  • Cure.getStoreItems(id) and Cure.syncStore(id)
  • Cure.setLanguage(code), Cure.getLanguage(), Cure.availableLanguages()

6. Language management

80+ built in languages with RTL support, flag emojis and display name helpers. Changing the language triggers a full re-sync and every hook re-renders.

  • Cure.setLanguage("ar") and Cure.getLanguage()
  • LanguageDirection.direction(code): returns "RTL" or "LTR" to adapt the layout
  • LanguageDirection.isRTL(code): boolean RTL check (11+ RTL languages)
  • CureLanguageDisplay.flag(code) and .displayName(code)

7. Data store records

A data store is a collection of structured records. Each record has typed fields that you read with helper methods. Hidden items are left out of SDK responses.

  • item.string("field"): returns a localized string or null
  • item.int("field"), item.double("field"), item.bool("field")
  • item.ctaURL: optional CTA or deep link URL
  • item.id: unique identifier for list keys

8. Native performance and caching

The core runs natively: Swift on iOS (Kingfisher for images) and Kotlin on Android (Coil for images). All content is saved to disk, so cold starts show the last known content immediately. For manual control, use the sync APIs:

  • Cure.sync("screen_name"): sync one screen or tab
  • Cure.syncStore("api_id"): sync one data store
  • CMSCureContentUpdate: NativeEventEmitter event that fires on every content change

Get started in under 5 minutes

The SDK includes two full working examples: one with hooks and one with the imperative API.

Integration examples

# Install the SDK via npm or yarn
npm install @cmscure/react-native-cmscure-sdk
# --- or ---
yarn add @cmscure/react-native-cmscure-sdk

# iOS only: install CocoaPods dependencies
cd ios && pod install && cd ..

# Important: Add to your ios/Podfile inside the target block:
#   use_frameworks! :linkage => :static
#
# Android: Ensure minSdkVersion is at least 24 in
#   android/build.gradle

JavaScript SDK

The official CMSCure JavaScript SDK brings managed content, multiple languages and live updates to your web apps. It works with React, Next.js, Vue, Angular, Svelte and plain JavaScript.

Official SDKProduction readyTypeScript

1. Installation

Install the SDK from npm:

# Using npm
npm install @cmscure/javascript-sdk

# Using Yarn
yarn add @cmscure/javascript-sdk

# Using pnpm
pnpm add @cmscure/javascript-sdk

Or load it from a CDN in plain HTML and JavaScript projects:

<script src="https://cdn.jsdelivr.net/npm/@cmscure/javascript-sdk@latest/dist/cmscure.umd.min.js"></script>

2. Project setup

Get your credentials from your CMSCure dashboard and initialize the SDK in your app's entry point.

3. Key features

  • Translations: cure.observe('tab:key', callback) binds multi language content.
  • Colors: cure.observe('color:name', callback) for theme and brand colors.
  • Images: cure.observe('image:key', callback) for images served from a CDN.
  • Data stores: cure.observe('store:name', callback) for structured collections.
  • Direct access: cure.translation(key, tab), cure.color(key), cure.image(key), cure.dataStore(name).
  • Unified resolver: cure.resolve('tab:key') reads any content type with one method.

4. Multiple languages

The SDK detects the browser language and lets you switch languages at any time.

  • Language detection: uses the browser language, with a configurable defaultLanguage.
  • Switching: after cure.setLanguage('fr'), every observe() binding updates.
  • Language list: cure.getAvailableLanguages() and cure.getLanguage().
  • RTL support: detect RTL languages and change the layout direction.

Manage all your app content from the CMSCure dashboard and it updates in your live app.

5. Performance and reliability

Built for production, with fast content delivery and safe fallbacks.

  • CDN: API requests go through gateway.cmscure.com, real time updates through wss://app.cmscure.com.
  • Rate limiting: each resource syncs at most once every 2 seconds, which prevents duplicate API calls and 429 errors.
  • Persistent cache: content is kept in localStorage across browser sessions and refreshed when it changes.
  • Fallbacks: every method accepts a defaultValue.

Ready to start?

Create a free CMSCure account and manage your app content in minutes.

Framework examples

# Install via npm
npm install @cmscure/javascript-sdk

# Or via yarn
yarn add @cmscure/javascript-sdk

# Or via CDN (no installation needed)
# <script src="https://cdn.jsdelivr.net/npm/@cmscure/javascript-sdk@latest/dist/cmscure.umd.min.js"></script>

API reference

Detailed API references for every CMSCure SDK. Method signatures differ by platform, but tabs, keys and real time updates work the same way everywhere.

JavaScript SDK API (@cmscure/javascript-sdk)

The JavaScript SDK provides a modern, Promise-based API for web applications. Compatible with vanilla JavaScript, React, Next.js, Vue, Angular, and other frameworks.

What is new in v1.4.7

  • Reactive observe() bindings: one call per UI element, updates on content or language changes.
  • Rate limiting: each resource syncs at most once every 2 seconds, which prevents 429 errors.
  • Data store field resolver: handles both plain values and localized objects ({en:"…", ar:"…"}).
  • Persistent localStorage cache: cached content loads instantly across browser sessions.
  • Real time WebSocket sync: live updates over Socket.IO when a project secret is provided.
// Installation
npm install @cmscure/javascript-sdk

// Or CDN
// <script src="https://cdn.jsdelivr.net/npm/@cmscure/javascript-sdk@latest/dist/cmscure.umd.min.js"></script>

// Usage
import CMSCureSDK from '@cmscure/javascript-sdk';
const cure = new CMSCureSDK();

Configuration

await cure.configure({ projectId, apiKey, projectSecret?, defaultLanguage? })

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.

Reactive bindings (primary API)

cure.observe(reference, listener, options?)

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.

cure.resolve(reference, defaultValue?)

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.

Direct content access

cure.translation(key, tab, 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.

cure.color(key, 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.

cure.image(key, 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.

cure.dataStore(apiIdentifier, 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.

Language management

cure.setLanguage(languageCode)

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>

cure.getLanguage()

Returns the currently active language code.

Returns

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

cure.getAvailableLanguages()

Returns all language codes configured in your CMSCure project.

Returns

string[] Array of available language codes.

Synchronization and events

cure.refresh()

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

Returns

Promise<void>

cure.addEventListener('contentUpdated', handler)

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, ... }.

Data store field access

Items from dataStore() keep their fields under item.data. Values can be plain types or localized objects. Use a helper: const v = item.data?.title; typeof v === "object" ? v[cure.getLanguage()] : v

Android SDK API (com.github.cmscure:android-sdk)

The Android SDK provides synchronous content access with Kotlin Coroutines Flow for reactive updates. Supports both Jetpack Compose and traditional Android Views.

// build.gradle (project)
maven { url = uri("https://jitpack.io") }

// build.gradle (module)
implementation("com.github.cmscure:android-sdk:1.0.19")

// Access via singleton
import com.cmscure.sdk.CMSCureSDK
typealias Cure = CMSCureSDK

Configuration

Cure.init(context: Context)

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

Parameters

  • context Context: Application context.
Cure.configure(context, projectId, apiKey, projectSecret, enableAutoRealTimeUpdates?)

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.

Content access

Cure.translation(forKey: String, inTab: String) → String

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.

Cure.colorValue(forKey: String) → 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.

Cure.imageURL(forKey: String) → String?

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.

Cure.getStoreItems(forIdentifier: String) → List<DataStoreItem>

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.

Language management

Cure.setLanguage(languageCode: String, force: Boolean = false)

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.
Cure.getLanguage() → String

Returns the currently active language code.

Returns

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

Cure.availableLanguages(completion: (List<String>) → Unit)

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

Parameters

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

Synchronization and real time

Cure.sync(screenName: String, completion: ((Boolean) → Unit)?)

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.
Cure.contentUpdateFlow → SharedFlow<String>

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.

Jetpack Compose

Use these compose helpers inside @Composable functions for reactive UI bindings.

HelperDescription
rememberCureString(key, tab, default)Reactive translated string
rememberCureColor(key, default)Reactive Color from hex key
rememberCureImageUrl(key, tab?, default?)Reactive image URL
cureDataStore(apiIdentifier)Reactive State<List<DataStoreItem>>
CureText(key, tab, ...)Drop in Text composable
CureImage(key, tab?, ...)Drop in AsyncImage composable
CureBackground(key, ...)Box with a CMS managed background color
CureLayoutDirection { content }Auto RTL/LTR direction wrapper

Android view components

Use these views in classic XML layouts.

ViewXML attributes
CureTextViewapp:cureKey, app:cureTab, app:cureDefault
CureImageViewapp:cureImageKey, app:cureImageTab
CureColorViewapp:cureColorKey, app:cureColorDefault

React Native SDK API (@cmscure/react-native-cmscure-sdk)

The React Native SDK provides React hooks for reactive UI bindings and an imperative Cure object for direct access. All hooks auto-update on content and language changes.

npm install @cmscure/react-native-cmscure-sdk

import { Cure, CMSCureProvider, useCureString, useCureColor,
  useCureImage, useCureDataStore, useCureLanguage,
  CureSDKImage } from '@cmscure/react-native-cmscure-sdk';

Provider

<CMSCureProvider config={{ projectId, apiKey, projectSecret, enableAutoRealTimeUpdates? }}>

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.

Hooks (primary API)

useCureString(key, tab, defaultValue?) → string

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.

useCureColor(key, defaultValue?) → 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").

useCureImage(key, tab?, defaultValue?) → string | null

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.

useCureDataStore(apiIdentifier) → { items, isLoading }

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 }

useCureLanguage() → { code, isRTL, flag, displayName }

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 }

Components

<CureSDKImage url={url} style={style} />

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.

Imperative API

The Cure object gives direct access outside hooks or in code that is not React.

MethodDescription
await Cure.translation(key, tab)Async translation lookup
await Cure.colorValue(key)Async color hex
await Cure.imageURL(key)Async image URL
await Cure.getStoreItems(apiIdentifier)Async data store items
Cure.setLanguage(code)Set active language
await Cure.getLanguage()Get current language
await Cure.availableLanguages()Get available languages
Cure.sync(screenName)Manual sync for a tab
await Cure.syncStore(apiIdentifier)Sync and return data store items

Language utilities

MethodDescription
LanguageDirection.isRTL(code)Check if language is RTL
CureLanguageDisplay.flag(code)Get flag emoji for language
CureLanguageDisplay.displayName(code)Get the readable language name

iOS core: CMSCureSDK / Cure (singleton)

The main entry point for interacting with the SDK. Access its functionalities via the shared singleton instance. A typealias Cure is provided for convenience: public typealias Cure = CMSCureSDK.

// Accessing the shared instance:
CMSCureSDK.shared
// or using the typealias:
Cure.shared

Configuration

// Swift / Android
configure(projectId: String, apiKey: String, projectSecret: String, serverUrlString: String = "https://app.cmscure.com", socketIOURLString: String = "wss://app.cmscure.com")

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'.
// Swift / Android
var debugLogsEnabled: Bool { get set }

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

// Swift / Android
var pollingInterval: TimeInterval { get set }

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.

Language management

// Swift / Android
setLanguage(_ language: String, force: Bool = false, completion: (() -> Void)? = nil)

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.
// Swift / Android
getLanguage() -> String

Retrieves the currently active language code.

Returns

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

// Swift / Android
availableLanguages(completion: @escaping ([String]) -> Void)

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.

Content accessors

// Swift / Android
translation(for key: String, inTab screenName: String) -> String

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.

// Swift / Android
colorValue(for key: String) -> String?

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.

// Swift / Android
imageUrl(for key: String, inTab screenName: String) -> URL?

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.

Synchronization and cache

// Swift / Android
sync(screenName: String, completion: @escaping (Bool) -> Void)

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.
// Swift / Android
isTabSynced(_ tabName: String) -> Bool

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.

// Swift / Android
clearCache()

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.

Real time updates (Socket.IO)

// Swift / Android
startListening()

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.

// Swift / Android
stopListening()

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

// Swift / Android
isConnected() -> Bool

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

Returns

A Boolean indicating the connection status.

// Swift / Android
onTranslationsUpdated(for screenName: String, handler: @escaping ([String: String]) -> Void)

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.

NotificationCenter

The SDK also posts a Notification.Name.translationsUpdated notification on the main thread when content updates. The userInfo dictionary may contain a "screenName": String key with the tab that was updated (or __ALL__).

SwiftUI integration

For SwiftUI applications, CMSCureSDK provides ObservableObject wrappers and convenience extensions to create reactive UIs that automatically update when content changes.

ObservableObject wrappers

Use these with @StateObject in your SwiftUI views.

// Swift / Android
class CureString: ObservableObject { get set }

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

// Swift / Android
class CureColor: ObservableObject { get set }

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

// Swift / Android
class CureImage: ObservableObject { get set }

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.

String extension

// Swift / Android
"your_key".cure(tab: "your_tab_name") -> String

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.

Utilities and error handling

The SDK includes some utilities and defines an error enum for more robust error handling.

Color extension (SwiftUI)

// Swift / Android
extension Color { init?(hex: 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.

Error type

// Swift / Android
public enum CMSCureSDKError: Error, LocalizedError { get set }

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.

Refer to the SDK source code for specific error cases and their localized descriptions.

Webhooks

CMSCure Webhooks let you receive real-time HTTP POST notifications whenever content changes in your project. Use them to trigger builds, clear caches, sync external systems or audit content updates, without polling.

Setting up webhooks

Navigate to Project Settings → Webhooks in the dashboard. You can add up to 10 webhooks per project. Each webhook needs a destination URL (HTTPS recommended) and one or more event subscriptions.

Supported events

EventDescription
translation.createdA new key and value were added to a screen
translation.updatedAn existing translation value was changed
translation.deletedA translation key was removed
color.createdA new color token was added
color.updatedA color token value was changed
color.deletedA color token was removed
image.uploadedA new image asset was uploaded
image.updatedAn image asset was replaced or renamed
image.deletedAn image asset was removed
datastore.createdA new DataStore collection was created
datastore.deletedA DataStore collection was deleted
datastore.item.createdA new item was added to a DataStore
datastore.item.updatedA DataStore item was modified
datastore.item.deletedA DataStore item was removed
content.publishedContent was published (pushed live to SDKs)

Payload format

Every webhook delivery is an HTTP POST with a JSON body:

{
  "event": "translation.updated",
  "projectId": "proj_abc123",
  "timestamp": "2026-04-17T12:00:00.000Z",
  "data": {
    "tabName": "Dashboard",
    "key": "welcome_title",
    "values": {
      "en": "Welcome to Your App!"
    }
  }
}

The data field is event-specific and contains the relevant resource details.

Verifying signatures

Every delivery includes an X-CMSCure-Signature header: an HMAC-SHA256 hex digest of the raw JSON body, signed with your webhook secret. Always verify this signature to make sure the request is authentic.

const crypto = require('crypto');

function verifyWebhook(req, secret) {
  const signature = req.headers['x-cmscure-signature'];
  const expected  = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(req.body))
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Headers

HeaderDescription
Content-Typeapplication/json
X-CMSCure-SignatureHMAC-SHA256 hex digest of the body
X-CMSCure-EventThe event type (for example translation.updated)

Retry and failure policy

  • Deliveries time out after 10 seconds.
  • Any non-2xx response or network error increments a failure counter.
  • A successful delivery (2xx) resets the counter to zero.
  • After 50 consecutive failures, the webhook is automatically disabled.
  • Re-enable a disabled webhook from the dashboard. Re-enabling resets the failure counter.

Testing

Use the Send Test button in the webhook settings panel to fire a test event. The test payload looks like:

{
  "event": "test",
  "projectId": "proj_abc123",
  "timestamp": "2026-04-17T12:00:00.000Z",
  "data": {
    "message": "This is a test webhook from CMSCure"
  }
}

Best practices

  • Always use HTTPS endpoints in production.
  • Verify the X-CMSCure-Signature header before processing any payload.
  • Respond with a 2xx status quickly and do heavy processing asynchronously.
  • Subscribe only to the events you need to minimize noise.
  • Monitor the failure count in your dashboard and set up alerts for disabled webhooks.

This reference covers the JavaScript, Android, React Native and iOS (Swift and SwiftUI) SDKs. Unity, Flutter and other platforms will be added as they become available. Tabs, keys and real time updates work the same way on every platform.

Documentation | CMSCure