Sidekick Extensions

Shopify SidekickはShopify管理画面に直接組み込まれたAIアシスタントです。自然言語を通じてマーチャントのストア管理を支援します -- 売上についての質問への回答、商品説明の作成、ディスカウントコードの生成など。Sidekick Extensionsを使用すると、開発者はSidekickにアプリの機能を教えることができ、マーチャントが会話インターフェースを離れることなくサードパーティアプリの機能とやり取りできるようになります。

開発者プレビュー

Sidekick Extensionsは現在開発者プレビュー段階にあります。APIの表面は進化していますが、このレッスンで説明されるコアパターンは安定しています。Shopifyパートナープログラムを通じて、今日からエクステンションの構築とテストを開始できます。

Sidekick Extensionsが重要な理由

Sidekick Extensions以前は、アプリの機能はサイロ化されていました。ロイヤリティプログラムアプリを使用するマーチャントは、そのアプリのUIに移動し、インターフェースを学習し、手動でアクションをトリガーする必要がありました。Sidekick Extensionsを使えば、同じマーチャントが以下のように言えます:

「今月のロイヤリティプログラム会員トップ10を表示して」

...するとSidekickがリクエストをアプリにルーティングし、データを取得し、会話形式で提示します。これは単なるギミックではありません -- マーチャントがアプリ機能を発見し使用する方法を根本的に変えます。

マーチャント体験

Sidekick Extensionの構築

Sidekick Extensionは3つの主要コンポーネントで構成されます:

1. エクステンションマニフェスト -- エクステンションが何をできるかを宣言
2. アクションハンドラー -- Sidekickがエクステンションを呼び出したときに実行される関数
3. レスポンスフォーマッター -- Sidekickがマーチャントに提示するためのデータ構造化

エクステンションマニフェスト

マニフェストはアプリが公開する機能をSidekickに伝えます。アクション、パラメータ、戻り値の型を記述する宣言的スキーマを使用します。

# shopify.extension.toml
[extension]
type = "sidekick_extension"
name = "Loyalty Program Assistant"
handle = "loyalty-sidekick"

[[extension.capabilities]]
name = "get_member_stats"
description = "Retrieve loyalty program statistics including total members, points issued, and redemption rates"
parameters = []

[[extension.capabilities]]
name = "lookup_member"
description = "Look up a specific loyalty program member by name or email"

[[extension.capabilities.parameters]]
name = "query"
type = "string"
description = "Customer name or email to search for"
required = true

[[extension.capabilities]]
name = "issue_bonus_points"
description = "Issue bonus loyalty points to a customer segment"

[[extension.capabilities.parameters]]
name = "segment"
type = "string"
description = "Customer segment identifier"
required = true

[[extension.capabilities.parameters]]
name = "points"
type = "number"
description = "Number of bonus points to issue"
required = true

良い機能説明の書き方

Sidekickは機能の説明を使用して、マーチャントのリクエストをエクステンションにルーティングするかどうかを決定します。具体的でアクション指向の説明を書いてください。「ロイヤリティデータを管理」ではなく、「合計会員数、発行ポイント、引き換え率を含むロイヤリティプログラムの統計情報を取得」と書いてください。説明が正確であるほど、Sidekickはマーチャントの意図をより正確にマッチングします。

アクションハンドラー

アクションハンドラーは、Sidekickがマッチする機能を特定した際に呼び出すサーバーサイド関数です。構造化されたパラメータを受け取り、Sidekickがマーチャントにフォーマットするデータを返します。

// extensions/sidekick/src/handlers.ts
import { SidekickActionHandler } from '@shopify/sidekick-extensions';

