stigg-widgets

Stigg Widgets — ドロップイン UI

Stigg には、よく使われる料金／請求の UI に対応した、事前構築済みの React コンポーネント（v0.2.1 以降、Next.js の SSR をサポート）と、バニラ JavaScript のクライアント SDK が用意されています。ペイウォール、カスタマーポータル、チェックアウト、クレジット残高の UI を再構築せずに表示するための標準的な方法です。Vue 用と Embed SDK もあります。詳しくは docs.stigg.io をご覧ください。以下のパターンはそれらにも適用できます。

始める前に

上位の stigg スキルに従って、まず検索してください。 ウィジェットの props は更新されるため、最新の情報は Storybook を参照してください。

エージェントから Storybook を読む方法

https://widgets.stigg.io/ の Storybook は JavaScript で描画されるため、基本的な HTTP フェッチではタイトルしか取得できません。ただし、機械可読なインデックスを提供しています。GET https://widgets.stigg.io/index.json を実行すると、ストーリー ID の一覧全体（パターン widgets-<component>--<variant>）が返されます。ユーザーがウィジェットについて言及したら、そのインデックスを取得し、props やスニペットについては docs.stigg.io/documentation/snap-in-widgets/<widget> にあるウィジェットごとのドキュメントページも参照してください。

エージェント向けの完全な手順（探索ワークフロー、ストーリー ID のカテゴリ、ウィジェットごとの標準ドキュメントパス、基本的な WebFetch でタイトルしか取得できない理由）については、references/storybook.md をご覧ください。

ウィジェットの概要

ウィジェット	用途	リファレンス
ペイウォール／料金表	公開料金ページまたはアプリ内アップグレードの案内	references/paywall.md
カスタマーポータル	アプリ内セルフサービス：サブスクリプション、使用状況、請求、プラン選択	references/customer-portal.md
チェックアウト	カートのようなアプリ内決済エクスペリエンス	references/checkout.md
クレジットウィジェット（残高、利用状況、使用状況チャート、付与一覧、自動チャージのステータス、自動チャージの設定）	顧客向けクレジットプール UI	references/credit-widgets.md

セットアップ

すべてのウィジェットは <StiggProvider>（React）または他のフレームワーク SDK における同等のプロバイダー内で使用します。パブリッシャブルキー（client-）を使用してください。サーバーキーは使用しないでください。

import { StiggProvider } from '@stigg/react-sdk';

export function App() {
  return (
    <StiggProvider apiKey="<STIGG_CLIENT_API_KEY>" customerId="<LOGGED_IN_CUSTOMER_ID>">
      <NestedComponents />
    </StiggProvider>
  );
}

Next.js でも同じです。@stigg/react-sdk は SSR をサポートしているため、別のパッケージは不要です。バニラ JavaScript では @stigg/js-client-sdk を使用します。Vue の @stigg/vue-sdk も同じプロバイダー構成に従います。詳しくは docs.stigg.io をご覧ください。

本番環境のセットアップでは、クライアント側のセキュリティ強化（HMAC SHA256 で署名された顧客トークン）を必ず含めてください。 パブリッシャブルキーの詳細パネルで設定します。stigg-api/references/auth.md をご覧ください。

コンポジション：カスタマーポータル＋ペイウォール

CustomerPortal コンポーネントはコンポジションをサポートしています。Paywall をスロット／prop として渡してください。

<CustomerPortal
  paywallComponent={<Paywall />}
  theme={...}
  textOverrides={...}
/>

これにより、同じペイウォール設定を使用して、ポータルの「プラン選択」セクションを構成できます。

コンポジション：モジュラーなカスタマーポータル

デフォルトのポータルレイアウトがアプリに合わない場合は、CustomerPortalProvider の下で各セクションを個別に構成できます。

import {
  CustomerPortalProvider,
  CustomerUsageData,
  PaymentDetailsSection,
  // SubscriptionsOverview, AddonsList, Promotions, InvoicesSection, ...
} from '@stigg/react-sdk';

function App() {
  return (
    <CustomerPortalProvider theme={...} textOverrides={...}>
      <CustomerUsageData />
      <PaymentDetailsSection />
    </CustomerPortalProvider>
  );
}

テーマ設定

方法は 2 つあります。

1. Stigg アプリのノーコードの Widget Designerで色、タイポグラフィ、レイアウトを設定します。エンジニアリング担当者以外でも調整できます。
2. コードでのテーマ設定 — 各コンポーネントの theme={...} prop に加え、ドキュメントに記載された stigg プレフィックス付きクラス（例：stigg-payment-details-section-layout、stigg-{plan.id}、stigg-compatible-addon-{addon.id}、stigg-entitlement-feature-{feature.id}）を対象とするカスタム CSS を使用します。

