Ideal House
跳转到主要内容

PrestaShop 集成#

使用小型 PrestaShop 模块加载 Room Visualizer 并基于当前产品或组合 reference 渲染按钮。

验证状态： PrestaShop 8/9 模块、钩子和资源文档已于 2026年9月7日 审核完毕，无商家店铺可供测试。示例使用了 Classic 和 Hummingbird 共有的文档化钩子，但第三方主题可能会移动或删除它们。

加载 SDK 之前： 打开 Dashboard → Settings，将店铺前台来源添加到 Allowed Origins (CORS)，然后点击 Save。包含已发布的 hostname 以及所使用的任何预览或暂存来源；多个来源间用逗号分隔。参见 配置步骤。

前置条件与映射#

准备暂存店铺、模块开发访问权限、Shop ID、Publishable Key 以及已导入的 SKU。确定 ideal.house code 来自基础产品 reference 还是所选组合 reference。每个可可视化的组合都必须具有唯一且非空的 reference。

最小 SDK 合同#

html
<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>

Product Code 必须与导入的 ideal.house sku 完全匹配。PrestaShop ID 与 reference 不可互换。

创建模块插入点#

注册 displayProductAdditionalInfo 以在产品页面上放置内容，并注册 actionFrontControllerSetMedia 以加载本地适配器。Classic 和 Hummingbird 均在产品和快速查看模板中记录了 display 钩子。

php
public function install()
{
    return parent::install()
        && $this->registerHook('displayProductAdditionalInfo')
        && $this->registerHook('actionFrontControllerSetMedia');
}

public function hookActionFrontControllerSetMedia($params)
{
    $this->context->controller->registerJavascript(
        'module-' . $this->name . '-adapter',
        'modules/' . $this->name . '/views/js/adapter.js',
        array('position' => 'bottom', 'priority' => 200)
    );
}

在 display 钩子回调中，获取展示的产品，选择其 reference，分配给 Smarty，并渲染模块模板。在该模板中转义该值：

smarty
<div class="idealhouse-host">
  {if $idealhouse_product_code}
    <div
      data-idealhouse-button-container
      data-product-code="{$idealhouse_product_code|escape:'html':'UTF-8'}">
    </div>
  {/if}
</div>

不要直接复制简写的 PHP 作为完整的生产模块：需要添加正常的模块元数据、版本兼容性、配置存储、权限检查和卸载清理。

加载 SDK 一次#

在 adapter.js 中，从模块已清理的店铺前台配置读取两个公开值后，创建精确的 SDK 元素：

js
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 = window.idealhousePublicConfig.shopId;
  script.dataset.publishableKey = window.idealhousePublicConfig.publishableKey;
  document.head.append(script);
}

通过 PrestaShop 支持的 JavaScript 定义/配置机制暴露 idealhousePublicConfig。永远不要暴露 Client Secret。

组合变更与动态页面#

主题的产品刷新生命周期和第三方组合模块各不相同。在活跃主题已解析所选组合时，将其 reference 传入此客户桥接：

js
function renderIdealhouseCombination(host, reference) {
  host.replaceChildren();
  const code = String(reference || '').trim();
  if (!code) return;
  const container = document.createElement('div');
  container.dataset.idealhouseButtonContainer = '';
  container.dataset.productCode = code;
  host.append(container);
}

不要根据显示标签猜测。快速查看包含在文档化的钩子位置中，但需验证活跃主题确实渲染了该钩子。对于 AJAX 过滤器或重新刷新的产品片段，让钩子创建新 host，或在主题文档化的更新回调之后调用桥接。

导入产品数据#

将 PrestaShop 产品/组合 reference 映射为 ideal.house sku。使用 商品上传 以及 导入、任务状态、列出商品、更新商品、删除商品 和 错误与重试 指南。任何 PrestaShop Webservice 导出、cron 或基于钩子的同步均为客户实现。

验证与移除#

测试简单产品、每个组合、缺失/重复的 reference、未知 ideal.house SKU、快速查看、列表、分层导航、浏览器历史、移动端、语言/货币销售上下文、同意设置以及生产缓存。确认一次 SDK 请求以及 reference/SKU 精确相等。

卸载或禁用模块，确保其钩子/配置/资源已被移除，清除 Smarty 和店铺前台缓存，并确认 SDK URL 及 data-idealhouse-* 标记均不存在。

官方平台参考#