export const getMemberStats: SidekickActionHandler = async (context) => {
  const { session, admin } = context;

  // アプリのデータベースからロイヤリティ統計を照会
  const stats = await db.loyaltyStats.aggregate({
    shopId: session.shop,
    period: 'current_month',
  });

  return {
    type: 'data_summary',
    data: {
      totalMembers: stats.totalMembers,
      activeMembers: stats.activeThisMonth,
      pointsIssued: stats.pointsIssuedThisMonth,
      pointsRedeemed: stats.pointsRedeemedThisMonth,
      redemptionRate: (stats.pointsRedeemedThisMonth / stats.pointsIssuedThisMonth * 100).toFixed(1),
      topReward: stats.mostPopularReward,
    },
    summary: `ロイヤリティプログラムには${stats.totalMembers.toLocaleString()}人の会員がいます。今月は${stats.activeThisMonth.toLocaleString()}人がアクティブで、引き換え率は${(stats.pointsRedeemedThisMonth / stats.pointsIssuedThisMonth * 100).toFixed(1)}%です。`,
  };
};

export const lookupMember: SidekickActionHandler = async (context) => {
  const { session, params } = context;
  const { query } = params;

  const members = await db.loyaltyMembers.search({
    shopId: session.shop,
    query,
    limit: 5,
  });

  if (members.length === 0) {
    return {
      type: 'not_found',
      summary: `「${query}」に一致するロイヤリティ会員は見つかりませんでした。`,
    };
  }

  return {
    type: 'member_list',
    data: members.map((m) => ({
      name: m.name,
      email: m.email,
      tier: m.tier,
      pointsBalance: m.pointsBalance,
      lifetimeSpend: m.lifetimeSpend,
      memberSince: m.createdAt,
    })),
    summary: `「${query}」に一致する${members.length}人の会員が見つかりました。`,
  };
};

export const issueBonusPoints: SidekickActionHandler = async (context) => {
  const { session, params } = context;
  const { segment, points } = params;

  // 実行前にアクションを検証
  const segmentSize = await db.segments.count({
    shopId: session.shop,
    segmentId: segment,
  });

  return {
    type: 'confirmation_required',
    action: 'issue_bonus_points',
    summary: `「${segment}」セグメントの${segmentSize}人の顧客に${points}ボーナスポイントを発行します。合計ポイントコスト: ${points * segmentSize}。確認しますか？`,
    params: { segment, points, affectedCustomers: segmentSize },
  };
};

破壊的アクションには確認が必要

データを変更するSidekick Extensionアクション（ポイントの発行、レコードの削除、設定の更新）は、まずconfirmation_requiredレスポンスタイプを返す必要があります。Sidekickは実行前にマーチャントに確認を提示します。Sidekickハンドラーから破壊的操作を自動実行することは絶対に避けてください。

Sidekick Pulse: プロアクティブなマーチャントレコメンデーション

Sidekick Pulseはリアクティブなクエリモデルの対となるプロアクティブな機能です。マーチャントが質問するのを待つ代わりに、Pulseにより注目すべきことが起きたときにエクステンションがマーチャントにインサイトをプッシュできます。

Pulseイベントタイプ

イベントタイプ	説明	例
insight	データ駆動の観察	「ロイヤリティ引き換え率が今週23%増加しました」
alert	注意が必要なもの	「15人のロイヤリティ会員のポイントが3日後に期限切れ」
suggestion	実行可能なレコメンデーション	「ダブルポイントプロモーションの検討を -- トップセグメントが14日間購入していません」
celebration	ポジティブなマイルストーン	「ロイヤリティプログラムが1,000人の会員に到達しました！」

// アプリバックエンドからPulseイベントを登録
import { SidekickPulse } from '@shopify/sidekick-extensions';

const pulse = new SidekickPulse({
  appId: process.env.SHOPIFY_APP_ID,
});