両方を組み合わせることもできます。CSS クラス一覧の最新情報は、ドキュメントを再取得して確認してください。

テキストの上書き

デフォルトの文言は textOverrides で上書きできます。

const textOverrides = {
  manageSubscription: 'Manage',
  usageTabTitle: 'Usage',
  addonsTabTitle: 'Add-ons',
  promotionsTabTitle: 'Promotions',
  paywallSectionTitle: 'Plans',
  // ...
};

<CustomerPortal textOverrides={textOverrides} paywallComponent={<Paywall />} />

キーの一覧はドキュメントに記載されています。特定のキーが必要な場合は、text overrides を検索してください。

マルチテナント（複数のアクティブなサブスクリプション）

顧客ごとに複数のサブスクリプションを許可する製品（ワークスペース／プロジェクト）では、Paywall、CustomerPortal、Checkout、クレジットウィジェットのすべてに resourceId を渡してください。

<Paywall resourceId="workspace-abc" onPlanSelected={({ plan, customer }) => { ... }} />

<CustomerPortal
  resourceId="workspace-abc"
  paywallComponent={<Paywall resourceId="workspace-abc" />}
/>

また、権利のチェックが適切なスコープで行われるよう、JS クライアントで stigg.setResource('workspace-abc') を呼び出し、コンテキストを離れるときに clearResource() を呼び出します。

ペイウォールのレンダラーを選択する

Stigg の Paywall は、onPlanSelected を通じて顧客の意図を公開します。intentionType に応じて分岐してください。

<Paywall
  onPlanSelected={({ plan, intentionType }) => {
    switch (intentionType) {
      case SubscribeIntentionType.START_TRIAL:
        // provision trial subscription
        break;
      case SubscribeIntentionType.REQUEST_CUSTOM_PLAN_ACCESS:
        // redirect to a contact form
        break;
      case SubscribeIntentionType.UPGRADE_PLAN:
      case SubscribeIntentionType.DOWNGRADE_PLAN:
        // open the Checkout widget or your custom flow
        break;
    }
  }}
/>

キャッシュの更新

プロビジョニング、更新、付与など、顧客を変更する操作をコードで実行すると、JS クライアントのキャッシュに一時的に古いデータが表示されることがあります。SDK には更新メソッドが用意されています。キャッシュの更新については、React / JS SDK のページをご覧ください。

このスキルを使用しないケース

• バックエンドでのヘッドレスなゲーティング（UI なし）→ stigg-entitlements。
• 機能／プラン／アドオンのモデリング → stigg-pricing-modeling。
• サブスクリプションのプログラムによるプロビジョニング／キャンセル → stigg-subscriptions。
• クレジット通貨／付与の定義 → stigg-credits。

よくある間違い

間違い	修正方法
ウィジェットのセットアップにサーバーキーを埋め込む	必ず公開可能キー（client- プレフィックス）を使用してください。読み取り専用として設計されているため、ブラウザーのバンドルに含めても安全です。
本番環境でクライアント側のセキュリティ対策を省略する	公開可能キーは公開されています。HMAC 署名付き顧客トークンを有効にしてください。
アプリの UI にプラン名／価格をハードコーディングする	ウィジェットを使用してください。カタログの変更が自動的に反映されます。ハードコーディングした内容は実際の情報とずれていきます。
複数のアクティブな商品で resourceId を指定し忘れる	ウィジェットが誤ったサブスクリプション（または何もない状態）を対象にします。resourceId を受け取るすべてのウィジェットに渡してください。
<div> セレクターを上書きしてウィジェットのスタイルを変更しようとする	ドキュメントに記載されている stigg-* CSS クラスを使用してください。これらは安定しており、名前空間で管理されています。
ポータルを組み合わせても CustomerPortalProvider でラップし忘れる	サブセクションから顧客／テーマのコンテキストにアクセスできなくなります。
Storybook ではなく記憶を頼りにウィジェットのプロパティを参照する	ライブのストーリー一覧は https://widgets.stigg.io/index.json で確認し、プロパティの表はブラウザーで Storybook UI を開いて確認してください。作成前に再確認してください。
アクティブなサブスクリプションがない状態で顧客ポータルをレンダリングしようとする	一部のセクション（プラン選択／ペイウォール）は機能しますが、ほかのセクション（支払い情報／請求書）には有料サブスクリプションまたは接続済みの請求プロバイダーが必要です。アプリでは適切に案内してください。