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">(noallow-same-origin). The content runs in an opaque origin; it cannot access the app's DOM, cookies orlocalStorage, cannot changewindow.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 anddata: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):
| Call | Effect |
|---|---|
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).
Carousel block
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).
In-app messages
In-app messages — block-based modal/banner/fullscreen layouts, triggers, audience, frequency, actions, A/B variants, SDK contract and public API.
Embedded placements
Instead of a popup, place content in an area you reserve in your app, such as a home page banner or a recommendation slot below the cart. You change the content from the dashboard; no app update is needed. Decision record:…