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.json
{
  "flags": { "newCheckout": true },
  "overrides": [
    { "platform": "ios", "maxBuild": 320, "flags": { "newCheckout": false } }
  ]
}

The filter

An iOS app on build 315 sends:

filter
.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:

terminal
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:

Swift
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:

filter
"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:

schema.json
{
  "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. iOS CFBundleVersion and Android versionCode are 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. Raise maxBucket to 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 empty 200, so the fetch code falls back to its last good copy. See Querying with jq.

Last updated 10 November 2026