Build status: source complete, not yet built

We would rather tell you this on the first screen than have you discover it in your build log. This page documents a package that exists as source and nothing more.

The honest expectation is that the first real build will surface a handful of ordinary compile-time corrections, and that the test suite will need a pass before it goes green. That is normal for code that has never met a compiler. It is not a reason to distrust the design, and it is a very good reason not to schedule a release around it until someone has run the build.

Getting it into a build today

There is no coordinate to depend on. implementation("click.contentflow:compose:1.0.0") will not resolve from any repository, because nothing has been published and the build declares no publishing at all. Until that changes there are two honest routes.

Route one: a composite build

Point your app's settings.gradle.kts at the checkout. Gradle substitutes the modules in place, so your app compiles against the real source.

includeBuild("../contentflow-sdk-kotlin")

dependencies {
    implementation("click.contentflow:compose:1.0.0")  // substituted by the composite build
}

Route two: include the modules directly

Copy or submodule the checkout into your repository and include the three Gradle projects, then depend on them as projects.

dependencies {
    implementation(project(":compose"))  // transitively brings :android and :core
}

If you are not using Compose, depend on the android module instead and drive ContentFlowClient yourself. core alone is plain Kotlin/JVM with no Android types, which is what makes the contract tests runnable without an emulator.

First build

No wrapper jar is committed, so generate one once with a locally installed Gradle, or open the project in Android Studio and let it provision the wrapper for you.

$ gradle wrapper          # once, because gradlew is not committed
$ ./gradlew :core:test    # JVM contract tests, no emulator needed
$ ./gradlew build         # all three modules, needs the Android SDK

Start, register, place, read

Four steps, end to end. The renderer registration in step one is not optional, for the reason explained under placements and renderers.

1. Register a renderer, then start

ContentFlow.start(apiKey, locale) takes no tenant and no context. The tenant is derived from the key, and the application context is captured at process start by ContentFlowInitProvider, which the android module's manifest registers for you.

import click.contentflow.ContentFlow
import click.contentflow.registerRenderer
import java.util.Locale

class App : Application() {
    override fun onCreate() {
        super.onCreate()

        // Register before start so the first delivered block already has a renderer.
        ContentFlow.registerRenderer("home.discovery") { block ->
            DiscoveryCard(block)
        }

        ContentFlow.start(apiKey = "ws_1a2b3c_app", locale = Locale.getDefault())
    }
}

2. Drop the slot into your UI

import click.contentflow.ContentFlowSlot

@Composable
fun HomeScreen() {
    Column {
        Balance(account = user.account)
        ContentFlowSlot(placement = "home.discovery")
        Transactions()
    }
}

3. Declare typed field keys

There is no code generation in v1. A FieldKey is a typed handle on one tag, declared next to the screen that uses it, so there is no schema download, no build plugin, and no generated model to drift when a marketer edits a block.

import click.contentflow.FieldKeys

object DiscoveryFields {
    val Title  = FieldKeys.text("#title_main")
    val Body   = FieldKeys.textarea("#body_desc")
    val Hero   = FieldKeys.image("#header_image")
}

4. Read fields by tag inside the renderer

import click.contentflow.ContentBlock

@Composable
fun DiscoveryCard(block: ContentBlock) {
    val title = block.value(DiscoveryFields.Title)   // null when absent
    val hero  = block.require(DiscoveryFields.Hero)  // throws when absent or mistyped
    val body  = block.value(DiscoveryFields.Body)

    Card(title = title, hero = hero, body = body)
}

That is the whole integration. The slot serves cached content immediately, revalidates in the background, keeps stale content visible when the network is down, renders nothing when the placement is empty, and shares one observation and one live-updates connection across every slot on screen.

Modules and requirements

Three Gradle modules, one Kotlin package. The Kotlin package is click.contentflow in all three; the Android library namespaces differ, which matters only for generated R classes.

core is deliberately free of Android types so envelope decoding, ETag and 304 handling, typed field access, consent gating and cache namespacing are all testable on the JVM without an emulator. compose depends on android, which depends on core, so depending on compose brings all three.

Toolchain

Why OkHttp and not Ktor

