Developers

Website and email blocks

How your app adds content to a venue's website, custom booking page and marketing emails, and how to frame a page of your own as a widget.

A venue's guests meet it in more places than the booking. They read its website, land on its custom booking page and open its marketing emails. Your app can put its own content in all three. A board game library can show this month's new games on the home page and in the newsletter, and offer a search box on a page of its own.

Your app writes no page and no email. It declares the blocks it offers. The venue places them in its editors, fills in the settings of each placed copy, and BookingNinja asks your app for the content and draws it in the venue's own fonts and colours.

Declare the blocks

Blocks are listed in the manifest, under extension_points:

  • website_blocks for the venue's website and custom booking page.
  • email_blocks for its marketing emails, both campaigns and automations.
json
{
  "extension_points": {
    "website_blocks": [
      {
        "key": "new_games",
        "label": "New games",
        "description": "The newest games on the shelf.",
        "icon": "dice",
        "settings": [
          { "key": "count", "type": "number", "label": "How many games", "default": 4 },
          { "key": "category", "type": "select", "label": "Category", "default": "any",
            "options": [ { "value": "any", "label": "Any category" }, { "value": "Party", "label": "Party" } ] }
        ]
      },
      {
        "key": "library_search",
        "label": "Game library search",
        "kind": "widget",
        "surfaces": ["website"],
        "widget": { "url": "https://games.example.com/widget", "height": 600 }
      }
    ],
    "email_blocks": [
      {
        "key": "new_games",
        "label": "New games",
        "sample": "This month's new games",
        "settings": [ { "key": "count", "type": "number", "label": "How many games", "default": 4 } ]
      }
    ]
  }
}

An app may declare up to 10 website blocks and 10 email blocks. Each one has:

Field What it is
key The block's identifier, lower case with underscores. It is unique within its list and is sent back to you as block. A website block and an email block may share a key.
label The name in the editor's block list. Up to 40 characters.
description One line under the name.
icon A name from the same icon set as staff blocks.
settings The fields the venue fills in for each copy it places. Up to 12.
kind Website blocks only. content, the default, is drawn by BookingNinja from your reply. widget is a page of your own (see below).
surfaces Website blocks only. Where the venue may place it: website, booking_page, or both, which is the default.
sample Email blocks only. Words shown in the email editor's canvas when your app cannot be reached.

Settings use the same field types as everywhere else in your manifest (see the settings guide). Two limits are particular to blocks: a field's options cannot come from your app live (options may not be remote; a manifest that uses it is refused when you save or register it), and an info field shows its text and holds no answer.

Because the settings belong to each placed copy, a venue can put the block on its home page with four games and on its party page with a category chosen. A field the venue left blank carries its default.

What happens when a venue places a block

BookingNinja calls POST content-blocks at {base_url}/content-blocks, signed like every other call (see the signatures guide).

json
{
  "context": {
    "installation_id": "ins_8f3k2m",
    "venue": { "id": "ven_4d7a1c", "name": "The Dice Cafe", "timezone": "Europe/London", "currency": "GBP", "locale": "en-GB" },
    "settings": { "venue": { "library_id": "lib_main" }, "session": {} }
  },
  "surface": "website",
  "block": "new_games",
  "settings": { "count": 4, "category": "any" },
  "preview": false
}
Field What it is
context The installation, the venue and the venue's saved settings for your app. settings.session is always empty, because no session is involved.
surface Where the block is placed: website, booking_page or email.
block The key you declared.
settings What the venue filled in for this copy of the block.
preview True while the venue is looking at the block in an editor.

There is no booking in the context and no guest anywhere in it.

When BookingNinja asks

A guest never waits for your app. When someone opens the venue's website, BookingNinja shows content from a copy it already holds.

  • Websites and the booking page. BookingNinja fetches the content in the background and keeps it for valid_for_seconds: between 60 and 86400 seconds, 900 if you leave it out. When that time has passed it asks again, and keeps showing the old copy until the new answer arrives. Choose a time that matches how often your content changes. A list of new games might be an hour. Tonight's availability might be a minute.
  • Editors. While a venue edits, BookingNinja asks live, with preview true, so the venue sees the real thing as it changes a setting. A preview answer is shown to the venue only and is not kept.
  • Emails. BookingNinja asks once when it builds the email: when a campaign starts sending, or each time an automation runs. Everyone who receives that email gets the same content. valid_for_seconds means nothing for an email.

Your app has 3 seconds to answer.

When your app fails

  • On a website, BookingNinja keeps showing the last good copy. If it has never had one, the block is left out. The rest of the page is not affected.
  • In an email, a block that cannot be fetched is left out.
  • In an email editor, the canvas shows the block's sample words in place of content it could not fetch.

