Custom blocks

A custom block is a reusable section you define once. It is built from block types that the app already ships. You can then use it on any screen.

Status: built. The app loads custom block definitions from the server, so a change needs no new store build. Web mode (below) is built, but has not been run on a real phone.

Why it is data, not code#

App stores do not allow apps to download and run new code. A custom block is a JSON file. It names the block types it uses, and it lists the settings a merchant can change. The app renders it with the blocks it already has.

There is no expression language, no eval, and no function text. Keys such as onPress, eval, __proto__ and constructor are rejected. So are javascript: and data: links, and <script in text.

Anatomy of a definition#

A definition has:

a key: 3 to 40 characters, lower case letters, digits and underscores, starting with a letter. The block type becomes custom_<key>.
a version: a whole number. Increase it each time you change the definition. A save with an older version is skipped.
a parameter schema: the settings a merchant can set, with types and defaults. Each parameter can have a format of uri, color, link, image or text.
a template: a list of nodes. Each node is an existing block type with settings.

Inside the template you can use:

{"$param": "path"} to put a parameter value into a setting.
{{param}} inside a text string, to put a value into the middle of text.
when: show a node only if a parameter is true, false, equal or not equal to a value.
repeat: show a node once for each item in a list parameter. Inside it, item.field reads the current item.

Templates can only use content and catalogue blocks, such as product carousels, banners, rich text, menus and collection grids. Core screen blocks (cart, product summary, account) and other custom blocks are not allowed.

Limits#

Definition size: up to 64 KB.
Template nodes: up to 40. Nesting depth: up to 8.
Text strings: up to 4000 characters.
Repeats: up to 20 per node.
Parameters: up to 40.
Patterns in the parameter schema are not allowed. This prevents slow regular expressions.

If a block's settings do not match its parameter schema, the block shows nothing.

Web mode#

A custom block can also be a web panel. It shows merchant HTML (up to 60,000 characters) or one https page in a sandboxed web view. The sandbox:

uses a private browsing session, no file access and no third-party cookies
blocks new windows
lets the page go only to about:blank or to allowed https hosts
applies a strict content security policy to inline HTML

The page talks to the app through one bridge, window.appBuilder.call(method, params). The bridge has these methods:

getContext: locale, platform, currency and the current product or collection. No customer data.
navigate: open a product, collection, page, search, tab, or an allowed https link.
addToCart: add a product variant, quantity 1 to 99.
track: send an event. The name is snake_case, with up to 10 flat properties. It appears as custom_web_<event>.
toast: show a short message.
resize: change the panel height, within a cap.

Each definition lists which methods its page may use. Each message is checked for size, shape, origin, method and parameters. The bridge allows 30 calls per 10 seconds.

Web mode needs care. Apple and Google review it under their web content rules. Test the panel on a real device before you publish.

Adding a definition#

Write the JSON definition.
Check it with appbuilder validate or the validate route. See CLI and API keys.
Save it as a custom block draft.
Enable it. Once enabled, the app loads it on its next config refresh.
Use it on a screen like any other block.

If you change a definition, bump its version. The app keeps the old version working until it refreshes.