Recipes
Version and platform targeting with jq
Turn a feature off for old builds, one platform or a percentage of users, with overrides in your config and a jq filter in the URL.
hotcfg has no user-level targeting: it doesn't know who your users are. But an app knows its own platform and build number, so it can ask for config merged for exactly that, with a jq filter in the URL. The rules live in your config, under the same schema, history and rollback as everything else.
The config
Default flags, then overrides that apply to some platforms and builds:
{
"flags": { "newCheckout": true },
"overrides": [
{ "platform": "ios", "maxBuild": 320, "flags": { "newCheckout": false } }
]
}The filter
An iOS app on build 315 sends:
.flags * ([.overrides[] | select(.platform == "ios" and 315 <= .maxBuild) | .flags] | add // {})and gets {"newCheckout": false}. Build 321 gets {"newCheckout": true}. With no matching override, add // {} keeps the defaults.
The filter has to be URL-encoded. With curl:
curl -G "https://api.hotcfg.run/v1/acme/mobile-flags" \
--data-urlencode 'query=.flags * ([.overrides[] | select(.platform == "ios" and 315 <= .maxBuild) | .flags] | add // {})'In Swift, build the URL with URLComponents and pass it to the fetch code:
let build = Int(Bundle.main.infoDictionary?["CFBundleVersion"] as? String ?? "") ?? 0
var url = URLComponents(string: "https://api.hotcfg.run/v1/acme/mobile-flags")!
url.queryItems = [URLQueryItem(name: "query", value:
".flags * ([.overrides[] | select(.platform == \"ios\" and \(build) <= .maxBuild) | .flags] | add // {})")]In JavaScript, new URLSearchParams({ query: filter }) encodes it.
Design the rules up front
The filter ships inside your app binary. You can change the rules in your config at any time, but not the filter in builds already installed. So give every app a filter that understands every kind of rule you might want, with each field optional:
"ios" as $platform | 315 as $build | 42 as $bucket
| reduce (.overrides[]?
| select((.platform == null or .platform == $platform)
and (.minBuild // 0) <= $build and $build <= (.maxBuild // 1e9)
and (.minBucket // 0) <= $bucket and $bucket <= (.maxBucket // 99))
| .flags) as $f (.flags; . * $f)The app fills in the first line. Rules can then use any of platform, minBuild, maxBuild, minBucket and maxBucket, and matching rules apply in order: later rules win, and nested objects are merged, not replaced. A config with no overrides at all returns flags unchanged.
Keep the rules valid with a schema, so a typo can't silently match nothing:
{
"type": "object",
"required": ["flags"],
"properties": {
"flags": { "type": "object" },
"overrides": {
"type": "array",
"items": {
"type": "object",
"required": ["flags"],
"additionalProperties": false,
"properties": {
"platform": { "enum": ["ios", "android", "web"] },
"minBuild": { "type": "integer" },
"maxBuild": { "type": "integer" },
"minBucket": { "type": "integer", "minimum": 0, "maximum": 99 },
"maxBucket": { "type": "integer", "minimum": 0, "maximum": 99 },
"flags": { "type": "object" }
}
}
}
}
}Things to know
- Use integer build numbers, not version strings. jq compares strings character by character, so
"3.10" < "3.9"is true. iOSCFBundleVersionand AndroidversionCodeare integers already. - Percentage rollouts work the same way: the app picks a bucket from 0 to 99 once (at random, or from a hash of an install id), stores it, and sends it.
{"maxBucket": 9, "flags": {...}}reaches 10% of installs. RaisemaxBucketto roll out further. - Caching: each distinct filter (so each build, platform and bucket) is its own cache entry at the edge. It's cached and purged on publish like the plain URL, and served for up to a week if our servers are down. The first read of each filter in each Cloudflare data center reaches our servers.
- Errors are errors. A filter that fails, or returns nothing, answers
422, never an empty200, so the fetch code falls back to its last good copy. See Querying with jq.
Last updated 10 November 2026