When there is nothing to show

Reply with an empty blocks list. The block is left out of the page or the email. When the venue has ticked "Only send when this has something" on an email, an empty answer means that email is not sent at all. This is the right answer for "no new games this month". Do not reply with a block that says there is nothing, and do not reply with an error.

The content you send

json
{
  "blocks": [
    { "type": "text", "text": "New on the shelf", "style": "heading" },
    {
      "type": "cards",
      "layout": "grid",
      "cards": [
        {
          "title": "Blokus",
          "meta": "2-4 players",
          "text": "Fit your pieces in and block everyone else.",
          "image_url": "https://games.example.com/images/blokus.jpg",
          "alt": "The Blokus box",
          "link": { "label": "See the game", "url": "https://games.example.com/games/blokus" }
        },
        {
          "title": "Wavelength",
          "meta": "2-12 players",
          "text": "Read each other's minds, and argue about it.",
          "price": "Free to play",
          "image_url": "https://games.example.com/images/wavelength.jpg",
          "alt": "The Wavelength box"
        }
      ]
    },
    { "type": "button", "label": "Browse the full library", "url": "https://games.example.com/library", "style": "primary" }
  ],
  "valid_for_seconds": 3600
}

blocks is up to 20 blocks, drawn in order. They are the same kind of blocks as in the guest step, so one vocabulary covers a lot:

Block What it is for
text A paragraph, or a heading when style is heading
notice A boxed message with an optional bold title and a tone
hero One large picture with a heading and a few words
gallery Pictures to look at
steps A numbered list of what happens
details Labelled rows, such as opening hours
faq Questions and their answers
table A small table
links A short list of links
divider A line between groups
cards A set of cards: new games, upcoming events, this week's specials
button One button linking out

Two of them are particular to this call. A cards block holds up to 12 cards. Each card has a title and may have a meta line above it (a date, a category, a player count), some text, a price, a picture and a link. The price is plain text, such as £4 or Free, and BookingNinja does no sums with it. With the grid layout the cards sit side by side, two to four across depending on the screen. With list each card is one row with the picture beside the words. A button is a label, an HTTPS url and a style of primary or secondary. Pictures and links must be HTTPS.

A block type BookingNinja does not know is left out and the rest is kept, so your app can start sending a new type before every venue has it.

How a block looks

BookingNinja draws every block in the venue's own fonts and colours. Your app does not choose them. The same reply is drawn differently where there is less room:

Websites and the booking page Emails
gallery A carousel or a grid, as you ask Always a grid
faq Each answer opens when the guest taps its question Every answer is shown
cards Two to four across, one across on a phone Narrow columns, so they stack
Pictures Shown from BookingNinja's own copy Always BookingNinja's own copy
Links Open in a new tab Tracked like every other link in the email

Pictures are copied by BookingNinja when it fetches your content. A guest's browser or mail app never contacts your host to draw your content, and nothing of yours has to stay up for the page to show. That is also why an email carries no address of your app: it holds only BookingNinja's copy of each picture, and links that go through BookingNinja's tracking.

Keep a picture's alt filled in. It is what a screen reader reads, and what an email shows when a mail app blocks pictures.

Widgets

Sometimes content is not enough. A search box, a calendar you run yourself or a quiz need a page of your own. A website block with kind set to widget is that page, framed on the venue's website. BookingNinja does not call content-blocks for it.

Use a content block when what you show is a list or some words. It loads fast, matches the venue's design and costs nothing to host per visit. Use a widget only when the guest needs to do something on the page. A widget cannot be put in an email.

json
{
  "key": "library_search",
  "label": "Game library search",
  "kind": "widget",
  "surfaces": ["website"],
  "widget": { "url": "https://games.example.com/widget", "height": 600, "min_height": 300, "title": "Search the game library" }
}
  • url is HTTPS, on port 443, on a host of your own. It cannot be a BookingNinja or letsbookfor address.
  • height is the frame's starting height in pixels, between 120 and 2000. min_height is the smallest it may be made.
  • title is the frame's accessible title. It defaults to the block's label.

BookingNinja has to switch widgets on before they appear in a venue's editor. While they are off, a widget block is not offered at all, and content blocks work as normal. Ask BookingNinja if yours is not showing.

The token

BookingNinja frames {url}?token=<token>. The token tells your page which venue, block and settings it was made for. It is a compact HS256 JWT with these claims:

