Implementation Patterns8 min read

Serving Content to Native iOS and Android Apps Alongside the Web From One Backend

An editor corrects a price on a promo, the website updates within seconds, and the iOS app keeps showing the old number because the copy lives in an HTML blob inside a webview that nobody remembered to refresh.

Published November 14, 2026

An editor corrects a price on a promo, the website updates within seconds, and the iOS app keeps showing the old number because the copy lives in an HTML blob inside a webview that nobody remembered to refresh. The fix is to serve native iOS and Android apps and the web from one backend as presentation-free structured content. In Sanity, Swift, Kotlin, and web clients send GROQ queries over HTTPS to the same Content Lake, and each one renders the JSON with its own components.

Mobile raises the stakes compared with the web. Old app builds stay installed for months and keep sending the same requests, so one renamed field breaks things for real users. Phones go offline, users pay for data, and images need to match each screen. App store review runs on its own schedule, so new content and the build that displays it rarely ship on the same day.

This guide treats native delivery as a modeling and contract problem, not a transport problem. It covers how to structure content without layout, keep old builds working, cache content for offline use, keep payloads small, and preview content against builds that haven't shipped yet.

Why does page-shaped HTML break native iOS and Android apps?

Page-shaped HTML breaks native apps because it bakes one channel's layout into the content, and SwiftUI, Jetpack Compose, and React Native can't use that layout. Suppose a CMS saves a landing page as a rich-text blob with inline styles, CSS classes, column widths, and embedded iframes. The web renders it fine. A native app is left with two bad options. It can drop the blob into a webview, which looks and scrolls like a website stuck inside an app. Or it can use a fragile HTML parser that fails the first time an editor pastes an unfamiliar embed.

Channel-agnostic structured content is the precondition for serving mobile and web from one source. Structured content splits content into typed fields with meaning, such as a headline, a summary, an image, a price, or a reference to a related product, instead of a document formatted for one screen. Each client then decides how to present it. The website might show the summary under a hero image 1200 pixels wide. The iOS app might show it in a compact card in a list, and an Android widget might show only the headline.

A common counter-argument is that a separate mobile API, or a mobile copy of the content, is simpler. In practice the copy drifts. Editors update the web version and forget the app version, and support tickets arrive about prices or policies that don't match across channels. Two backends also mean two sets of permissions, two ways to preview, and two places to audit.

In Sanity, the Schema is defined in code and describes fields by meaning, so the same document in the Content Lake serves the website and both native apps. Web and mobile clients send GROQ queries to the same dataset, and each one projects only the fields it renders. This is the Power anything pillar of Sanity, the AI Content Operating System: serve content to every channel from a single source of truth, using structured content with clear meaning and API-first delivery, instead of running a separate content system for each platform.

How do you model presentation-free content for SwiftUI, Jetpack Compose, and React Native?

Presentation-free content is content modeled as typed fields and structured rich text with no HTML, CSS classes, or layout widths, so each native framework renders it with its own components. A promo card becomes a document with a headline, a summary, an image with a hotspot, and a reference to a call-to-action target. Nothing in it says 'two columns' or 'blue button.' SwiftUI maps it to a VStack, Jetpack Compose maps it to a Card composable, and the web uses whatever its design system provides.

Rich text is where most teams slip back into HTML. Body copy needs bold text, links, headings, and inline objects, and the easy path is to save markup. The better path is a JSON format. Paragraphs are blocks with a style, inline formatting is a list of marks, and embedded objects such as a product reference or a video are custom block types with their own fields. A renderer on each platform walks through the blocks and maps every style, mark, and type to a native view.

Sanity structures rich text as Portable Text, which uses exactly that JSON shape. The renderer situation needs a realistic look, though. The official @portabletext/react-native package exists but is marked experimental on npm, and there is no official SwiftUI or Jetpack Compose renderer. iOS and Android teams write their own mapping, usually a switch over block style, mark type, and custom block _type that returns a Text, an AttributedString, or a composable. Each platform writes this mapping once. It's also where you enforce your design system, because unknown types can fall back to a safe default instead of crashing the screen.

Two modeling habits pay off across channels. First, model links as references to documents instead of URLs, so the app can open a native screen while the web goes to a path. Second, store editor intent in fields, not formatting. An 'emphasis level' field works on every platform, while a hex color only fits one. In Sanity Studio you can build the editing interface around these fields with custom inputs, so editors work with what the content means, not how it looks.

How do you keep old app versions working when the content schema changes?

To keep old app versions working, treat every shipped binary as a permanent API client, because some users never update and the app stores give you no reliable way to force them. When a website deploys, every visitor gets the new code. An iOS or Android build stays installed for months, sending the same request and expecting the same response shape. If a content change renames a field or changes its type, those older builds break for users while the latest build looks fine in testing.

Two rules prevent most of these breaks. First, make schema changes additive. Add new fields, keep old ones filled in until telemetry shows the builds that read them are gone, and never change the type of an existing field in place. Second, make the client tolerant. Decode with optional fields and ignore unknown keys, so a new field never crashes a Codable struct or a Kotlin serialization model.

