第 1 步：获取您的 Photta 组件密钥
登录位于 business.photta.app 的 Photta Business 管理后台。前往“设置” → “API 密钥”，并复制以 pk_live_ 开头的可公开密钥。这是您唯一需要的凭据。在密钥生效之前，请在“设置” → “允许的域名”中添加您的 WooCommerce 商店域名（例如 mystore.com）。系统会在每次试穿请求时进行域名检查，因此在正式上线前必须设置好白名单。
如果您在 localhost 或分级环境 URL 等子域名上进行本地测试，请分别将该域名添加到允许列表中。在任何付费方案中，您最多可以添加 10 个域名。试用帐户允许一个域名。一旦您的域名列出，来自该来源的请求将立即被接受 — 没有生效延迟。
第 2 步：选择短代码或脚本标签
WooCommerce 为您提供两种清晰的集成路径。短代码方法（[photta_widget pk="pk_live_..."]）允许您将组件粘贴到产品页面模板或自定义 WooCommerce 钩子中的特定位置 — 如果您希望按钮精确出现在产品展示图和“加入购物车”按钮之间，这是理想选择。要使用短代码，请将其直接粘贴到 WooCommerce 产品模板文件 single-product/add-to-cart/simple.php 中，或使用页面构建器区块。
脚本标签方法通过主题的 functions.php 文件使用 wp_enqueue_script 全局插入 SDK。将以下内容添加到子主题的 functions.php 中：add_action('wp_footer', function() { echo '<script src="https://widget.photta.app/sdk.js" data-pk="pk_live_..." defer></script>'; }); 这将自动在每个产品页面上渲染组件按钮，无需更改任何模板。大多数商家因其简单性而更倾向于脚本标签方法。
第 3 步：粘贴并保存您选择的代码片段
对于短代码路径：打开子主题中用于单个产品页面的 WooCommerce 模板覆盖文件。在您希望按钮出现的精确垂直位置粘贴 [photta_widget pk="pk_live_..."]。保存文件。短代码渲染器由 Photta 的轻量级助手注册 — 不需要插件文件，因为 SDK 本身在加载时会注册短代码处理器。
对于脚本标签路径：在 WordPress 后台中打开“外观” → “主题文件编辑器”，导航到子主题的 functions.php，并添加第 2 步中显示的 wp_footer 操作片段。点击“更新文件”保存。通过刷新编辑器并确认代码存在来验证片段是否已保存。如果您使用缓存插件（如 WP Rocket、W3 Total Cache），请立即清除缓存，以便提供新的页脚脚本。
第 4 步：验证组件是否出现在您的商店中
在无痕浏览器窗口中导航到您 WooCommerce 商店的产品页面。您应该会在“加入购物车”区域附近看到一个“试穿”按钮。点击按钮，上传测试照片，并验证试穿结果是否渲染。如果按钮没有出现，请打开浏览器控制台 (F12) 查看是否有 photta 错误。403 域名错误意味着您的域名尚未加入“允许的域名”列表。
同时，通过按 Ctrl+U（查看源代码）并搜索 photta，检查 SDK 脚本标签是否出现在页面 HTML 源代码中。如果标签不存在但您添加了 wp_footer 钩子，请仔细检查您的主题是否在页脚模板中调用了 wp_footer() — 一些较旧或高度定制的主题会省略此调用。在 footer.php 的 </body> 闭合标签前添加 <?php wp_footer(); ?> 即可修复此问题。
第 5 步：配置按类别显示的可见性
默认情况下，组件按钮出现在所有产品页面上。要将其限制在特定类别，请在脚本标签中添加 data-categories 属性，并附上 WooCommerce 类别别名的逗号分隔列表：<script src="https://widget.photta.app/sdk.js" data-pk="pk_live_..." data-categories="womens-apparel,mens-apparel,swimwear" defer></script>。SDK 会读取当前页面的 WooCommerce 类别数据，并自动在不匹配的页面上隐藏按钮。
对于短代码用户，只需将短代码放置在与目标类别相关的模板中，或将短代码包装在 WooCommerce 条件语句中：使用 has_term() PHP 函数在输出短代码之前检查当前产品是否属于目标类别。这种模式让您能够精确控制哪些产品类型显示试穿选项，而无需复制模板。