shopify-built-for-shopify

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 ウェブコンポーネントを使用して、管理画面のスタイルに合わせてください。

<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% 増加」など）	虚偽の主張となるため
レビュー投稿へのインセンティブ（「Pro にするなら 5 つ星を」など）	操作的なため
閉じられないプロモーション	マーチャントを圧倒するため
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 のセグメントを使用する
• 訪問者 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 ピクセル