Three reasons, all of them about your build rather than ours. It is already on nearly every Android classpath through Retrofit or Coil, so it usually adds nothing. It streams server-sent events without a second dependency. And it runs unchanged on the JVM, which is what lets the contract tests use MockWebServer with no emulator. core exposes OkHttp as an api dependency, and ContentFlowClientFactory.create accepts your own OkHttpClient so its dispatcher and connection pool are shared rather than duplicated. Closing a ContentFlow client never shuts down a client you passed in.

The Android module also declares INTERNET and ACCESS_NETWORK_STATE, and registers ContentFlowInitProvider under the authority ${applicationId}.contentflow-init, so two apps on one device never collide. The provider holds the application context and nothing else: no Activity, no Fragment, no View.

Keys, tenant and environment

One publishable key carries everything: which workspace you read, and whether you read live or test. Nothing else in the SDK can change either.

The tenant is derived from the key

A key is shaped <tenantId>_app for live or <tenantId>_test for test, and the tenant is the part before the suffix. Tenant ids themselves contain underscores, real workspaces look like ws_<hex>, so the SDK strips the known suffix rather than splitting on the first underscore.

That is why ContentFlow.start(apiKey = ..., locale = ...) needs no tenant parameter. The server applies exactly the same rule: strip a trailing _app or _test, and when neither is present, fall back to the text before the last underscore. It also rejects a mismatching X-Tenant-Id with 403 TENANT_KEY_MISMATCH, so a derived tenant can never widen access. ContentFlowKeys.tenantFor is that server rule byte for byte, last-underscore fallback included, and its own documentation comment says it mirrors the server. ContentFlowError.InvalidConfiguration is therefore raised only where the server would also parse nothing out of the key, which is a key with no underscore at any position after its first character. Every key the server resolves, this SDK resolves too, including keys that resolve to a workspace id that does not exist: those are dialled, not refused. See the table below. If your key predates the format, pass the tenant explicitly:

ContentFlow.start(context, apiKey = "legacy-key", tenantId = "ws_1a2b3c")

Where the server, this SDK and the Swift SDK disagree

Three resolvers, two of them identical. The server strips _app or _test, then falls back to the text before the last underscore. ContentFlowKeys.tenantFor is that function reproduced exactly. The Swift SDK strips _app or _test and has no fallback at all, so it refuses client side what this SDK sends.

If you ship both platforms, the three legacy-shaped rows, pk_live_abc, acme_application and abc_, are the ones to test. A legacy key produces a 404 from Android and a configuration failure on iOS, which look nothing alike in a crash report or a support ticket even though the cause is one string. Neither platform can reach a workspace its key does not name.

The environment comes from the suffix and nothing else

A key ending exactly in _test selects test and UAT; anything else is live. No request body ever carries an environment field, no header flips it, and the SDK never rewrites your key. Caches are namespaced by a hash of the full key, the tenant, the derived environment, the endpoint category, the locale and a cache schema version, so a test key and a live key can never observe each other's content on the same device.

Headers on every request

All three go on every call, the SSE stream included.

Accept-Language carries the active locale as a BCP 47 tag on every request. ?locale= goes on the GET reads only, /sdk/sync, /sdk/blocks/:key and /sdk/strings, and never on a POST. This SDK sets no User-Agent of its own, so whatever your OkHttpClient sends by default goes out; the Swift SDK sends contentflow-swift/1.0.0, so the two platforms are not separable the same way in an access log. Neither SDK ever sends X-API-Key: both use X-CF-Key exclusively, even though the server accepts either.

The device id is a random UUID generated once and stored in the SDK's own SharedPreferences file, committed synchronously so a process death cannot lose it. It is never an advertising id, never ANDROID_ID, and never any hardware identifier. Clearing app data rotates it, which is the correct behaviour.

Placements and renderers

A placement is exactly a block type key

ContentFlowSlot(placement = "home.discovery") fetches /sdk/blocks/home.discovery. There is no placement resolution layer: no normalisation, no case folding, no prefixing, no fuzzy matching and no fallback, because the delivery API has no placement concept to resolve against. If a placement renders nothing, the first thing to check is that a block with that exact key is published to this workspace.