Sanity adds a third layer at the API level. Every request is pinned to a date version, written vYYYY-MM-DD, which fixes how the API behaves. The docs say to write the date as a literal string. If you compute it at runtime, the version changes every day, and API behavior can shift without you deploying anything. A shipped binary keeps its pinned version, so an app built long ago keeps getting the behavior it was tested against. Sanity may still apply backward-compatible changes to old versions, such as new GROQ operators and functions, new optional parameters, or new _-prefixed metadata. That's one more reason to ignore unknown fields. When a version is eventually retired, calls to it return HTTP 410. The X-Sanity-Deprecated and X-Sanity-Warning response headers give notice ahead of time, so the app should log them.

The GROQ projection inside each app build becomes that build's contract. Version 3.2 asks for headline, summary, and image. Version 3.4 also asks for a badge. Both read the same documents in the Content Lake, and neither sees fields it doesn't expect.

In a native app, the query is the contract

The GROQ projection compiled into a build sets the exact response shape that build will ever receive. Adding to the Schema is safe for old builds as long as the old fields stay filled in. Renaming a field is a breaking change for every installed version that asks for it, even though the API itself never changed.

How should native apps handle offline caching and live content updates?

Native apps should cache query results locally, show cached content right away, and refresh only the queries whose content has changed. Mobile networks drop out, and an app that shows a spinner on launch because it can't reach the backend feels broken in a way a website doesn't. Offline-first apps usually save the last good response for each screen in SQLite, Core Data, Room, or plain files, then sync up when the connection returns.

The hard part is knowing when a cached response is stale without downloading everything again. Polling on a timer wastes battery and data. A change feed works better, as long as it tells the client which cached results are affected.

In Sanity, a query response includes result, ms, query, and syncTags. The Live Content API is recommended for new projects. It's a Server-Sent Events stream at GET https://<projectId>.api.sanity.io/v2025-02-19/data/live/events/<dataset> that sends events listing sync tags that have changed for published content. Public data needs no auth. When an event's tags match the syncTags saved with a cached query, the app reruns that query and replaces the cached entry. Send last-event-id to resume after a reconnect, and handle the welcome, restart, error, and goaway events. Listeners always connect to the live API, not the CDN.

There is a real gap here. Sanity documents no built-in offline storage or sync SDK, and there is no official Swift or Kotlin client. Saving results by query and syncTags is the app's job. Contentful offers more out of the box, with official Swift and Android SDKs, a Sync API, and contentful-persistence.swift backed by Core Data. In return, Sanity lets each build cache exactly the payload it renders instead of syncing complete entries.

Functions can help on the server side. A document function that runs on create or update events can warm a cache, trigger a push notification, or prepare a mobile-specific payload ahead of time, so users open the app to fresh content instead of waiting for a fetch.

â„šī¸

What Sanity does not ship for mobile

Sanity has no official Swift or Kotlin SDK and no built-in offline sync layer, and @portabletext/react-native is experimental. Native apps call the Query API over HTTPS, store results themselves, and use Live Content API sync tags to decide what to refetch. Plan engineering time for that client layer.

How do you control payload size and image transforms per device?

To keep payloads small on mobile, ask the backend for only the fields a screen renders, and request images at the exact pixel size and format the device displays. A list screen that downloads full article bodies just to show twenty titles wastes data and slows the first render. An image served at desktop width to a phone uses bandwidth on pixels nobody sees.

On the data side, the fix is projection. A GROQ query names exactly the fields and linked documents a screen needs. The list query returns titles, thumbnails, and slugs, and the detail query returns the full body. The same query can follow a reference with -> to pull a related author's name inline, which saves a second round trip on a slow connection. Send requests through the API CDN at https://<projectId>.apicdn.sanity.io, where cached responses aren't rate limited. GET requests are capped at 11 KB, and the CDN also caches POST, so long queries still benefit.

For images, project image.asset->url in GROQ and add transform parameters to the cdn.sanity.io URL, for example ?w=800&fit=max&fm=webp. Width and height must be integers, fit=max prevents upscaling, and dpr handles high-density screens. One detail matters for native apps: auto=format picks a format from the browser's Accept header, so the docs say to set fm (jpg, pjpg, png, or webp) yourself in a native app. The @sanity/image-url helper is JavaScript-only, so Swift and Kotlin code applies the editor's crop and hotspot directly. It calculates rect=x,y,width,height from the fractions saved on the image field.

Pick a small set of image sizes for the whole app, such as a thumbnail, a card, and a full-width image, each multiplied by the device's screen scale. When every screen uses the same sizes, they share cached variants instead of each requesting its own. For most mobile content pipelines, this is the cheapest performance win available, and it needs only a shared constants file in each codebase.

How do you preview content and coordinate content releases with app releases?

