Blocks API

Blocks API exposes pre-built HTML blocks that can be quickly integrated into your shop’s user interface. A website embeds a block in an IFRAME, while a native app displays it in a Web View.

Replace SHOP_SLUG in the examples with the Bubblehouse shop slug supplied for your integration. The URL parameters below explain CUSTOMER_TOKEN and MARKET.

Web

Include bubblehouse.js once on the page, then display the block in an IFRAME:

<script
  src="https://app.bubblehouse.com/s/SHOP_SLUG/bubblehouse.js"
  async
></script>

<iframe
  id="bubblehouse-rewards"
  title="Bubblehouse rewards page"
  src="https://app.bubblehouse.com/s/SHOP_SLUG/blocks/Rewards7?instance=bubblehouse-rewards&amp;auth=CUSTOMER_TOKEN&amp;market=MARKET"
  loading="lazy"
  height="1500"
  sandbox="allow-top-navigation allow-scripts allow-forms allow-modals allow-popups allow-popups-to-escape-sandbox allow-same-origin"
  allow="clipboard-write"
  style="border: 0; width: 100%;"
></iframe>

URL:

https://app.bubblehouse.com/s/SHOP_SLUG/blocks/Rewards7
  ?instance=bubblehouse-rewards
  &auth=CUSTOMER_TOKEN
  &market=MARKET

Whitespace and newlines in URL examples are illustrative.

Native app

Display this URL in a Web View:

https://app.bubblehouse.com/s/SHOP_SLUG/blocks/Rewards7
  ?instance=bubblehouse-rewards
  &auth=CUSTOMER_TOKEN
  &market=MARKET
  &env=mobile
  &standalone=1

URL parameters

• instance: Give every displayed block a unique value. On the web, use the same value for the IFRAME’s id.
• auth: Pass a customer token. Omit it or leave it empty for an anonymous customer.
• market: Set it to the market identity supplied by Bubblehouse. Omit it to use the storefront’s default market.
• env: Use web for websites; this is the default. Use mobile when the block runs in a native app.
• standalone: 0 is the default. Use 1 to display a scrollable page without an outer frame.
• height (IFRAME style attribute, not a URL parameter): Set the initial IFRAME height in pixels. Choose a value close to the expected content height; bubblehouse.js updates it after the block renders.

Use case	env	standalone
IFRAME embedded on the web	web	0
URL loaded in a native mobile Web View	mobile	1
IFRAME embedded inside a native mobile Web View	mobile	0

Login and signup handling

Give Bubblehouse the URLs for your login page, signup page, and primary loyalty page. Bubblehouse configures these destinations so blocks can send signed-out customers to authentication and return them to the loyalty experience.

For native app Web Views, we normally hide the login and signup controls. If you keep them visible but want to use native navigation, intercept navigations to the configured login and signup URLs, cancel the Web View navigation, and display the corresponding native UI instead. Likewise, intercept the configured primary loyalty page URL when the app should return to its native loyalty UI.