Registering a renderer is required

A block payload carries content: field tags, types and values. It carries no layout, no template identifier and no rendering instructions. A slot therefore cannot invent native UI, and any SDK that claims otherwise is guessing. You register a composable per placement, once, and the slot calls it.

ContentFlow.registerRenderer("home.discovery") { block ->
    DiscoveryCard(block)
}

In a release build an unregistered placement renders nothing and reports a renderer_missing diagnostic, once per placement rather than on every recomposition. In Compose previews, and when you opt in with ContentFlow.setDevelopmentFallback(true), an unregistered placement instead renders a plain diagnostic view of the payload so you can see delivery working before you write the real UI.

The inline form, when a registry is overkill

The second ContentFlowSlot overload takes the content lambda directly and bypasses the registry, with optional slots for the loading, empty and error states.

ContentFlowSlot(
    placement = "home.discovery",
    loading = { ShimmerCard() },
    empty = { },
    error = { e -> Log.w("cf", e.message.orEmpty()) },
) { block ->
    DiscoveryCard(block)
}

Both overloads behave the same way underneath: cached content appears immediately, a transient failure never replaces content already on screen, Empty renders the empty slot, and every slot on the screen shares one observation and one SSE connection. A slot composed before ContentFlow.start renders nothing and reports a slot_before_start diagnostic instead of crashing.

Fields, tags and types

On the wire, a block's content is a tag-keyed values map joined against a fields schema array of {tag, type}. The SDK normalises that into a list of ContentField, addressed by tag.

{
  "key": "discovery_card",
  "instanceId": "inst_9f2c",
  "segment": "high_value",
  "version": 7,
  "values": { "#header_image": "https://…", "#title_main": "Hello" },
  "fields": [ { "tag": "#header_image", "type": "image" },
              { "tag": "#title_main",   "type": "text" } ]
}

Address fields by tag, never by index. Field order is preserved from the wire for debugging and generic rendering, but position is not a contract.

Tags are matched exactly

Matching is case-sensitive and literal. #title_main and title_main are different tags. If you look up the unprefixed form of a tag that exists with the #, the SDK still returns nothing, but it emits a tag_not_normalized diagnostic naming the tag it did find, so the mistake is visible. Duplicate tags in one scope resolve to the first occurrence and raise duplicate_tag.

Strict and lenient accessors

ContentBlock exposes the same three accessors.

Use value for anything the design can survive without, and require only for a field the screen genuinely cannot render without.

Three decoding rules worth knowing

• Declared but never published reads as absent. The field stays in block.fields as ContentFieldValue.Absent so the declared shape is still visible, but lenient access returns null and require throws FieldMissing. It is not reported as a type mismatch, because nothing was mistyped.
• A value with no schema entry still reaches you, with its type inferred from the payload and a field_without_schema diagnostic. Dropping it would silently delete live content because of a schema gap, which is the worse failure.
• An unrecognised wire type is preserved, not fatal. It becomes ContentFieldValue.Unknown carrying the raw JsonValue, readable with FieldKeys.raw(tag), because a marketer can publish a new field type without an app release.

Field key factories

Collections: a card is a block

A field the dashboard declares as collection holds an ordered list of whole block instances, which the server inlines under the field's tag. Each card arrives with its own key, instanceId, version, segment, values and field schema, and is decoded by the same code that decodes a top-level block.

There is no card type, no item type and no sub-schema on the field. The only addition to the model is ContentFieldValue.Collection(cards) and the matching FieldType.Collection.

Reading one

// ContentBlock
public fun collection(tag: String): List<ContentBlock>

// FieldKeys, when you prefer a declared key
public fun collection(tag: String): FieldKey<List<ContentBlock>>

collection(tag) is always a list: never null, never a throw. An absent tag, a tag that is not a collection, a declared-but-unpublished field, and a malformed collection value all read as empty, so a wrapper delivered by a stale proxy cannot break a screen and no wrapper draws list chrome around zero cards. A type mismatch also raises a field_type_mismatch diagnostic naming the tag.

