Skip to Content
API ReferenceBrowser events

Browser events

The iframe can send postMessage events to your page. Handling them is optional; the basic iframe works without a message listener.

Always check both the Play origin and the iframe window. Browser messages are for the interface. Your wallet changes only through authenticated webhooks.

Resize the frame

Add this listener before assigning the launch URL to the iframe:

const frame = document.getElementById("maktub-game");
const playOrigin = new URL(launchUrl).origin;
 
window.addEventListener("message", (event) => {
  if (event.origin !== playOrigin || event.source !== frame.contentWindow) return;
  const data = event.data;
  if (data?.type === "maktub:resize" && Number.isFinite(data.height) && data.height > 0) {
    frame.style.height = Math.ceil(data.height) + "px";
  }
});

Below 1024px, controls keep their natural size. A fixed-height iframe scrolls inside the game; applying the requested height lets your page own the scroll. With showBalance=true, the compact balance header stays visible during scrolling inside the iframe. If your page scrolls the entire expanded iframe, that outer scrolling remains controlled by your page.

The game requests a natural height on viewports below 1024px. Wider layouts fit the iframe’s assigned height without sending this message, so keep an initial height such as 730px. resize is a compatibility alias; listen to just one name.

Other messages from the game

typeExtra fieldsMeaning
paintedNoneThe game UI has mounted; session loading may still be in progress.
readyNoneSession configuration has loaded. Demo frames also send this event.
balance_updatebalanceUpdate an optional host balance display. Values are in the session’s currency; demo balances are not sent.
auth_requiredNoneThe game asks your page to authenticate the player.
maktub:upgradedNoneA token handoff message was received; see below.

On auth_required, send the player through your login/session flow and load the new launch URL. A ready event or displayed balance is not proof of a wallet transaction; use your ledger for that.

Supply a token after the iframe loads

Use this only if you intentionally loaded the frame without a token. The normal launch flow does not need it. Wait for painted before sending the token, so the receiver has mounted.

frame.contentWindow.postMessage(
  { type: "maktub:upgrade", token: session.token },
  playOrigin,
);

Use the Maktub response token, not your optional operator session reference. The iframe acknowledges receipt with maktub:upgraded before validating the session. That acknowledgement alone does not prove the credential is valid.

The first token is kept. Later posts are acknowledged but do not replace it; reload the iframe to change sessions. Demo frames ignore upgrades. maktub:session is an alias, and a search field such as ?token=... is also accepted.

Theme and language changes use a new session and launch URL, not a browser event.

AppearanceFree bets