A browser has srcset and sizes, and it sends an Accept header naming every image format it can decode. A mobile app has none of that automatically. An iOS UIImageView or SwiftUI AsyncImage, an Android view loaded by Coil or Glide, a React Native <Image>, or a Flutter Image.network asks for one URL and decodes whatever comes back. Which makes delivering images to an app simpler in one way — the app knows the exact dimensions of the box it is about to draw into — and easy to get quietly wrong in three others.

1. How the app identifies your account

The worst place for an API key is inside a shipped mobile binary. Anything compiled into an IPA or an APK can be read out of it, and unlike a website you cannot rotate a key in every installed copy of the app this afternoon.

You do not need a key in the app at all. The edge authenticates a delivery request in three ways, and two of them put no secret on the device:

  • By hostname. A request to your platform hostname (https://a3f9c21b.zwcld.net) or to a verified custom domain (https://img.example.com) identifies the account by itself. For public catalogue photos, avatars and editorial images, the app builds the URL and fetches it.
  • By a signed URL from your own API. When an image belongs to one user and must not be reachable by guessing its path, your backend signs the delivery URL with exp, kid and sig before returning it in the JSON response. The signing secret stays on your server; the app receives a normal HTTPS URL that works until its expiry timestamp and cannot be edited into another size or path.

And if you turn on the Bot & Hotlink Shield, your app keeps working. A native HTTP client (URLSession on iOS, OkHttp on Android) sends no Referer header, so the shield's default referrer rule lets it through while still refusing other websites that hotlink your images. Only turn on strict mode (which demands a matching Referer on every request) if your app sets a Referer header of its own on image requests or uses signed URLs.

2. Widths, pixel density and cache keys

On a phone, layout is measured in points or density-independent pixels (pt on iOS, dp on Android), while the screen draws 2× or 3× as many physical pixels. A card that is 360pt wide on a 3× phone needs a 1080px image.

The edge has two parameters for this — w in points plus dpr, or w in physical pixels directly — and they produce the same cache entry:

https://a3f9c21b.zwcld.net/v1/products/shoe.jpg?w=360&dpr=3&q=auto
https://a3f9c21b.zwcld.net/v1/products/shoe.jpg?w=1080&q=auto

The node multiplies w and h by dpr before it builds the cache key, so both URLs above resolve to the same 1080px rendition.

The trap on mobile is computing the width straight from the view's exact pixel size on every device. Across iPhones, iPads and a few hundred Android screen widths and density ratios (2.625, 2.75, 3.0), doing Math.round(viewWidth * scale) turns one product photograph into dozens of distinct URLs, which fragments your cache and makes every new screen size a cache miss.

Instead, snap the requested width up to a short list of buckets in the app before building the URL:

// TypeScript / React Native — snap to a fixed set of pixel widths
const WIDTHS = [160, 320, 480, 640, 960, 1280, 1920];

export function snapWidth(points: number, scale: number): number {
  const needed = points * Math.min(Math.ceil(scale), 3);
  return WIDTHS.find((w) => w >= needed) ?? WIDTHS[WIDTHS.length - 1];
}

In React Native or Expo, the @zawcloud/images package works directly — it has no DOM or Node dependencies:

import { PixelRatio } from 'react-native';
import { imageUrl } from '@zawcloud/images';

const url = imageUrl(
  '/products/shoe.jpg',
  {
    width: snapWidth(cardWidth, PixelRatio.get()),
    quality: 'auto',
    format: 'webp',
  },
  { baseUrl: 'https://a3f9c21b.zwcld.net' },
);

If you restrict permitted output sizes on the console's Limits tab, set the allowed widths to that exact bucket list. Anything outside the list is then refused with a 400 instead of filling the cache.

3. Choosing the format: explicit f or an Accept header

In a web browser, f=auto (the edge's default) reads the request's Accept header and picks AVIF if listed, else WebP, else JPEG or PNG.

Native networking stacks do not send a browser's Accept header by default. URLSession on iOS and OkHttp on Android send */* or no Accept header at all unless your image loader adds one. When the edge sees */* on an f=auto request, it cannot assume the caller has an AVIF or WebP decoder, so it falls back to JPEG or PNG — which is safe, and leaves most of the byte saving on the table.

You have two ways to get the smaller format in an app:

  1. Ask for it in the URL. Every current iOS (iOS 14+) and Android (Android 4.3+) decodes WebP natively, and iOS 16+ and Android 12+ decode AVIF. Passing f=webp (or f=avif where the OS version supports it) needs no custom header and makes the format explicit in the URL.
  2. Keep f=auto and send Accept from your image loader. Configure Coil, Glide, SDWebImage or Nuke once to send Accept: image/avif,image/webp,image/*,*/*;q=0.8, and the edge negotiates the format the same way it does for a browser.

In Swift (iOS / macOS), building the URL with URLComponents keeps parameter escaping exact:

import Foundation

func zawCloudUrl(
    path: String,
    pointsWidth: CGFloat,
    scale: CGFloat,
    preset: String? = nil
) -> URL? {
    let buckets = [160, 320, 480, 640, 960, 1280, 1920]
    let needed = Int(pointsWidth * min(ceil(scale), 3))
    let width = buckets.first(where: { $0 >= needed }) ?? buckets.last!

    var components = URLComponents(string: "https://a3f9c21b.zwcld.net")
    components?.path = "/v1/" + path.trimmingCharacters(in: CharacterSet(charactersIn: "/"))
    var items = [
        URLQueryItem(name: "w", value: String(width)),
        URLQueryItem(name: "f", value: "avif"),
        URLQueryItem(name: "q", value: "auto")
    ]
    if let preset = preset {
        items.append(URLQueryItem(name: "preset", value: preset))
    }
    components?.queryItems = items
    return components?.url
}

And on Android with Kotlin and Coil, adding an Accept header to the shared ImageLoader lets every URL stay on f=auto:

val imageLoader = ImageLoader.Builder(context)
    .okHttpClient {
        OkHttpClient.Builder()
            .addInterceptor { chain ->
                val request = chain.request().newBuilder()
                    .header("Accept", "image/avif,image/webp,image/*,*/*;q=0.8")
                    .build()
                chain.proceed(request)
            }
            .build()
    }
    .build()

4. Named presets for things you want to change without an App Store review

A website deploy takes minutes. An app release waits on review and then on users actually updating. If quality, sharpening, watermark position or corner radius are baked into the app's code, changing them means shipping a build.

Defining named presets in the console — ?preset=avatar, ?preset=product-card, ?preset=hero — moves those choices to the edge. The app passes the preset name (and, if needed, the snapped width w, since an explicit parameter in the URL always overrides the preset's default). When you adjust the preset's quality or crop mode in the console, existing app builds pick it up on their next request.

5. Placeholders and aspect ratios in your API responses

Scrolling lists on mobile jump for the same reason web pages do: the list cell does not know the image's height until the file arrives. And a grey box on a slow cellular connection looks empty until it decodes.

Every delivery URL accepts ?info=true (or ?blurhash=true / ?thumbhash=true) and returns JSON describing the rendition instead of the image bytes: its output width and height, dominant and average hex colours, a BlurHash, a ThumbHash, and a tiny 20px data-URI preview.

GET /v1/products/shoe.jpg?w=640&info=true

Do not call ?info=true from the mobile app on every scroll — that would double the number of HTTP requests the device makes. Fetch it once on your backend when an image is added to a product or post, and store the width, height and thumbhash (or blurhash) alongside the image path in your database. Your API then sends all three in the list response, so the app sizes the cell and draws the placeholder on the very first frame, while the image itself is still in flight.