Claim What it is
iss Always bookingninja
aud Your app's public id, app_…
installation The installation, ins_…
venue The venue's opaque id, ven_…
block The key of the block
surface website or booking_page
settings What the venue filled in for this copy (at most 2 KB as JSON)
hosts The hosts of the page the frame is on, empty in an editor preview. Answer with a matching Content-Security-Policy: frame-ancestors, and refuse a token framed elsewhere
iat When it was issued, in unix seconds
exp When it expires: 24 hours after iat. A page left open longer is reloaded with a fresh token.

The token is signed with a key made from your signing secret, not with the secret itself. The key is the lowercase hex of HMAC-SHA256 of the text bookingninja-widget-v1, keyed with your signing secret. Use that hex text, as it is, as the key for the JWT's HMAC-SHA256.

Check the signature, iss, aud and exp before you draw anything. Reject a token whose header says anything other than HS256.

php
<?php
// widget-token.php
function verifyWidgetToken(string $token, string $signingSecret, string $appId): ?array
{
    $parts = explode('.', $token);
    if (count($parts) !== 3) {
        return null;
    }
    [$header, $payload, $signature] = $parts;
    $decode = fn (string $part) => base64_decode(strtr($part, '-_', '+/'), true);

    if (($decode($header) ? json_decode($decode($header), true)['alg'] ?? null : null) !== 'HS256') {
        return null;
    }
    $key = hash_hmac('sha256', 'bookingninja-widget-v1', $signingSecret);
    $expected = hash_hmac('sha256', $header.'.'.$payload, $key, true);
    if (! hash_equals($expected, (string) $decode($signature))) {
        return null;
    }
    $claims = json_decode((string) $decode($payload), true);
    if (! is_array($claims) || ($claims['iss'] ?? null) !== 'bookingninja' || ($claims['aud'] ?? null) !== $appId || ($claims['exp'] ?? 0) <= time()) {
        return null;
    }
    return $claims;
}
js
// widget-token.mjs
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyWidgetToken(token, signingSecret, appId) {
  const parts = token.split('.');
  if (parts.length !== 3) return null;
  const [header, payload, signature] = parts;
  try {
    if (JSON.parse(Buffer.from(header, 'base64url')).alg !== 'HS256') return null;
    const key = createHmac('sha256', signingSecret).update('bookingninja-widget-v1').digest('hex');
    const expected = createHmac('sha256', key).update(`${header}.${payload}`).digest();
    const given = Buffer.from(signature, 'base64url');
    if (given.length !== expected.length || !timingSafeEqual(given, expected)) return null;
    const claims = JSON.parse(Buffer.from(payload, 'base64url'));
    if (claims.iss !== 'bookingninja' || claims.aud !== appId || claims.exp <= Date.now() / 1000) return null;
    return claims;
  } catch {
    return null;
  }
}

The page is public. Anyone can open its address, and a token on a website's page can be read by anyone who views the source. So the token says only public things: which block of which venue. Never treat it as a login. Do not show a guest's private details, or let anyone change anything, on the strength of a token alone. If the widget needs a signed-in guest, your app signs them in itself.

Letting the page be framed

BookingNinja frames your page in a sandbox that allows scripts, forms, popups and storage for your own page. Your page has to allow itself to be framed by the venue's website:

  • Do not send X-Frame-Options: DENY or SAMEORIGIN.
  • If you send a Content-Security-Policy, its frame-ancestors has to allow *, or the venue's own hosts.

A venue's website cannot be on the same host as your widget.

The height

A frame cannot know how tall its page is. Tell BookingNinja by posting a message to the parent window when your page loads, and again whenever its height changes:

js
function sendHeight() {
  parent.postMessage(
    { type: 'bookingninja:widget-height', height: Math.ceil(document.documentElement.getBoundingClientRect().height) },
    '*'
  );
}
new ResizeObserver(sendHeight).observe(document.body);
sendHeight();

BookingNinja keeps the frame between min_height and 4000 pixels.

Your page is your own, seen directly by the venue's visitors. It needs its own privacy notice, and it may set its own cookies in the frame. BookingNinja does not tell your app who a visitor is.

What your app never sees

No guest data is sent in a content-blocks call. The request names the venue and the settings of the block, and nothing about whoever is looking at the page or the email. An email is built once, so every recipient gets the same content, and your app cannot tailor an email to one person. If you need to know who clicked, do it on your own page, which the guest has chosen to visit.

Test it

The example app has all three: a content block, a widget and an email block, each with a failure switch for an empty list, a reply that breaks the contract and an unknown block type. See the testing guide. Place the blocks on a venue's draft website, then check:

  • the editor preview, with a setting changed;
  • a reply of blocks: [], which should leave the block out;
  • your app switched off, with and without an earlier copy;
  • the widget with an expired token, which your page should refuse.