Guides
Fetching config in your app
Code that reads hotcfg with a short timeout, revalidates with the ETag, keeps the last good copy and falls back to bundled defaults.
An app should never wait on hotcfg to start, or break when it can't reach it. The code below, for each language:
- sends the ETag it saved last time, so unchanged config costs a bodyless
304; - gives up after two seconds (offline, slow or hung);
- on any failure returns the last good copy it saved, and the first time, defaults bundled with the app.
import Foundation
#if canImport(FoundationNetworking)
import FoundationNetworking // Linux
#endif
enum HotcfgConfig {
static let url = URL(string: "https://api.hotcfg.run/v1/acme/mobile-flags")!
static let defaults = Data(#"{"features": {}, "limits": {"max_upload_mb": 10}}"#.utf8)
private static let cacheKey = "hotcfg.mobile-flags"
// Give up after 2 seconds in total, however slow or hung the network.
private static let session: URLSession = {
let config = URLSessionConfiguration.ephemeral
config.timeoutIntervalForRequest = 2
config.timeoutIntervalForResource = 2
return URLSession(configuration: config)
}()
/// The config as JSON: fresh, else the last good copy, else the defaults.
static func load() async -> Data {
let store = UserDefaults.standard
let cached = store.dictionary(forKey: cacheKey)
let cachedData = cached?["data"] as? Data
// Skip URLSession's own cache: the stored ETag does that job.
var req = URLRequest(url: url, cachePolicy: .reloadIgnoringLocalCacheData)
if cachedData != nil, let etag = cached?["etag"] as? String {
req.setValue(etag, forHTTPHeaderField: "If-None-Match")
}
do {
let (body, res) = try await session.data(for: req)
let status = (res as? HTTPURLResponse)?.statusCode ?? 0
if status == 304, let cachedData { return cachedData }
guard status == 200, (try? JSONSerialization.jsonObject(with: body)) != nil else {
return cachedData ?? defaults
}
let etag = (res as? HTTPURLResponse)?.value(forHTTPHeaderField: "ETag") ?? ""
store.set(["etag": etag, "data": body], forKey: cacheKey)
return body
} catch {
return cachedData ?? defaults // offline or timed out
}
}
}iOS 15, macOS 12 or later. Decode the result with JSONDecoder().decode(MyConfig.self, from: await HotcfgConfig.load()).
Each recipe was run against the same cases: first load, unchanged (304), a 503, a refused and a hung connection, each with and without a saved copy, then recovery. A hang costs two seconds in every one.
When to fetch
- Apps: at startup and when the app returns to the foreground. Apply the result on the next launch or screen if you'd rather not change things under the user.
- Servers: at startup and every minute or so, keeping the result in memory.
Private bins
Private bins are on Pro. Add Authorization: Bearer pk_live_… with a publishable key limited to that bin and environment. Without a key, a private bin answers 404, the same as a bin that doesn't exist.
Note
Public bins are served from Cloudflare's cache and purged on every publish, so most reads never reach hotcfg's servers. Private bins are never cached at the edge. For config read by many app users at once, prefer a public bin.
In a browser
ETag is readable across origins, so the JavaScript recipe works from any site. Unchanged config is still a 304.
Last updated 10 November 2026