PushizoDocs
Channels

HTML in-app messages, template gallery and carousel

Decision record: ADR-0027. In the in-app message editor, choose the HTML content type, or use Start from template to copy a layout from the gallery (24 ready-made templates, tr/en).

Decision record: ADR-0027. In the in-app message editor, choose the HTML content type, or use Start from template to copy a layout from the gallery (24 ready-made templates, tr/en).

Security model

HTML is not sanitized; it is isolated:

  • Web: <iframe sandbox="allow-scripts"> (no allow-same-origin). The content runs in an opaque origin; it cannot access the app's DOM, cookies or localStorage, cannot change window.top.location, open popups or submit forms.
  • A CSP is prepended to the document: default-src 'none'; img-src https: data:; style-src 'unsafe-inline'; script-src 'unsafe-inline'. fetch, XHR, WebSocket and external scripts/styles/fonts cannot be loaded; only https and data: images.
  • If the content tries to navigate to another page on its own (link, location, meta refresh), the message is closed. Link clicks are automatically converted to the bridge (click('link', href)).
  • Android WebView and iOS WKWebView load the same document; file/content access is disabled, navigation and network requests are blocked, and the only JavaScript interface is the bridge. In Flutter, HTML messages are rendered by the native SDK.
  • Liquid variables ({{ user.tags.name }}) are inserted HTML-escaped on the server.

If your site's CSP does not allow inline scripts (no 'unsafe-inline' or equivalent in script-src), the bridge script will not run, because the srcdoc document inherits this policy; on pages where HTML in-app will be used, adjust the CSP accordingly.

PushizoBridge API

Inside the content, window.PushizoBridge is ready to use (and cannot be overwritten):

CallEffect
PushizoBridge.close()Closes the message (user dismissal: dismiss event).
PushizoBridge.click(actionId, url?)Click event (button_id = actionId, 1–64 characters [A-Za-z0-9_.:-]); click listeners are called and the message closes. If url is http(s), it opens in a new tab/browser; if it is an app scheme (myapp://…), it opens as a deeplink; javascript:, data:, file: are ignored.
PushizoBridge.addTag(key, value)Adds a tag to the user (User.addTags); the message stays open. Key without spaces ≤ 128, value ≤ 255 characters.
PushizoBridge.trackEvent(name, props)Sends an event (Session.sendEvent); props up to 20 flat values (text ≤ 255, number, boolean, null).

Declarative shortcuts:

  • Clicking an element with data-hs-close → close().
  • Clicking an element with data-hs-action="id" → click("id", href or data-hs-url).
  • Clicking an <a href> → click("link", href).

Example:

<style>body{font-family:system-ui;text-align:center;padding:24px}@media (prefers-color-scheme:dark){body{background:#18181b;color:#fafafa}}</style>
<h1>Would you rate us?</h1>
<button onclick="PushizoBridge.trackEvent('rating',{stars:5});PushizoBridge.click('rate_store','https://pushizo.com/store')">5 stars</button>
<button data-hs-close>Later</button>

Message protocol (for SDK developers): { hs: "pushizo-bridge", v: 1, nonce, type, … }, types ready, close, click (action_id, url?), add_tag (key, value), track_event (name, props), resize (height). To be accepted, the source frame, a per-impression nonce and the schema are verified; shared test vectors are in sdk/testdata/html-bridge-vectors.json.

Height and layout

For modals and banners, html_height (40–2000 px) is the initial height; once the content loads, the bridge reports the actual height (capped at 90% of the screen). In fullscreen, the content fills the entire area. For dark theme, use @media (prefers-color-scheme: dark).

In block content, the Carousel block holds 1–10 cards: image (https, alt text), title, text and an optional button (in-app button actions). Cards scroll horizontally; screen readers announce a "Card 1/3" label, and you can navigate with the arrow buttons and the keyboard (←/→). A card button click is a normal button click; all button IDs must be unique within the message.

SDK compatibility

SDKs declare their capabilities with supports=html,carousel (current versions of Web, Android, iOS, Flutter). HTML messages are not sent to older SDKs, and carousel blocks are removed; the rest of the message is shown.

Template gallery

  • System templates are versioned in code (IN_APP_GALLERY_VERSION); categories: welcome, promotion, cart, survey, rating, onboarding, update, permission, newsletter, announcement, loyalty.
  • Save as template turns the current layout into an organization template; it appears in all apps of the same organization.
  • API: GET /internal/v1/apps/{appId}/in-app-templates?language=tr&source=system|org&category=…, POST (name, description, category, layout), PATCH/DELETE …/{templateId} (organization templates only).

On this page