Tag matching is the same lookup every other accessor uses, which means it is exact: #slides and slides are different tags, and looking up the unprefixed form of a tag that exists with the # returns nothing plus a tag_not_normalized diagnostic. Positional reads are ordinary Kotlin, so getOrNull(2) is the bounds-safe way to reach the third card.

val title = carousel
    .collection("#slides")
    .getOrNull(2)
    ?.value(FieldKeys.text("#title"))

A carousel, end to end

Register a renderer for the card key and one for the wrapper key. ContentFlowCard resolves each card through the registry entry for the card's own block key, so a wrapper's renderer never has to know how its children look.

object CardFields {
    val Title = FieldKeys.text("#title")
    val Image = FieldKeys.image("#image")
}

// A card is a block, so it gets an ordinary renderer.
ContentFlow.registerRenderer("reading_card") { card ->
    ReadingCard(
        title = card.value(CardFields.Title),
        image = card.value(CardFields.Image),
    )
}

ContentFlow.registerRenderer("reading_carousel") { carousel ->
    Column {
        carousel.value(FieldKeys.text("#heading"))?.let { Text(it) }
        LazyRow {
            contentFlowCards(
                cards = carousel.collection("#slides"),
                wrapperInstanceId = carousel.instanceId,
                collectionTag = "#slides",
            )
        }
    }
}

The two Compose helpers

Keying on instanceId is the point of the helper. A card moved from position 2 to position 5 keeps its identity and its UI state; a replaced card gets a new one. Array position is never identity, so this never keys on the index.

Analytics

ContentFlowCard emits one impression per card instance per session, attributed to the card's own instanceId, with position, wrapperInstanceId and collectionTag attached as dimensions. Pass trackImpression = false if the app tracks visibility itself. Nothing is emitted while analytics consent is denied.

Building an event by hand is the same idea: EngagementEvent.of(block, type, position, wrapperInstanceId, collectionTag, custom) puts the card's instanceId, blockKey and screen on the event and folds the placement into custom as dimensions. Placement is context, not ownership: a card shown in three carousels reports against its own instance in all three, and the metric owner is never rewritten to the wrapper.

Malformed cards degrade, they never fail the wrapper

• A collection value that is not a list reads as empty, with a collection_value_not_a_list diagnostic.
• Inside the list a card with no usable key, instanceId or values map is skipped with collection_card_skipped. Siblings survive in delivered order.
• Nesting is capped at one level, matching the server: a collection inside a card reads as empty with collection_nesting_exceeded, so a hand-built or stale payload cannot drive unbounded recursion.

Repeaters were withdrawn, and replaced by collections

The withdrawn design stored a list's items as nested values inside a single block instance. That made every item a value rather than an entity, so an individual card could not carry its own segment targeting, its own schedule, its own approval state, its own A/B variants, or its own analytics. ContentFlow is instance centric and all of that machinery already exists at the instance level, so a list built out of values sat outside it.

A collection is that list expressed as a wrapper holding an ordered set of real block instances, so every card inherits all of it. In Kotlin that means FieldType.Collection, ContentFieldValue.Collection(cards), ContentBlock.collection(tag), FieldKeys.collection(tag), and the two Compose helpers. Declare FieldKeys.collection(tag), not a repeater key, and expect whole blocks under the tag, never { id, values } items.

The platform-level explanation is at Blocks & fields, Collections.

Consent

Saudi PDPL compliance is not a feature flag here, and this section is worth reading in full before you wire a consent screen to it.

Everything starts denied

On a fresh install, analytics consent and every channel consent are ConsentStatus.Denied. Consent is never inferred: not from calling identify, not from registering a push token, not from an OS notification permission, not from a server segment, and not from a previous installation. Only an explicit application call changes it. A corrupt consent file resets to denied, failing closed rather than open.

Content still syncs while consent is denied

This is deliberate. Blocks, strings and locales are delivered normally to an unconsented device; only analytics is dropped. Your app is not broken for a user who declined measurement.

The three-state wire contract on identify

identify has no consent parameter. It sends the SDK's own persisted decision, and omits the field entirely until the application has made one. The server reads the three cases differently:

