The product map

Everything below runs on one workspace (tenant). The SDK is how an app takes part; the dashboard and the management API are how a team operates it.

Which tool do I use?

How the pieces talk

Four public surfaces reach ContentFlow, and each has its own credential. App traffic from the SDK goes to the SDK API at api.contentflow.click/sdk/v1. Operator traffic goes to the management API at api.contentflow.click/api/v1: from your servers and CI with a write or read key, and from the dashboard at app.contentflow.click with a portal sign-in. AI assistants connect through ContentFlow's MCP server, acting as the signed-in dashboard user. All four work on the same workspace data.

Core concepts

Blocks vs. instances

A block type is a UI shape defined in code (a hero, a card, a carousel). A block instance is that shape filled with content, a specific hero on your home screen. Types are defined by developers and registered over the REST API, the CLI that will version them from git is not published yet; instances are managed by anyone in the dashboard. Field types and tag addressing are covered in Blocks & fields.

A list is not a special case of either. A collection field holds an ordered list of references to other instances, so a carousel is an ordinary instance whose slides are ordinary instances. Every card therefore has its own targeting, schedule, approval state, A/B variants and analytics, and delivery inlines the eligible ones in full under the field's tag.

Channels

A channel is a route a campaign is delivered over: in-app, popup, push, SMS, WhatsApp or email. Blocks are different: they are delivered in-app through /sync, never by push. Popup and in-app render as block-style image cards; how often a popup may appear is set per item and by workspace limits (Popup frequency and limits). SMS runs through Twilio or Taqnyat, and WhatsApp through Twilio, using your own account or a ContentFlow-managed one.

Segments & targeting

A segment is an audience. A block instance is targeted only by its segment (seg and segIds). The locale does not decide who sees a block: it only selects the translation. Campaigns target segments, plus rules such as geo. The special "All users" segment still needs a phone number and consent on the contact before SMS or WhatsApp can reach it. For the whole chain, sending a trait through to proving the targeting landed, see Traits & targeting.

Content lifecycle

1. Define, a developer adds a block type in code and registers it from a server or CI with POST /sdk/v1/cards/register and the write key. A ContentFlow CLI is not published yet.
2. Fill, someone creates an instance in the dashboard (or seeds it via /cards/sync).
3. Target, pick a segment, a schedule and a priority.
4. Publish, the block goes live. There is no content webhook; connected apps see it on the live stream.
5. Sync, apps pull it on the live signal or their next GET /sdk/v1/sync, no redeploy.
6. Roll back, restore a saved version of the instance in the dashboard. Apps pick it up the same way.

Four callers, different kinds of key

Use the credential that matches the caller. Each one can do only its own job, so a key leaked from an app can't edit content or read profiles.

An app can use three kinds of key. A publishable key, shaped <workspace-id>_cfpk plus 40 hex characters, is the recommended one. You create, rotate and revoke it under Settings → API keys; it is stored hashed, and its environment comes from its stored record. Derived keys, <workspace-id>_app and <workspace-id>_test, are the legacy form. Anyone who knows the workspace id can compute them, so they are not secret. Admins can switch them off per workspace, and operators globally; a refused key gets 401 INVALID_SDK_KEY. A secret key, pk_live_… or pk_test_…, is for servers.

Create and rotate publishable SDK keys in the dashboard under Settings → API keys. Write and read keys are under Developers → Your keys; they are shown in full only once, when they are created or rotated; after that you see a masked value, so rotate a key you have lost. See Keys for headers and the API explorer for every operation.

Live and test never mix

The key decides the environment; there's no client-side flag. For a publishable key the environment comes from its stored record; for a derived key it comes from the suffix (_test or _app). A test key sees content published to Test as well as Live; a live key sees Live only. Test traffic is stamped env: test, excluded from live analytics and never updates block counters.

