The Kotlin SDK

The Kotlin SDK, com.bifrostorbit:cms-sdk, reads published content from the delivery API in Android apps and on JVM servers, such as Ktor or Spring Boot. It does what the client in the JavaScript SDK does: pages, redirects, menus, site-wide content, lists, banners, popups, products, sitemaps and the schema, with the same retries and errors. It is open source under the MIT licence.

• Suspend functions for Kotlin coroutines, and CompletableFutures for Java.
• Built on OkHttp and kotlinx.serialization. Bring your own OkHttpClient to share its connection pool and interceptors.
• Every answer has a @Serializable model. Fields arrive as a JsonObject, and you decode them into your own types when you need them.

Install

It needs Java 11 or later on servers, and Android 5.0 (API 21) or later in apps. The Java futures need Android 7.0 (API 24). Kotlin projects need Kotlin 2.2 or later.

The package is com.bifrostorbit:cms-sdk on Maven Central, where you can see the latest version.

1// build.gradle.kts2plugins {3    kotlin("plugin.serialization") version "2.4.21" // to decode fields into your own types4}56dependencies {7    implementation("com.bifrostorbit:cms-sdk:0.1.0")8}

With Maven:

1<dependency>2  <groupId>com.bifrostorbit</groupId>3  <artifactId>cms-sdk</artifactId>4  <version>0.1.0</version>5</dependency>

An Android app also needs <uses-permission android:name="android.permission.INTERNET" /> in its manifest.

Set up

Create a public key in Configuration › API keys. It starts with cms_pk_ and reads published content only, so it may ship in an app.

1import com.bifrostorbit.cms.CmsOrbitClient23val cms = CmsOrbitClient("cms_pk_...") {4    defaultRegion = "germany"5}

In Java:

CmsOrbitClient cms = CmsOrbitClient.builder("cms_pk_...")    .defaultRegion("germany")    .build();

Create one client and share it. It is safe to use from many coroutines and threads at once.

Secret keys

A secret key reads drafts, so anyone who has it can read unpublished content. The SDK refuses a cms_sk_ key, as apiKey or previewKey, when it runs on Android, because an app's files can be read by anyone who installs it. This matches the JavaScript SDK, which refuses secret keys in browser code. On a JVM server a secret key is allowed: keep it in an environment variable or a secrets manager, never in source control.

Methods

Every method is a suspend function. Call it from a coroutine, such as viewModelScope.launch on Android or a Ktor route.

1val result = cms.resolve("/products/hiking-boots")2val page = cms.getPage("/products/hiking-boots", RequestOptions(locale = "de-DE"))3val header = cms.getNavigation("header")4val footer = cms.getGlobal("footer")5val articles = cms.list(ListOptions(type = "article", sort = CmsSort.PUBLISHED_AT_DESC, perPage = 12))

RequestOptions holds region, locale, preview, strict and includeReferences. ListOptions adds type, page, perPage, filter, tag, category, sort, q and includeFields. From Java, build them with new RequestOptions().withRegion("de") and new ListOptions("article").withPerPage(12).

A page has meta, which says which region and language answered and whether a fallback was used, so an app can show a notice such as "This page is not available in English yet."

From Java

cms.getAsync() has the same methods, each answering with a CompletableFuture. Call join() to wait for the answer on a server, or chain thenAccept to stay off the calling thread. Cancelling a future cancels its request.

1CmsResolution result = cms.getAsync().resolve("/products/hiking-boots").join();2if (result instanceof CmsResolution.Page) {3    CmsPage page = ((CmsResolution.Page) result).getPage();4    System.out.println(page.getName());5} else if (result instanceof CmsResolution.Redirect) {6    response.sendRedirect(((CmsResolution.Redirect) result).getTo());7}

A failed call completes the future with a CompletionException from join(), whose getCause() is one of the exceptions in Errors.

Your own types

Fields arrive as a JsonObject. Declare a @Serializable class with the fields you use, and decode them with decodeFields. Fields you leave out are ignored, and missing or null values take your defaults.

1@Serializable2data class FaqEntry(val question: String, val answer: String = "")34val faqs = cms.list(ListOptions(type = "faqEntry", category = "pricing", includeFields = true))5val entries = faqs.items.map { it.decodeFields<FaqEntry>() }

decodeFields is on pages, blocks, global entries, list items and referenced entries. Images decode as CmsImage and links as CmsLink. CmsJson.decode<T>(element) decodes any other JsonElement. A shape that does not match throws CmsDecodingException.

From Java, pass the JSON to your own library: page.getFields().toString() is the fields as JSON text, ready for Jackson or Gson.

Generate types

Instead of writing the classes yourself, let the type generator in the JavaScript package write them from your space's schema: one @Serializable data class per component and content type. Run it with Node 20 or later whenever the schema changes:

npx --package @bifrost-orbit-cms/sdk cms-orbit generate --lang kotlin --out src/main/kotlin/cms/CmsTypes.kt --package com.example.cms