// プロアクティブなインサイトをプッシュ
await pulse.emit({
  shopId: 'shop_abc123',
  type: 'suggestion',
  priority: 'medium',
  title: 'ダブルポイントの機会',
  message: 'VIPセグメント（234人の顧客）の購入間隔平均は45日です。現在38日目です。ターゲットを絞ったダブルポイント週末で再エンゲージメントを促進できます。',
  actions: [
    {
      label: 'ダブルポイントイベントを作成',
      capability: 'create_promotion',
      params: { type: 'double_points', segment: 'vip', duration: '48h' },
    },
    {
      label: '閉じる',
      type: 'dismiss',
    },
  ],
});

カスタムアプリ生成

Sidekickはマーチャントが自然言語を通じてカスタムアプリロジックを生成するのも支援できます。マーチャントが組み込み機能やインストール済みアプリに存在しないワークフローを説明すると、SidekickはShopify Flowオートメーションや簡単なカスタムスクリプトを生成できます。

エクステンション開発者として、Sidekickがあなたのドメインでソリューションを生成する際に使用するテンプレートを登録できます:

// アプリドメインの生成テンプレートを登録
export const generationTemplates = [
  {
    domain: 'loyalty',
    template: 'points_rule',
    description: 'Create a custom points earning rule',
    schema: {
      trigger: ['order_created', 'product_reviewed', 'referral_completed'],
      condition: 'string', // Liquid互換の条件
      pointsFormula: 'string', // 例: "order.total * 2"
    },
    example: {
      trigger: 'order_created',
      condition: 'order.total > 100',
      pointsFormula: 'order.total * 1.5',
    },
  },
];

Sidekick経由のFlowオートメーション

Sidekick Extensionsは、マーチャントが自然言語でShopify Flowオートメーションに組み込めるFlowトリガーとアクションを登録できます。

マーチャントが「VIP顧客が$100以上の注文をしたら、ダブルロイヤリティポイントを付与してお礼メールを送って」と言うと、Sidekickは以下を行います:

1. トリガーを特定（注文作成）
2. 条件を追加（顧客タグがVIP、注文金額 > $100）
3. エクステンションの「ポイント発行」アクションを2倍の倍率で接続
4. お礼用のShopify Emailアクションを追加

Sidekickコマンドによるテーマ編集

アプリにテーマアプリエクステンション（後のモジュールで説明）が含まれる場合、Sidekickはマーチャントが自然言語でアプリブロックを設定・配置するのを支援できます:

「商品ページのカートに追加ボタンの下にロイヤリティポイントウィジェットを追加して」

Sidekickはこれを正しいテーマエディター操作に変換し、マーチャントのテーマの正しいセクションにアプリブロックを配置します。

Sidekick Extensionsのテスト

Shopify CLIコマンドshopify app dev --sidekick-debugを使用して、Sidekickのルーティング決定の詳細ログを有効にしてください。これにより、Sidekickがマーチャントのクエリをどのように解釈し、なぜエクステンションにルーティングするか（またはしないか）を正確に確認できます。開発中に非常に有用です。

ベストプラクティス

1. 機能を集中させる -- 各機能は1つのことをうまく行うべきです。少数の大きな機能より、多数の小さな機能を優先してください。
2. 人間が読めるサマリーを書く -- Sidekickはサマリーテキストをマーチャントに直接提示します。ストアオーナーに話しかけるように書いてください。
3. エラーを適切に処理する -- Sidekickが伝えられる有用なエラーメッセージを返してください。「統計を取得できません」では役に立ちません。「初期同期が完了していないためロイヤリティ統計を読み込めませんでした -- インストール後約5分かかります」が有用です。
4. レート制限を尊重する -- Sidekickはハンドラーを頻繁に呼び出す可能性があります。高コストなクエリをキャッシュし、重い処理にはバックグラウンドジョブを使用してください。
5. すべてをログに記録する -- 開発中はSidekickのUIを見ることができないため、包括的なログが最良のデバッグツールです。

次のステップ

AIショッピングエージェントに進んで、Catalog APIとCheckout Kitを使用した完全な会話型ショッピングアシスタントの構築方法を学びましょう。