> For the complete documentation index, see [llms.txt](https://docs.taptap3d.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.taptap3d.com/proposed-reference/host-integration.md).

# Iframe lifecycle

Proposed iframe connection syntax, validated resize events, lifecycle messages and storefront fallback behaviour.

Status: proposed protocol. The product does not serve these routes or messages yet. [Embed a listing](/integration-guides/iframe-guide.md) contains the complete host example; the [local quickstart](/get-started/local-quickstart.md) runs it against synthetic data.

## Embed URL

```
{EMBED_ORIGIN}/embed/{publicationId}?locale=en&theme=light
{EMBED_ORIGIN}/embed/{publicationId}?revision={revision}&locale=zh-Hant&theme=light
```

Use an origin supplied during onboarding. Browser code must not contain private API credentials. The proposed read-only embed requests no camera, microphone, payment, popup or top-level navigation permissions.

## Host messages

The proposed frame sends messages to the registered parent origin, not `*`. These payloads are objects, not JSON strings.

```js
// Frame has rendered the approved revision.
({ type: 'taptap3d:ready', version: 1,
   publicationId: 'pub_demo_vessel', revision: 'rev_demo_001' });

// Height is measured in CSS pixels.
({ type: 'taptap3d:resize', version: 1,
   publicationId: 'pub_demo_vessel', height: 680 });

// Remove the displayed content.
({ type: 'taptap3d:unavailable', version: 1,
   publicationId: 'pub_demo_vessel', code: 'publication_withdrawn' });
```

Check `event.origin`, `event.source`, `version`, `publicationId`, type and each type's payload. Apply a resize only for an integer height from 240 through 1600. Ignore malformed or unknown messages. Checking only an ID or type does not identify the sender.

No host-to-frame command API is proposed for the first release. Do not make the frame change records or execute arbitrary navigation through messages.

## Loading and failure

Reserve 720 pixels of height before load. Keep a descriptive iframe title and a visible canonical link outside the frame. After 10 seconds without a valid ready message, show a status message while keeping the link; a late ready message can clear the status.

On an unavailable message, hide the frame and show the unavailable state. A network outage cannot establish withdrawal status. Do not leave transaction controls enabled based on stale embed data.

If the storefront uses Content Security Policy, add the approved origin to its `frame-src` directive. Browser JSON rendering also needs the API origin in `connect-src` and permitted CORS. Do not replace the storefront's whole policy or use wildcards to bypass a blocked request.

The intended sandbox for the read-only iframe is `allow-scripts allow-same-origin`, with the embed hosted on a separate origin from the storefront. Do not combine those permissions for a same-origin frame. The local mock deliberately omits sandboxing because both pages share a loopback origin; production permissions still require verification against the real embed.

## Ecommerce placement

Place an embed in a product content area, not checkout. The storefront owns SKU mapping, offers, stock, cart and payment. Map a storefront product to a public `publicationId` explicitly; it is not automatically the SKU.

A theme template or custom HTML block can host an iframe if the platform permits it. Server-rendered storefronts can use the JSON route. Specific Shopify, WooCommerce, Shopline and other adapters are not released. Validate the partner platform's iframe, script and CSP restrictions before committing to an integration.

## Accessibility and search

The intended embed supports keyboard navigation, meaningful image alternatives, English and Traditional Chinese, and narrow screens. Test Safari, Firefox and Chromium. Height changes must not move a focused purchase control unexpectedly.

Publish approved title and description in the host page's own HTML for search visibility. See [Search visibility](/integration-guides/search-visibility.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.taptap3d.com/proposed-reference/host-integration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.