The reason for the absent case is concrete: a reflexive false on every launch would silently revoke a grant the same user made on web or another surface. An explicit denial does send false, because saying no is a real decision that has to reach the server. Identify can never grant consent, and the local store distinguishes "never asked" from "said no" even though both refuse analytics locally.

Setting consent

ContentFlow.client.setAnalyticsConsent(ConsentStatus.Granted)
ContentFlow.client.setChannelConsent(ConsentChannel.Marketing, ConsentStatus.Granted)

setAnalyticsConsent persists the decision, purges the queue first on any non-grant so a queued event cannot escape between the local change and the round trip, and then re-identifies to propagate the decision. Because the server replaces the stored trait map rather than merging into it, that internal re-identify resends the last traits the app supplied.

setChannelConsent covers Push, Sms, Whatsapp, Email, Location (wire name locationTracking) and Marketing. Channel consent is stored against a user profile, so it requires a prior identify(userId = ...) and fails fast with ContentFlowError.InvalidConfiguration otherwise. Every channel is sent on each call, so local and server state cannot drift apart.

What denial actually does locally

• Engagement and identity events are refused before anything is stored, so a denied device holds no analytics data even in memory. Calls return TrackingDisposition.DroppedNoConsent, which is a result, not an error.
• Revoking consent purges anything queued, immediately, and a batch that fails while consent is revoked mid-flight is dropped rather than re-queued.
• Registering a push token is an operational registration, not consent. It does not grant push consent.

Observe consent reactively through client.consent, a StateFlow<ConsentSnapshot>, or read it once with client.consentSnapshot().

Behaviours this SDK chose on purpose

Each of these is a decision with a cost. They are stated here so you can design around them rather than discover them.

Caching, offline and live updates

• Stale-while-revalidate by default. The disk snapshot is published before the first request goes out, so a cold start with no network still renders.
• Conditional requests use the stored weak ETag byte for byte, W/ and quotes included. The SDK never parses or reconstructs it. A 304 keeps the cached body and refreshes only validation metadata; a 304 whose cached body has gone triggers one unconditional refetch and an etag_without_body warning.
• A captive portal or malformed proxy response never overwrites the cache. A sync response that parses as JSON but carries no blocks array is refused, and the cached snapshot is kept, because treating it as an authoritative empty snapshot would unpublish everything on screen.
• Cache entries are checksummed and swapped in atomically, so a process death during a write leaves either the old valid snapshot or the new one, never a half file. A tampered or schema-mismatched entry is discarded with a cache_discarded diagnostic.
• Live updates use one SSE connection per client, never one per slot. It pauses when the app backgrounds, reconnects with jittered backoff capped at 60 seconds, revalidates after every reconnect because events may have been missed, and collapses bursts of invalidations into one sync. A 401 or 403 on the stream is terminal until the configuration changes, rather than an infinite reconnect loop.
• The stream request carries headers and no query parameters. All three auth headers plus Accept-Language are set on it, and the URL is bare /sdk/stream. A resumed stream sends the last event id as the standard Last-Event-ID header. The Swift SDK resumes with a ?lastEventId= query parameter and also sends ?key=, ?device=, ?tenantId= and ?locale= on the stream URL, so a proxy rule, a log filter, or a WAF signature written for one platform does not cover the other.
• Polling is the fallback, not the default. The periodic foreground sync only fires while the stream is not connected.

All of this is configurable through SyncPolicy, which is a plain data class on the configuration. The defaults are a 5 minute foreground revalidation window, a 15 minute poll interval, a 10 second request timeout, a 10 event flush batch and a 15 second flush interval.

ContentFlow.start(
    context,
    ContentFlowConfiguration(
        apiKey = "ws_1a2b3c_app",
        tenantId = "ws_1a2b3c",
        locale = Locale.forLanguageTag("ar"),
        syncPolicy = SyncPolicy(liveUpdates = false, pollIntervalMillis = 5 * 60_000L),
        diagnostics = DiagnosticsLevel.Verbose,
    ),
)

Switching locale with setLocale invalidates locale-specific observations and revalidates. Caches are keyed per locale, so switching back is instant.

Diagnostics

Nothing is logged by default beyond errors. Diagnostics are never thrown and never break content delivery; a sink that throws is ignored rather than taking the SDK down.