Preview for native apps works when an internal build can point the same query at unreleased content while the store build keeps reading only published content. App releases and content releases run on different clocks. A new onboarding flow might ship in a build that clears review on an unpredictable date, while its content has to be written, reviewed, and ready beforehand. Without coordination, one of two things happens. Either the content goes live and confuses users on old builds, or the new build ships pointing at empty fields.

Sanity handles the content side with Perspectives and Content Releases. A perspective tells the Content Lake which version of the content to return: published, drafts, raw, or a stack of release IDs such as ['release-id1','release-id2']. Since API version 2025-02-19, the default perspective is published, and the Content Releases APIs require 2025-02-19 or newer. GROQ helpers such as releases::all() and sanity::partOfRelease() let tools list and filter release content. Queries that use drafts aren't cached on the CDN, so preview requests should set useCdn to false.

One useful pattern, which is a convention and not a packaged feature, is to have internal and TestFlight builds pass a release perspective through an authenticated proxy. QA then sees the upcoming app build alongside the content release planned for it, while the store build stays on published. When the build is approved, the team publishes the release. The new fields appear for the new build, and old builds never ask for them, so they're unaffected.

Security shapes this pattern. Treat anything shipped in an app binary as public. Unauthenticated requests to a public dataset read only published content and can't see drafts or release versions, so the store build needs no token. Preview, private datasets, and writes go through a server or cloud function you control that holds the token, with one robot token per application. Image and file assets aren't private even in a private dataset, so never count on an asset URL staying secret.

Serving native apps and web from one backend: Sanity vs Contentful, Hygraph, and Strapi

FeatureSanityContentfulHygraphStrapi
Native client SDKsNo official Swift or Kotlin SDK. Native apps send GROQ to the Query API over plain HTTPS and decode the JSON. Community clients exist for Flutter, Rust, and C#.Official Swift (iOS) and Android SDKs maintained by Contentful, the most complete ready-made native client story of the platforms compared here.GraphQL-first API, so mobile teams can use standard GraphQL tools such as Apollo iOS or Apollo Kotlin against the endpoint.Apps call the REST or GraphQL API directly. Client code and generated types are usually built and maintained by the team.
Shaping the payload for each app versionOne GROQ projection per build returns exactly the fields and dereferenced references (->) a screen renders, in one round trip. That projection serves as the build's contract.REST returns whole entries, with include depth for linked entries. GraphQL lets clients pick fields, so payload shaping depends on which API the app uses.GraphQL selection sets let each app version request only the fields it renders, which fits well with per-build contracts.REST has populate and field selection parameters, and the GraphQL plugin allows selection sets. The team picks an approach and maintains it.
API stability for old app buildsEvery request is pinned to a literal date version (vYYYY-MM-DD), so old binaries keep the behavior they were tested on. Retired versions return 410 after X-Sanity-Deprecated notice headers.Delivery APIs plus versioned official SDKs. Teams still need to make content type changes additive so older builds keep decoding responses.The GraphQL schema changes as your content models change. Older builds stay safe when fields are added rather than renamed or removed.Self-hosted, so the team decides when the API changes. Keeping shipped builds backward compatible is the team's responsibility.
Offline caching and syncNo built-in offline SDK. Apps cache results by syncTags and rerun queries when Live Content API Server-Sent Events report that those tags changed.Strongest native offline story here: a Sync API for incremental updates and contentful-persistence.swift for Core Data storage on iOS.No dedicated offline layer is assumed here. Teams usually rely on GraphQL client caches, such as Apollo's normalized cache, for offline reads.The team builds offline storage and change detection, usually with polling or webhooks that feed a local store in the app.
Image transforms per devicecdn.sanity.io URL parameters (w, h, fit=max, dpr, fm=webp, and rect for editor crop and hotspot), built on image.asset->url from the same GROQ query.The Images API supports resizing and format conversion through URL parameters, so apps can request sizes that fit the device.Offers asset transformations through its API. Check parameter coverage for native format needs before relying on it for every screen size.The upload plugin creates responsive formats at upload time. On-the-fly transforms usually need a provider or an image CDN that the team sets up.
Previewing unreleased content in internal buildsPerspectives return the same query as published, drafts, or a stack of Content Release IDs. Internal builds pass a release perspective through an authenticated proxy.The Content Preview API serves draft content with a separate token, so internal builds can point at preview while store builds use delivery.Content stages keep draft and published content separate. Internal builds can query the draft stage with a token that has the right permissions.Draft and published states are built in. Internal builds query drafts through an authenticated endpoint that the team sets up and secures.
Rich text for native renderersPortable Text JSON with block styles, marks, and custom _types. @portabletext/react-native is experimental, and SwiftUI and Compose teams write their own mapping.The Rich Text field returns a JSON node tree. Native apps map each node type to a view in SwiftUI, UIKit, or Jetpack Compose.Rich text is available as structured AST JSON alongside other output formats, so native apps can render from the AST.The blocks editor returns structured JSON in recent versions. Older Markdown fields need a Markdown renderer in the native app.

Ready to try Sanity?

See how Sanity can transform your enterprise content operations.