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
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.
- Create tabs (for example
- 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
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, orcure.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.
- SwiftUI: use reactive wrappers such as
- 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
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 exampleimage: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 optionalctaUrl. Field values can be plain types or localized objects. - SDK configuration: initialize each platform SDK once with your
Project ID,API Keyand, 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, webobserve()) 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.
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 inColor(hex:)andUIColor(hex:). - Images:
Cure.ManagedImage(SwiftUI) orimageURL(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 textCureColor("key"): reactive SwiftUI ColorCureDataStore(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")andgetLanguage()languageDirection: use.isRTLto adapt the layoutCureLanguageDisplay.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.
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 toColor. - Images:
CureImage(Compose) orCureImageView(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 textrememberCureColor("key", Color.Gray): reactive Compose ColorcureDataStore("apiIdentifier"): reactive data store recordsCureImage(key = "hero_banner"): managed image in one lineCureText(key = "title", tab = "home"): managed text in one lineCureLayoutDirection { /* 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:cureDefaultCureImageView:app:cureImageKeyfor global imagesCureColorView:app:cureColorKeyfor 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")andCure.getLanguage()LanguageDirection.direction(code): use.isRTLto adapt the layoutCureLanguageDisplay.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"): returnsString?item.int("field"),item.double("field"),item.bool("field")item.ctaURL: optional CTA or deep link URLitem.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 tabCure.syncStore("api_id"): sync one data storeCure.sync(CMSCureSDK.COLORS_UPDATED): sync global colorsCMSCureSDK.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.
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 textuseCureColor("key", "#007AFF"): reactive hex color stringuseCureImage("key"): reactive image URLuseCureDataStore("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 lookupCure.colorValue(key)andCure.imageURL(key)Cure.getStoreItems(id)andCure.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")andCure.getLanguage()LanguageDirection.direction(code): returns"RTL"or"LTR"to adapt the layoutLanguageDirection.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 ornullitem.int("field"),item.double("field"),item.bool("field")item.ctaURL: optional CTA or deep link URLitem.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 tabCure.syncStore("api_id"): sync one data storeCMSCureContentUpdate: 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.gradleJavaScript 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.
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-sdkOr 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'), everyobserve()binding updates. - Language list:
cure.getAvailableLanguages()andcure.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 throughwss://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.
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
projectIdstring: Required. Your unique Project ID from the CMSCure dashboard.apiKeystring: Required. Your API Key for authenticating requests.projectSecretstring: Optional. Enables real-time WebSocket updates via Socket.IO.defaultLanguagestring: 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
referencestring: Content reference: 'tab:key' (translations), 'color:key', 'image:key', 'store:identifier', 'meta:languages', or 'meta:language'.listenerfunction: Callback receiving (value, { reason }) on every update.options.defaultValueany: 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
referencestring: The content reference to resolve.defaultValueany: 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
keystring: The key for the desired string (e.g., 'welcome_title').tabstring: The tab/screen name (e.g., 'home_screen').defaultValuestring: 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
keystring: The color key (e.g., 'primary_color').defaultValuestring: 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
keystring: The image key (e.g., 'hero_banner').defaultValuestring: 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
apiIdentifierstring: The API identifier of the Data Store (e.g., 'feature_products').defaultValueArray: 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
languageCodestring: 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
handlerfunction: Receives a CustomEvent with event.detail containing { reason, timestamp, ... }.
Data store field access
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()] : vAndroid 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 = CMSCureSDKConfiguration
Cure.init(context: Context)Initializes internal storage and resources. Must be called once before configure(), typically in Application.onCreate().
Parameters
contextContext: 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
contextContext: Application context.projectIdString: Your Project ID from the CMSCure dashboard.apiKeyString: Your API Key for authenticating requests.projectSecretString: Project Secret for Socket.IO real-time handshake.enableAutoRealTimeUpdatesBoolean: Optional. Enable automatic real-time sync. Defaults to true.
Content access
Cure.translation(forKey: String, inTab: String) → StringSynchronously 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
forKeyString: The translation key (e.g., 'welcome_title').inTabString: 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
forKeyString: 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
forKeyString: 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
forIdentifierString: 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
languageCodeString: Language code (e.g., 'en', 'ar').forceBoolean: Optional. Force refresh even if unchanged. Defaults to false.
Cure.getLanguage() → StringReturns 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
screenNameString: 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.
| Helper | Description |
|---|---|
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.
| View | XML attributes |
|---|---|
CureTextView | app:cureKey, app:cureTab, app:cureDefault |
CureImageView | app:cureImageKey, app:cureImageTab |
CureColorView | app: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
projectIdstring: Your Project ID from the CMSCure dashboard.apiKeystring: Your API Key.projectSecretstring: Project Secret for real-time updates.enableAutoRealTimeUpdatesboolean: Optional. Enable auto real-time sync. Defaults to true.
Hooks (primary API)
useCureString(key, tab, defaultValue?) → stringReturns a reactive translated string that auto-updates on content or language changes. Auto-subscribes the tab on first access.
Parameters
keystring: Translation key (e.g., 'welcome_title').tabstring: Tab/screen name (e.g., 'home_screen').defaultValuestring: Optional fallback text.
Returns
string Reactive translated string.
useCureColor(key, defaultValue?) → stringReturns a reactive hex color string that auto-updates on content changes.
Parameters
keystring: Color key (e.g., 'primary_color').defaultValuestring: Optional fallback hex (e.g., '#007AFF'). Defaults to '#000000'.
Returns
string Hex color string (e.g., "#3b82f6").
useCureImage(key, tab?, defaultValue?) → string | nullReturns a reactive image URL. If tab is provided, retrieves from tab translations instead of global images.
Parameters
keystring: Image key (e.g., 'hero_banner').tabstring | null: Optional tab for tab-based images.defaultValuestring: 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
apiIdentifierstring: 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
urlstring | null: The image URL (typically from useCureImage).styleStyleProp<ImageStyle>: Optional style prop for the image.
Imperative API
The Cure object gives direct access outside hooks or in code that is not React.
| Method | Description |
|---|---|
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
| Method | Description |
|---|---|
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.sharedConfiguration
// 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
projectIdString: Your unique Project ID from the CMSCure dashboard.apiKeyString: Your API Key for authenticating API requests.projectSecretString: Your Project Secret, used for legacy encryption and socket handshake.serverUrlStringString: Optional. Base URL for the CMSCure API. Defaults to 'https://app.cmscure.com'.socketIOURLStringString: 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
languageString: The language code to set (e.g., "en", "fr").forceBool: 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() -> StringRetrieves 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) -> StringRetrieves 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
keyString: The key for the desired translation.screenNameString: 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
keyString: 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
keyString: The key for the desired image URL.screenNameString: 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
screenNameString: 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) -> BoolChecks if the specified tab's content exists in the local cache, indicating it has been synced at least once and has data.
Parameters
tabNameString: 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() -> BoolReturns 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
screenNameString: 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
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") -> StringA convenience extension on String to directly get a translation within SwiftUI views. This also triggers view updates when the underlying translation changes.
Parameters
tabString: 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
hexString?: 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
| Event | Description |
|---|---|
translation.created | A new key and value were added to a screen |
translation.updated | An existing translation value was changed |
translation.deleted | A translation key was removed |
color.created | A new color token was added |
color.updated | A color token value was changed |
color.deleted | A color token was removed |
image.uploaded | A new image asset was uploaded |
image.updated | An image asset was replaced or renamed |
image.deleted | An image asset was removed |
datastore.created | A new DataStore collection was created |
datastore.deleted | A DataStore collection was deleted |
datastore.item.created | A new item was added to a DataStore |
datastore.item.updated | A DataStore item was modified |
datastore.item.deleted | A DataStore item was removed |
content.published | Content 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
| Header | Description |
|---|---|
Content-Type | application/json |
X-CMSCure-Signature | HMAC-SHA256 hex digest of the body |
X-CMSCure-Event | The 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-Signatureheader 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.