shopify-built-for-shopify

Built for Shopify 指南

此技能会在开发过程中强制执行 Shopify 的 Built for Shopify（BFS）质量标准，确保应用达到 Shopify App Store 的最高质量标准。

参考：https://shopify.dev/docs/apps/launch/built-for-shopify/requirements

快速合规检查清单

在审核代码或构建功能时使用此清单：

BFS Compliance Review:
- [ ] App is embedded in Shopify admin (App Bridge)
- [ ] Uses session token authentication
- [ ] Primary workflows stay within Shopify admin
- [ ] No additional login/signup required
- [ ] Uses theme app extensions (not Asset API for writes)
- [ ] Meets Web Vitals targets (LCP ≤2.5s, CLS ≤0.1, INP ≤200ms)
- [ ] Uses Polaris components matching admin styling
- [ ] Mobile responsive design
- [ ] Uses nav menu (s-app-nav) and contextual save bar
- [ ] Error messages are red, contextual, and helpful
- [ ] No dark patterns or pressure tactics
- [ ] Premium features are disabled and labeled
- [ ] Promotional content is dismissible

1. 集成要求

嵌入（强制要求）

应用必须嵌入 Shopify 后台：

<script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>

// Use session token authentication
import { authenticate } from "@shopify/shopify-app-remix/server";

export async function loader({ request }) {
  const { session } = await authenticate.admin(request);
  // ...
}

主要工作流

所有主要应用工作流都必须能够在 Shopify 后台中完成：

• 核心功能无需访问外部网站
• 第三方连接设置必须能在应用内访问
• 在应用主页提供简化的监控／报告功能

干净安装

对于店面应用，请使用主题应用扩展，而不是 Asset API：

{% schema %}
{
  "name": "My App Block",
  "target": "section",
  "settings": []
}
{% endschema %}

请勿使用 Asset API 创建、修改或删除主题文件（允许读取）。

2. 性能要求

Web Vitals 目标（第 75 百分位）

指标	目标	描述
LCP	≤ 2.5s	最大内容绘制
CLS	≤ 0.1	累积布局偏移
INP	≤ 200ms	下次绘制交互

优化策略

// Lazy load heavy components
const HeavyChart = lazy(() => import('./HeavyChart'));

// Use React.memo for expensive renders
const ExpensiveList = memo(({ items }) => (
  // ...
));

// Avoid layout shifts with skeleton loaders
<Suspense fallback={<SkeletonPage />}>
  <AppContent />
</Suspense>

店面性能

• Lighthouse 评分降幅不得超过 10 分
• 结账请求：p95 ≤ 500ms，失败率 ≤ 0.1%

3. 设计要求

熟悉（与 Shopify 后台一致）

使用 Polaris Web 组件，匹配后台样式：

<s-page>
  <s-title-bar title="My Page">
    <s-button slot="primary-action">Save</s-button>
  </s-title-bar>
  
  <s-layout>
    <s-layout-section>
      <s-card>
        <s-text>Content in cards</s-text>
      </s-card>
    </s-layout-section>
  </s-layout>
</s-page>

应避免导致审核不通过的原因：

• 自定义按钮颜色（使用 Polaris 默认样式）
• 衬线字体／手写体
• 非标准背景颜色
• 内容未放在卡片容器中
• 对比度不佳（必须符合 WCAG 2.1 AA）

导航

使用 App Bridge 导航菜单：

<s-app-nav>
  <s-nav-item href="/dashboard" selected>Dashboard</s-nav-item>
  <s-nav-item href="/settings">Settings</s-nav-item>
</s-app-nav>

请勿：

• 创建自定义导航菜单
• 在导航项中使用表情符号
• 设置单独的“主页”链接（应用名称应链接至主页）

上下文保存栏

所有表单输入都应使用：

import { useAppBridge } from "@shopify/app-bridge-react";
import { SaveBar } from "@shopify/app-bridge/actions";

function SettingsForm() {
  const app = useAppBridge();
  
  const showSaveBar = () => {
    const saveBar = SaveBar.create(app, {
      saveAction: { disabled: false, loading: false },
      discardAction: { disabled: false, loading: false },
    });
    saveBar.dispatch(SaveBar.Action.SHOW);
  };
  // ...
}

模态框

使用带有正确插槽的 s-modal：

<s-modal heading="Confirm Action">
  <p>Modal content here</p>
  <s-button slot="secondary-action">Cancel</s-button>
  <s-button slot="primary-action" variant="primary">Confirm</s-button>
