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](https://hotcfg.run/docs/guides/queries) in the URL. The rules live in your config, under the same [schema](https://hotcfg.run/docs/guides/schemas), 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](https://hotcfg.run/docs/guides/fetching):

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](https://hotcfg.run/docs/guides/queries).

Last updated 10 November 2026