Sandbox workspace. If your workspace has a linked sandbox (Settings → Sandbox, beta), its test keys send their data to the sandbox, not to the live workspace: the derived <workspace-id>_test key, test publishable keys (cfpk_test), and test secret keys (pk_test_) all land there, and a test publishable key is created in the sandbox itself. The sandbox still shows your live blocks and strings unless it overrides them. Without a sandbox, test keys behave as before. Live keys (_app, live publishable and pk_live_) are unchanged and never write to the sandbox. A sandbox workspace can only create and list test keys; asking for a live key there answers 403 SANDBOX_LIVE_KEY_FORBIDDEN. In Test mode, the Developers page shows the sandbox's test key. The sandbox's test key is managed from inside the sandbox: switch to the sandbox workspace, then create, rotate or revoke it under Settings → API keys there (the live workspace's key list never shows it). If ContentFlow briefly cannot confirm where a test key's traffic goes (for example during a brief outage), writes with that key (identify, events, track-event, consent, register-push, location and the other write calls) answer 503 SANDBOX_ROUTE_UNAVAILABLE with a Retry-After header instead of being stored in the live workspace, and the SDK retries them; reads (sync, blocks, strings) and the in-app campaign fetch (POST /campaigns, a read) keep working, answered from the workspace the key belongs to. Live keys are never affected.

A device belongs to the environment it was first identified in. Calling /identify, /consent, /register-push or logout for that device with the other environment's key returns 409 DEVICE_ENVIRONMENT_MISMATCH. Use a separate install (or a fresh device id) for test builds.

The call sequence, step by step

This is what one app launch looks like with the JavaScript SDK. client.start() runs steps 2 to 8 for you; the native SDKs follow the same order. Walk through it, then open the skip notes to see what each step protects.

import { createCFClient } from '@contentflow/sdk/web';

const client = createCFClient({
  publicKey: CF_PUBLISHABLE_KEY,        // a test-environment key in dev builds, a live one in production
  userId: signedInUserId,               // omit for anonymous installs
  locale: 'ar',
  consent: false,                       // analytics consent: ask first
});

await client.start();                   // cached paint → identify → sync + strings → live updates

// Later, when the user agrees to analytics:
await client.setConsent(true);          // re-identifies with consent: true

const banner = client.getBlock('home_banner');
if (banner) render(banner.values); else renderBundledFallback();

Consent decides what's stored

Analytics consent travels on /identify and governs what ContentFlow may store about a person: without it no profile, traits, segments, events or location are written, and only untargeted content is delivered. Channel consent, sent with setChannelConsent() to POST /consent, governs what may be sent to them. The full model is in Identity and consent.

Out of order: what happens

Most ordering mistakes don't throw: the SDK API acknowledges the request and tells you what it dropped. Watch dropReasons on event responses and the onEventsDropped callback.

Timing and freshness

• Segments on first launch. Identify waits for the profile to be written before it reads segments, so the first identify reports real membership. /sync never waits: it answers from the device's stored segments and refreshes them in the background at most once a minute.
• Content. A publish reaches connected apps through the live stream in about a second; otherwise on the next poll (30 s by default).
• Events. Up to 15 s in the SDK queue, then near real time into analytics.
• Behaviour in segments. Counts such as impressions, clicks and days since last active are rolled up into profiles hourly, so segments on them are up to an hour behind.

From a trait to a targeted block

A trait is a fact your app tells us about a device or a person. A segment is a named audience defined by rules over those facts. An instance is targeted at segments by name and id. This section walks the whole chain in the order you build it: send a trait → write a rule over it → create the segment → point an instance at it → prove it landed.

Read the warn notes even if you skim the rest. Three of them cover failures that return a success status and then reach nobody: an invalid trait key, a trait sent without consent, and a typo in seg.

1. Send a trait

Traits are sent on POST /sdk/v1/identify, authenticated with your SDK key in X-CF-Key. On /sdk/v1/* the key is the only required credential, and this call also needs X-CF-Device because it is about a device. No tenant header is needed: the key already names the workspace. The traits body field is optional, and its keys are flat: nesting goes inside a value, never in a key.

# "consent" is the user's recorded choice; true is shown for a user who opted in
$ curl -X POST https://api.contentflow.click/sdk/v1/identify \
     -H "Content-Type: application/json" \
     -H "X-CF-Key: $CF_SDK_KEY" \
     -H "X-CF-Device: $CF_DEVICE_ID" \
     -d '{
       "userId": "u_8812",
       "consent": true,
       "traits": { "region": "riyadh", "salary": 7200, "signupDaysAgo": 12 }
     }'

No declaration step exists. You do not register a trait before sending it, the first identify call that carries it is enough.

What the traits field does when you send a real set, leave it out, or send something odd:

2. Build a rule from the trait

Inside a segment rule a trait is addressed as customAttributes.<traitKey>. A trait called plan is matched with the field customAttributes.plan.

A rule is either a leaf or a group. Groups nest.

// leaf
{ "field": "customAttributes.plan", "operator": "equals", "value": "gold" }

// group, logicalOperator is "AND" or "OR"
{
  "logicalOperator": "OR",
  "conditions": [
    { "field": "customAttributes.plan", "operator": "equals", "value": "gold" },
    { "field": "customAttributes.salary", "operator": "greater_than", "value": 3000 }
  ]
}

Fields that are not traits carry their own prefix: demographic.*, behavioral.*, device.*, consent.*, location.*, metadata.* and enrichment.*. Note that POST /sdk/v1/identify does not populate demographic.*: identify sets traits, name, email, phone and the device id only.

3. Create the segment

Create the segment in the dashboard under Audience → Segments, with the rules from step 2. The rule builder there uses exactly the fields and operators above. Segments are managed in the dashboard, not with an SDK key.

4. Target an instance at the segment

In the dashboard, open the block instance and pick one or more segments as its audience. The instance stores them in two fields. seg holds the segment name, or the names joined with ", " when there are several. segIds holds the matching segment ids. Clearing the audience makes the instance untargeted.

When segIds is present, delivery matches by id, so renaming a segment in the dashboard keeps working. Writers that send names only (the API, cards as code) are matched by name until a backfill resolves the ids. The backfill runs hourly.

How it resolves at delivery

An instance reaches a device when any one of these is true:

• Its segIds include one of the device's segment ids, or (name-only writers) its seg names one of the device's segment names.
• seg is absent.
• seg is the empty string.
• seg is exactly All users.

The last three all mean untargeted. Matching is byte exact and case sensitive, so VIP and vip are different segments. A device with no segments sees only untargeted instances, which is a valid answer and not an error. A device gets no segments if it never called identify, or if its identify calls never reached granted consent. Delivery also filters on status and on schedule windows, independently of targeting.

Timing

Segment membership is recomputed when a trait value the write proposes actually differs from what is stored, so re-sending identical traits does not trigger a recomputation. A device's segment snapshot then refreshes at most once every 60 seconds. Expect roughly a minute for a targeting change to reach a device, not instant.

5. Prove it landed

Ask the platform which segments an identifier is in, rather than eyeballing a block that happened to render.

$ curl https://api.contentflow.click/api/v1/read/users/u_8812/segments \
     -H "X-CF-Read-Key: $CF_READ_KEY"

{
  "userId": "u_8812",
  "segmentNames": ["All users", "VIP customers"]
}

The second name is an example of a segment you created in your own workspace; yours will differ.

It answers with names, the same strings an instance's seg holds, so your assertion compares like with like. The {userId} slot accepts whatever the profile is keyed on, so a device id works there too. The full contract is on the REST API reference.

Integration checklist

1. Use the test key in development and the live key only in production builds. Never ship a write key or dashboard credentials in an app.
2. Create one client per workspace and account, and call start() on launch.
3. Set the user id on sign-in (setUserId), clear it on sign-out, and re-identify.
4. Ask for analytics consent before measuring, and for channel consent before messaging. They are separate calls.
5. Register block types as code from CI with the write key; give every slot a bundled fallback.
6. Track impressions and taps on every block (the React hooks do impressions for you) and conversions at the business outcome.
7. Register the push token after the OS grants permission, and again whenever it refreshes.
8. Handle dropReasons and the onEventsDropped / onEventsUncertain callbacks in your diagnostics.
9. Wire erasure: deleteIdentity() wipes the device only once the server confirms everything was deleted.

FAQ

Do I need to redeploy my app to change content?

No. Publishing an instance makes it live on the next GET /sdk/v1/sync your app performs, with no app release, no store review and nothing to redeploy. That's the whole point. The Get started shows the call.

Which SDK can I actually use today?

All four: JavaScript (web, React, React Native, Expo), Swift, Kotlin and Flutter. Each is distributed as an archive from the releases page on this site, not through a public package registry. The downloads are public and need no account or token; verify the published SHA-256 before installing. The REST API is also supported directly.

Why is my block empty, or stuck on old content?

An empty blocks list means nothing is published for the key's environment, or nothing targets this device. A wrong or suspended key does not give an empty list: it returns 401 INVALID_SDK_KEY. Work down this list:

1. Key and environment. A test key sees test and live content; a live key sees live only. The base URL is https://api.contentflow.click/sdk/v1; see the REST guide.
2. Identify and consent. Without analytics consent the device has no segments, so it gets only All users content.
3. Segment membership. Check the device's segments with the read call. Allow about a minute after a trait change.
4. Instance status. A draft or an instance waiting for approval is not delivered.
5. Schedule. The mode may be always, payday (the 25th to the 3rd), Ramadan (Hijri month 9) or a custom window. It is evaluated in the instance's schedule.tz, which defaults to Asia/Riyadh.
6. Frequency rules. A cap or cooldown may be hiding it for this device.
7. Device cache. The SDK may still be showing cached content until the next sync.
8. Sponsored content. Sponsored content is off by default, so an empty sponsored slot is normal.

Why didn't my SMS / WhatsApp campaign deliver?

The audience likely had zero contacts with phone + consent, or the workspace has no configured SMS or WhatsApp channel. Check both in the dashboard.

Can non-developers manage content?

Yes. Developers define block types in code; anyone can create and edit instances in the dashboard.

Glossary

Every term used across these docs, defined once.

Surfaces

The parts of ContentFlow you deal with directly, as they appear in the diagrams.