</s-modal>

移动设备适配

• 移动设备上不得出现水平滚动
• 内容必须适当换行／堆叠
• 所有内容都必须可访问（不得隐藏内容，除非提供展开机制）

4. 实用的 UX 要求

入门引导

• 简洁明了，引导商家完成流程
• 完成后可关闭
• 不得要求安装其他应用
• 说明索取任何商家信息的理由

主页

必须包含：

• 主题区块／嵌入状态（如适用）
• 相关指标／分析数据
• 动态内容（不能只有静态链接）

错误消息

<s-text-field 
  label="Email"
  error="Please enter a valid email address"
/>

5. 用户友好要求（禁止暗黑模式）

禁止的做法

请勿	原因
使用升级倒计时器	给商家施加压力
“不用了，我更愿意少卖一些”	带有内疚／羞辱意味的措辞
自动弹出的模态框／弹出层	干扰商家
保证效果（“销量提升 18%”）	虚假宣传
以评价作为奖励（“给 5 星即可使用 Pro”）	具有操纵性
不可关闭的促销内容	令商家不堪其扰
使用类似 Shopify 的图标／颜色	冒充 Shopify

高级功能

<s-card>
  <s-text variant="headingMd">Advanced Analytics</s-text>
  <s-badge tone="info">Pro Plan</s-badge>
  <s-button disabled>View Analytics</s-button>
  <s-link url="/upgrade">Upgrade to unlock</s-link>
</s-card>

• Shopify Plus 专属功能必须对非 Plus 商家隐藏（不能只是禁用）

6. 特定类别要求

如果构建的是：广告／分析／联盟营销应用

// MUST use Web Pixel extensions, NOT script tags
// extensions/web-pixel/src/index.ts
import { register } from "@shopify/web-pixels-extension";

register(({ analytics }) => {
  analytics.subscribe("page_viewed", (event) => {
    // Track event
  });
});

如果构建的是：电子邮件／SMS 营销应用

• 与 Shopify 同步客户数据
• 通过客户细分操作扩展使用 Shopify 细分
• 使用 visitors API 识别店铺访客

如果构建的是：折扣应用

# Use discount functions or native APIs
# Do NOT use draft orders for custom discounts
# Use discountRedeemCodeBulkAdd for multiple codes

mutation {
  discountRedeemCodeBulkAdd(
    discountId: "gid://shopify/DiscountCodeNode/123"
    codes: [{ code: "CODE1" }, { code: "CODE2" }]
  ) {
    bulkCreation {
      id
    }
  }
}

如果构建的是：订阅应用

• 使用 Selling Plan API、Subscription Contract API、Customer Payment Method API
• 在产品页面使用主题应用区块
• 清晰显示订阅信息（名称、价格、节省金额）
• 使用 Customer Account UI 扩展管理订阅

如果构建：履约应用

• 等待商家发出履约请求后再履约
• 在 4 小时内响应履约请求
• 在 1 小时内响应取消请求
• 在履约创建后 1 小时内添加跟踪信息
• 完成率达到 99％，回调成功率达到 99.9％

如果构建：退货应用

同步所有退货生命周期事件：

• returnCreate, reverseDeliveryCreateWithShipping
• reverseFulfillmentOrderDispose, returnLineItemRemoveFromReturn
• returnCancel, returnClose, refundCreate

代码审查清单

审查 Shopify 应用代码是否符合 BFS 要求时：

Technical:
- [ ] App Bridge script in <head>
- [ ] Session token auth (no cookie auth)
- [ ] Theme app extensions (no Asset API writes)
- [ ] Web Pixel extensions (no script tags for tracking)
- [ ] Proper API usage for app category

UI/UX:
- [ ] Polaris components throughout
- [ ] s-app-nav for navigation
- [ ] Contextual save bar for forms
- [ ] s-modal with proper slots
- [ ] Responsive design
- [ ] WCAG 2.1 AA contrast

Content:
- [ ] No outcome guarantees
- [ ] No pressure tactics
- [ ] Dismissible promotional content
- [ ] Disabled + labeled premium features
- [ ] Clear error messages (red, contextual)
- [ ] Helpful onboarding
- [ ] Dynamic homepage content

资源

• BFS 要求
• App Bridge
• Polaris Web Components
• 主题应用扩展
• Web Pixels