ContentFlowDiagnostics.setLevel(DiagnosticsLevel.Verbose)
ContentFlowDiagnostics.addSink { Log.d("ContentFlow", "${it.code}: ${it.message}") }

addSink returns an AutoCloseable that removes the sink again. Codes worth knowing:

Module: core

Plain Kotlin/JVM. No Android types. Package click.contentflow.

ContentFlowClient

The delivery client, an AutoCloseable interface. One client owns one configuration: a key, its derived environment, a tenant, a locale. All background work is a child of a single job that close() cancels, so a tenant or account switch is a clean teardown rather than a leak.

Configuration

Content model

Results, events and state

Errors and diagnostics

ContentFlowError is a sealed Exception hierarchy: InvalidConfiguration, AuthenticationFailed(status), AuthorizationFailed(status), NotFound(resource), RateLimited(retryAfterMillis), ServerError(status), TransportError, Timeout, DecodingError, InvalidResponseEnvelope, CacheError, Cancelled, ConsentDenied, UnsupportedFieldValue(tag, expected, actual) and FieldMissing(tag).

ContentFlowDiagnostics is a process-wide fan-out with level(), setLevel(level), addSink(sink): AutoCloseable, clearSinks() and report(severity, code, message, cause). A Diagnostic carries (severity, code, message, cause), severity being Debug, Warning or Error. DiagnosticsSink is a fun interface, so a lambda works.

Platform and factory

The factory is the seam that makes core testable: pass a caller-owned scope and an OkHttp client pointed at a mock server and the whole client runs on the JVM.

Module: android

The ContentFlow object is the entry point. It holds at most one client, in an AtomicReference, and bootstraps on its own supervisor scope so a failed startup never takes down a host scope and nothing is ever launched on GlobalScope.

Every overload is @JvmStatic, and the ones with defaults are @JvmOverloads, so Java callers get the same shapes. Repeated start calls are deterministic: an identical configuration returns the existing client, and a different one closes the old client first, so switching tenant or environment tears down the old streams, timers and caches rather than stacking on top.

ContentFlowInitProvider is public only because the manifest names it. You never call it. The module also derives the device context sent once per analytics batch: platform, osVersion, deviceModel and appVersion. Foreground state comes from ProcessLifecycleOwner; if lifecycle-process is absent the SDK assumes foreground and warns rather than stalling.

Module: compose

Three extensions on ContentFlow, two ContentFlowSlot overloads, and the two collection helpers. The registry behind them is internal, keyed by placement, and warns once per unregistered placement.

The observation is keyed on placement and client only, so a new lambda or modifier identity on recomposition never restarts it, and it is collected with collectAsStateWithLifecycle. In LocalInspectionMode, which is what a Compose preview runs in, an unregistered placement falls back to the development preview automatically so previews are not blank.

What is in v1, and what is not

This SDK is not at parity with the JavaScript SDK, and it does not pretend to be. Missing capabilities are omitted rather than stubbed, because a local-only stub would tell an app that something changed on the server when it did not.

Known limitations, stated plainly

• Engagement events are held in memory only and do not survive process death.
• The server does not deduplicate on the client-generated eventId the SDK already sends, so an ambiguous timeout can duplicate an event. Writes are therefore never retried by the transport.
• Traits replace rather than merge. Send the full set every time. An empty map, or omitting traits altogether, is a no-op that leaves stored traits unchanged; there is no way to clear a device's traits through this field.
• There is no code generation. Typed field keys give you the safety without a schema download, a build plugin, or generated models that drift when a marketer edits a block.

Migrating off a hand-written REST client

If you already talk to /sdk/* from your own OkHttp or Retrofit code, most of what you built maps onto something here. The REST reference remains the authority on the wire itself; this SDK is a client for exactly that contract and adds no endpoints of its own.

Two things worth checking during the swap. First, your base URL: if your old client ever pointed at api.contentflow.click it was reading frozen content, and moving to this SDK will change what your app displays. That is the fix landing, not a regression. Second, your version handling: if you were comparing a block's version against the sync ETag, they are different values with the same name, and only one of them is an integer.