It reads CMS_API_URL and CMS_PUBLIC_KEY, or --url and --key. Add --include references if you load references with include.

Components in Jetpack Compose

A page's components is a list of CmsComponent, each with id, type, fields, children and variant. Decode each into your own class and draw it:

1@Serializable2data class Hero(val heading: String, val image: CmsImage? = null, val description: String = "")34@Composable5fun CmsBlocks(blocks: List<CmsComponent>) {6    Column {7        blocks.forEach { block ->8            when (block.type) {9                "hero" -> HeroView(block.decodeFields<Hero>())10                "card-grid" -> CardGridView(block)11                else -> Unit12            }13        }14    }15}1617@Composable18fun HeroView(hero: Hero) {19    Column {20        hero.image?.let {21            AsyncImage(model = CmsImages.url(it.url, width = 1080), contentDescription = it.alt)22        }23        Text(hero.heading, style = MaterialTheme.typography.headlineLarge)24        Text(AnnotatedString.fromHtml(hero.description))25    }26}

Load the page in a view model, so it survives screen rotation:

1class PageViewModel(private val cms: CmsOrbitClient) : ViewModel() {2    var result by mutableStateOf<CmsResolution?>(null)3        private set45    fun load(path: String) = viewModelScope.launch {6        result = try {7            cms.resolve(path)8        } catch (error: CmsOrbitException) {9            null10        }11    }12}

• AsyncImage is from Coil. CmsImages.url asks the CMS for an image resized to the width you show it at, and CmsImages.widths lists the sizes on offer.
• Rich text fields are HTML. AnnotatedString.fromHtml in Compose 1.7 shows headings, bold, italics and links; for tables and embeds, use a WebView.
• Blocks in a slot are on the slot's field and in children, as in Render components. Decode a Components field as List<CmsComponent> and pass it to CmsBlocks again.
• An unknown block type draws nothing, so an app that is not yet updated keeps working when editors add a component.

Insights Orbit

When the space is connected to Insights Orbit under Settings, each page carries id, the entry's id, and insights, a CmsInsightsSite with the site key, or null. Both are null from an older CMS Orbit.

On a server that renders HTML, CmsInsights.tags writes the Insights Orbit script with the site key and <meta name="insights-content"> with the entry's id, so the page's numbers follow it when its address changes. Without a site key it answers with an empty string:

val head = CmsInsights.tags(page)// or with your own key and a first-party address:val head = CmsInsights.tags(page, site = "SITE_KEY", src = "/stats/script.js", api = "/stats/collect")

contentId tags page views with another entry, disable switches off automatic events, such as listOf("scroll"), and campaigns = false stops counting elements marked with data-banner or data-popup. From Java, call CmsInsights.tags(page) or CmsInsights.tags(page, "SITE_KEY"). Insights Orbit counts websites, so an Android app has no use for the script.

Preview

Drafts need a secret key, which an Android app may not hold. Preview drafts on a JVM server instead, such as the server that renders your website.

1. Give the client a previewKey with the secret key.
2. When the editor opens your website with ?preview=…, check the token with verifyPreviewToken. It answers with the entry, including its url, or throws CmsUnauthorizedException when the token is invalid or has expired.
3. Remember that the visitor is previewing, such as in a session cookie, and read pages with RequestOptions(preview = true).

1get("/api/preview") {2    val token = call.parameters["preview"] ?: return@get call.respond(HttpStatusCode.BadRequest)3    val entry = try {4        cms.verifyPreviewToken(token)5    } catch (error: CmsUnauthorizedException) {6        return@get call.respond(HttpStatusCode.Unauthorized)7    }8    call.sessions.set(PreviewSession(enabled = true))9    call.respondRedirect(entry.url ?: "/")10}

Only redirect to addresses on your own website. Asking for a preview without a previewKey throws an IllegalStateException before any request is sent. See Set up the live preview.

Errors

Failed calls throw a CmsOrbitException, or one of its kinds. Each has the HTTP status and the API's code.

Network errors and server errors are retried twice, after 250 and 750 milliseconds, and each attempt times out after 5 seconds. Client errors, including 429, are never retried. Cancelling the coroutine cancels the request.

1val page = try {2    cms.getPage(path)3} catch (error: CmsNotFoundException) {4    null5} catch (error: CmsRateLimitedException) {6    delay(error.retryAfter * 1_000L)7    cms.getPage(path)8} catch (error: CmsServerException) {9    cachedPage10}

Each key may make 15,000 requests a minute. See Rate limits in the delivery API.

Caching

The client does not cache answers. The API's Cache-Control is meant for shared caches such as a CDN (s-maxage), so OkHttp's own cache does not keep them; see Caching in the delivery API. In an app, keep what you show in memory or in a local database, and read it again when the app returns to the foreground. On a server, keep answers for about a minute, or refresh them when publish webhooks arrive.