Shopware 6 集成#
通过 Shopware 6 插件或自定义主题添加 Room Visualizer，并将所选销售渠道的产品编号用作 ideal.house Product Code。
验证状态： Shopware 店铺前台文档已于 2026年9月7日 审核完毕，无客户店铺可供测试。此路径面向标准 Shopware 6 Twig 店铺前台；无头/组合式店铺前台需要其框架专用适配器。
加载 SDK 之前： 打开 Dashboard → Settings，将店铺前台来源添加到 Allowed Origins (CORS)，然后点击 Save。包含已发布的 hostname 以及所使用的任何预览或暂存来源；多个来源间用逗号分隔。参见 配置步骤。
前置条件#
准备开发店铺、插件/主题源代码访问权限、暂存销售渠道、Shop ID、Publishable Key 以及已导入的产品编号。在插件或子主题中进行修改，不要改动 Storefront 核心或供应商主题。
最小 SDK 合同#
<script
src="https://sdk.ideal.house/sdk.js"
data-shop-id="<SHOP_ID>"
data-publishable-key="<PUBLISHABLE_KEY>"
async
></script>
<div data-idealhouse-button-container data-product-code="CHAIR-OAK-01"></div>
将 Shopware productNumber 精确映射为 ideal.house sku。SDK 不会查询 Shopware 的 Store API。
扩展产品模板#
在您的插件中，扩展安装的 Shopware 版本中用于购买组件附近的 Twig 模板/块。使用当前销售渠道产品渲染 host：
{% sw_extends '@Storefront/storefront/component/buy-widget/buy-widget-form.html.twig' %}
{% block buy_widget_buy_container %}
{{ parent() }}
{% if page.product.productNumber %}
<div class="idealhouse-host">
<div
data-idealhouse-button-container
data-product-code="{{ page.product.productNumber|escape }}">
</div>
</div>
{% endif %}
{% endblock %}
块名称和上下文可能因 Shopware 版本和主题而异。检查活跃版本的模板，选择最窄的扩展块，并确认 page.product 在此可用。对于产品卡片，请改用卡片的 product 上下文。
加载 SDK#
Shopware 插件可添加店铺前台 JavaScript 并重写模板。添加一个本地店铺前台条目，以创建一次性的 SDK 脚本：
if (!document.querySelector('script[src="https://sdk.ideal.house/sdk.js"]')) {
const script = document.createElement('script');
script.src = 'https://sdk.ideal.house/sdk.js';
script.async = true;
script.dataset.shopId = '<SHOP_ID>';
script.dataset.publishableKey = '<PUBLISHABLE_KEY>';
document.head.append(script);
}
使用适用于您 Shopware 版本的流程编译店铺前台资源并激活插件/主题。在可复用插件中使用配置值存储凭据；仅渲染浏览器安全的 Publishable Key。
变体与动态内容#
Shopware 通常将可购买的变体表示为带有各自 productNumber 和规范 URL 的不同产品。在完整导航时，服务器渲染的 Twig 会自然输出新代码。如果您的主题在不重新加载页面的情况下切换变体，请将其文档化的完成回调连接到：
function replaceIdealhouseProduct(host, productNumber) {
host.replaceChildren();
const code = String(productNumber || '').trim();
if (!code) return;
const container = document.createElement('div');
container.dataset.idealhouseButtonContainer = '';
container.dataset.productCode = code;
host.append(container);
}
此桥接由客户负责，因为主题和第三方变体插件各不相同。通过过滤器/离屏组件加载的列表在新 DOM 到达后必须渲染或重建干净的容器。请勿克隆 SDK 生成的子节点。
产品导入#
将每个 Shopware 产品/变体 productNumber 导出为 ideal.house sku。通过 商品上传 导入，然后使用 导入商品、任务状态、列出商品、更新商品、删除商品 以及 错误与重试。
任何 Store API/Admin API 同步、定时任务或 Flow Builder/webhook 集成本质上是独立的客户代码。
验证与移除#
测试父产品、每个可可视化变体、缺失和未知的产品编号、列表、过滤器、离屏/快速查看、浏览器后退/前进、移动端布局、缓存/代理行为，以及所有相关的销售渠道/域名。确认一次 SDK 请求以及 productNumber/SKU 精确匹配。
要移除，请停用/卸载插件或移除子主题的 Twig 和 JavaScript，重新构建店铺前台资源，清除缓存，并确认没有 SDK 请求或容器残留。