Skip to content
HotLayout Docs
npmpub.devGitHub
Menu

Quickstart for iOS

This page is for an iOS developer. It shows how an app draws a screen that a manager published in HotLayout, using the native reader for iOS: a Swift package that turns a JSON document, a theme and your data into a SwiftUI screen.

Access. The iOS reader is not published in a public registry and its source is not public. It is available to customers on request: access is given with a licence or a trial. Write to contact@hotlayout.com and you will get the package together with instructions for adding it to your project. The React and Flutter packages are open source; see Quickstart for React and Quickstart for Flutter.

Related pages: index · delivery · data dictionary · theme · localization · compatibility · widgets · quickstart for Android

What you are integrating#

Piece What it is
Document One JSON file: a set of screens built from widgets. Published by the builder as published.json.
Theme One JSON file: the token names the project has and the values behind them.
Data A map your app supplies: values for the paths the document is bound to (user.name, user.points).
Reader The HotLayout Swift package: it draws the three as a SwiftUI view.

The reader renders document contract 9.27.0, passes the shared tables of cases that the React and Flutter readers pass, and is covered by UI tests. As with every reader, the major version of the contract must match: it draws any 9.x document and no 8.x one (see Compatibility policy).

Requirements#

  • iOS 16 or later (the package also builds for macOS 13 so that its tests run with swift test)
  • Swift 5.9 or later
  • no third-party dependencies

Draw a screen#

Load the document with the tolerant reader, read the theme, and put HotlayoutScreen where the screen goes:

import HotLayout

let document = try loadDocument(jsonData)          // tolerant read + version gate
let theme = HotlayoutThemeSet.read(themeJSON) ?? .builtIn

HotlayoutScreen(
    document: document,
    theme: theme,
    data: ["user.name": "Maya", "user.points": 1850],
    locale: Locale.current.identifier,              // the device locale, as is
    entry: "promo",                                 // a named entry point, optional
    onAction: { action, source in
        // The reader opens nothing itself. A standard action arrives checked:
        if let url = StandardActions.url(for: action) { openURL(url) }
    },
    onTrack: { event, source in analytics.log(event.event, event.params) },
    onScreenChange: { shown in print(shown.screenId, shown.cause) }
)

The helpers checkDocumentVersion, loadDocument and resolveLocale can also be used without the view.

Where jsonData and themeJSON come from is your choice: your backend after a signed webhook, or the published address of the project. See Delivery options.

What the reader does and does not do#

  • The document is untrusted input. A piece of the wrong shape is skipped and reported through onReport; it is never a crash. A tree deeper than 32 levels is refused.
  • The reader opens nothing by itself. Navigation inside a document (navigate, navigate.back, navigate.section) is done by the reader. openUrl, deeplink, close and the actions of your app go to onAction, and a standard action arrives already checked.
  • Images load only over https: by default. Pass an ImagePolicy to decide yourself, and to give addresses for the asset tokens (logo, banner, placeholder).
  • The locale is the device locale, passed as is; the reader picks the document's language by the contract's rule and mirrors the layout for right-to-left scripts. See Localization.
  • Data stays with you. The reader takes the values you pass in data; it never calls your backend.

Status#

The rules of the contract (versions, data, conditions, text, numbers, dates, plurals, locale, actions and navigation) are in place and pass the shared tables. Every widget of contract 9.27.0 is drawn natively, including the fixed app bar and bottom zone, input fields (with composed input for CJK keyboards), lists, tabs, progress, carousels, modal layers and motion; behaviour is checked with UI tests on a simulator. Platform limit: glass uses the system blur, so its strength is close to, but not exactly, the contract's blur radius.

Next#