developer-sandbox

インタラクティブなプレイグラウンドとデモ環境

導入を決める前に、開発者が製品を体験できるようにしましょう。優れたプレイグラウンドは、製品が自分の課題を解決してくれるかどうかという不確実さを取り除き、導入の最大の障壁をなくします。

概要

開発者向けプレイグラウンドには、複数の目的があります。

• 評価：セットアップに時間をかける前に、開発者がテストできます
• 学習：概念を理解するためのインタラクティブな環境です
• マーケティング：営業との通話なしで機能を実演できます
• サポート：問題のデバッグに利用できる再現可能な環境です

このスキルでは、興味を持った訪問者をアクティブユーザーに変えるプレイグラウンドの設計方法を扱います。

始める前に

developer-audience-context スキルを確認して、以下を把握しましょう。

• 開発者は登録前に何を検証したいと考えていますか？
• この分野で一般的な評価ワークフローはどのようなものですか？
• 競合製品ではどのようなプレイグラウンドが提供されていますか？
• 価値を実証するために必要な、最小限の体験とはどのようなものですか？

プレイグラウンドは、評価時に開発者が抱く疑問に答えるものであるべきです。

プレイグラウンドの設計原則

原則 1：すぐに成果を得られる

開発者がページにアクセスしてから 10 秒以内に、意味のあるものを目にできるようにしましょう。

良い例：ページが読み込まれると、動作するサンプルがすでに実行されている 悪い例：「ここにコードを入力してください」というプレースホルダーがある空のエディター

<div class="playground">
  <div class="editor">
    <pre><code>// Analyze sentiment of this text
const result = await api.analyze("I love this product!");
console.log(result.sentiment); // "positive"</code></pre>
  </div>
  <div class="output">
    <pre>{ "sentiment": "positive", "confidence": 0.94 }</pre>
  </div>
  <button class="run-btn">Run ▶️</button>
</div>

原則 2：段階的に複雑さを増す

まずはシンプルに始め、開発者の興味に応じて、さらに深く試せるようにしましょう。

レベル 1：ワンクリックデモ

[Analyze Text] → See result immediately

レベル 2：編集可能な入力

[Edit the text] → [Run] → See result

レベル 3：API へのフルアクセス

Edit code → Modify parameters → See raw request/response

レベル 4：完全なプレイグラウンド

Multiple files → Import SDK → Build mini-app

原則 3：実際の API、実際の結果

結果を偽装してはいけません。サンドボックス認証情報を使って、実際の API を利用しましょう。

実際の API が重要な理由：

• 信頼を築きます（デモではなく、実際の製品を体験できます）
• 実際のパフォーマンス特性を示します
• 実際のエラー処理を実演します
• 登録後に予想外のことが起きません

原則 4：手間をゼロにする

基本的なプレイグラウンドでは登録不要にしましょう。インストールも設定も不要です。

❌ Bad: "Sign up to try the playground"
❌ Bad: "Install our CLI to continue"
❌ Bad: "Configure your environment..."

✅ Good: Works immediately in browser

サンプルの事前入力

サンプル選定の方針

以下を満たすサンプルを選びましょう。

1. 30 秒で中核的な価値を示す
2. 開発者が抱える現実の課題を解決する
3. 競合他社との差別化を実証する
4. シンプルなものから高度なものへ複雑さを段階的に高める

サンプルのカテゴリ

「Hello World」サンプル

• API をできる限りシンプルに使う例です
• 一切変更せずに動作する必要があります
• システムが動作していることを証明します

// Example: Text Analysis API
const result = await api.analyze("Hello, world!");
// Output: { words: 2, characters: 13 }

「なるほど」と思えるサンプル

• 製品ならではの機能を示します
• 「すごい、こんなに簡単なんだ」という反応を引き出します
• これは最も重要なサンプルです

// Example: Shows AI doing something impressive
const result = await api.summarize(longArticle);
// Output: A perfect 3-sentence summary

「実際のユースケース」サンプル

• 開発者が実際に直面するシナリオを扱います
• 特定の課題を解決する方法を示します
• さまざまなユースケースに対応する複数のサンプルを用意します

// Example 1: E-commerce - Analyze product reviews
// Example 2: Support - Classify incoming tickets
// Example 3: Social - Detect spam comments

「インテグレーション」サンプル

• よく使われるツールと連携する製品の動作を示します
• 「自分の技術スタックでも使えるか？」という疑問に答えます

// Example: Integration with Express.js
app.post('/analyze', async (req, res) => {
  const result = await api.analyze(req.body.text);
  res.json(result);
});

サンプルの品質チェックリスト

• 変更せずにサンプルを実行できる
• 出力が興味深い、または印象的である
• コードが言語のベストプラクティスに従っている
• コメントで処理内容を説明している
• 実際のユースケースが明確である
• 「他に何ができるのだろう？」という自然な興味につながる

共有と埋め込み

共有可能なプレイグラウンド URL

プレイグラウンドの状態を開発者が共有できるようにしましょう。

https://playground.example.com/?code=BASE64_ENCODED_CODE
https://playground.example.com/share/abc123 (stored state)

ユースケース：

• チームメイトとのコード共有
• Stack Overflow の回答からのリンク
• 再現手順を含むバグ報告
• ブログ記事内のコードスニペット

埋め込み可能なプレイグラウンド

開発者が自分のコンテンツにプレイグラウンドを埋め込めるようにしましょう。

<iframe
  src="https://playground.example.com/embed/quickstart"
  width="100%"
  height="400px"
></iframe>


<div class="example-playground" data-example="quickstart"></div>
<script src="https://playground.example.com/embed.js"></script>

埋め込み時の考慮事項

サイズとパフォーマンス：

• 軽量な埋め込みスクリプト（50KB 未満）
• 表示されるまでプレイグラウンドの読み込みを遅延
• 幅はレスポンシブにし、高さは設定可能にする

カスタマイズ：

• テーマのオプション（ライト／ダーク、ホストサイトに合わせる）
• 特定の UI 要素の表示／非表示
• 読み取り専用モードと編集可能モード

クレジット表記：

• 製品に戻るリンクを含む、控えめなブランディング
• 「Powered by [Product]」フッター
• 「完全なプレイグラウンドで編集」リンク

ゲーティングするか、しないか

ゲートなしにする場合

ゲートなし（サインアップ不要）にするケース：

• 開発者が導入を検討している
• 例を通じて、製品の中心的な価値を示す
• レート制限によって不正利用を防止できる
• 主な目的がファネル上部での認知度向上である

ゲートを設ける場合

ゲートあり（サインアップ必須）にするケース：

• 本番環境の API リソースを使用する
• 個人用または保存済みのプレイグラウンドにアクセスする
• アカウントが必要な高度な機能を利用する
• 外部で使用する API キーを生成する

段階的にゲートを設ける戦略

┌─────────────────────────────────────────────────────────┐
│ UNGATED                                                  │
│ • Run pre-built examples                                │
│ • Edit and re-run examples                              │
│ • Share playground URLs                                 │
├─────────────────────────────────────────────────────────┤
│ FREE SIGNUP                                             │
│ • Save playgrounds                                      │
│ • Get API key for external use                         │
│ • Access more examples                                  │
│ • Higher rate limits                                    │
├─────────────────────────────────────────────────────────┤
│ PAID                                                    │
│ • Production API access                                 │
│ • Team features                                         │
│ • Premium models/features                               │
└─────────────────────────────────────────────────────────┘

ゲートを設ける際の UX

ゲートを設ける場合は、ユーザーの負担を最小限に抑えます。

<div class="save-prompt">
  <p>Want to save this playground?</p>
  <button onclick="signup()">Create free account</button>
  <button onclick="dismiss()">Continue without saving</button>
</div>


<div class="modal">
  <p>Sign up to continue using the playground</p>
  <form></form>
</div>

プレイグラウンドからサインアップへのコンバージョン

コンバージョンファネル

Playground Visit
      ↓
Runs First Example (Time to first interaction)
      ↓
Modifies Example (Engagement)
      ↓
Explores More Examples (Interest)
      ↓
Hits Limitation (Trigger)
      ↓
Signs Up (Conversion)

コンバージョンのきっかけを設計する

サインアップを促す自然な制限：

// Rate limit message
"You've used 10/10 free playground requests today.
 Sign up for 1,000 free requests/month."

// Feature tease
"This example uses our Pro model.
 Sign up to try it free."

// Save prompt
"Your playground session will expire in 30 minutes.
 Create an account to save your work."

人為的な障壁は避けます。

// Bad: Arbitrary block
"Sign up to run more than 3 examples"

// Bad: Feature that should be free
"Sign up to see request/response details"

コンバージョンのベストプラクティス

明確な価値提案：

┌─────────────────────────────────────────┐
│ Create a free account                   │
│                                         │
│ ✓ Get your own API key                 │
│ ✓ Save and share playgrounds           │
│ ✓ 1,000 free API calls/month           │
│                                         │
│ [Sign up with GitHub]                   │
│ [Sign up with Google]                   │
│ [Sign up with email]                    │
└─────────────────────────────────────────┘

コンテキストを維持する：

• サインアップ後、同じプレイグラウンドの状態に戻す
• コードに API キーをあらかじめ入力しておく
• ユーザーが行っていた作業に関連する「次のステップ」を表示する

ファネルを計測する：

analytics.track('playground_visit');
analytics.track('playground_first_run');
analytics.track('playground_code_edit');
analytics.track('playground_signup_prompt_shown');
analytics.track('playground_signup_started');
analytics.track('playground_signup_completed');

プレイグラウンドのアーキテクチャ

クライアントサイドのプレイグラウンド

最適な用途：

• JavaScript／TypeScript SDK
• ブラウザベースの API
• レイテンシが重要な場合

アーキテクチャ：

┌──────────────────────────────────────────┐
│ Browser                                  │
│  ┌─────────────┐    ┌────────────────┐ │
│  │ Monaco      │    │ Preview/Output │ │
│  │ Editor      │ →  │ Iframe        │ │
│  └─────────────┘    └────────────────┘ │
│         ↓                    ↓          │
│  Bundler (esbuild-wasm) → Execute       │
│                              ↓          │
│                        Your API         │
└──────────────────────────────────────────┘

サーバーサイドのプレイグラウンド

最適な用途：

• Python、Go、Ruby など
• 分離が重要な場合
• 依存関係が複雑な場合

アーキテクチャ：

┌────────────────────────────────────────────────┐
│ Browser                                        │
│  ┌─────────────┐    ┌────────────────────┐   │
│  │ Editor      │    │ Output             │   │
│  └─────────────┘    └────────────────────┘   │
│         ↓                    ↑                │
└─────────│────────────────────│────────────────┘
          │                    │
          ↓                    │
   ┌──────────────────────────────────────┐
   │ Backend                              │
   │  ┌────────────┐    ┌─────────────┐ │
   │  │ Code       │ →  │ Sandbox     │ │
   │  │ Receiver   │    │ Container   │ │
   │  └────────────┘    └─────────────┘ │
   └──────────────────────────────────────┘

セキュリティに関する考慮事項

サンドボックスの分離：

• ユーザーコードをコンテナ内で実行する
• CPU、メモリ、ネットワークを制限する
• ホストのファイルシステムへのアクセスを許可しない
• 終了しないプロセスを強制終了する

API の保護：

• IP／セッションごとにレート制限を設ける
• サンドボックス専用の API 認証情報を使用する
• 不正利用のパターンを監視する

コンテンツの安全性：

• 生成されたコンテンツをスキャンする
• 悪意のある出力をブロックする
• 監査用にログを記録する

プレイグラウンドの UX コンポーネント

必須の UI 要素

┌─────────────────────────────────────────────────────────────┐
│ [Examples ▼] [Docs] [Share] [Sign Up]                       │
├───────────────────────────────┬─────────────────────────────┤
│                               │                             │
│  // Your code here            │  Output                     │
│  const result = await         │  {                         │
│    api.analyze("Hello");      │    "sentiment": "neutral"  │
│                               │  }                         │
│                               │                             │
│                               │                             │
├───────────────────────────────┴─────────────────────────────┤
│ [▶ Run]  [Reset]  [Copy Code]  [Copy as cURL]              │
└─────────────────────────────────────────────────────────────┘

エディターの機能

• 構文ハイライト
• SDK メソッドの自動補完
• エラーのハイライト表示
• 行番号
• 複数ファイルのサポート（高度な機能）

出力の機能

• 整形された JSON
• ネストされたオブジェクトの折りたたみ
• 出力をコピーするボタン
• リクエスト／レスポンスの切り替え
• 実行時間の情報

ツール

コードエディター

• Monaco Editor：VS Code のエディター（機能が豊富）
• CodeMirror：軽量で拡張性に優れています
• Ace Editor：長年の実績があり、十分に検証されています

サンドボックス

• Firecracker：軽量な VM
• gVisor：コンテナのサンドボックス化
• WebContainers：ブラウザベースの Node.js

プレイグラウンドプラットフォーム

• CodeSandbox：開発環境一式
• StackBlitz：WebContainer ベース
• Replit：複数の言語をサポート
• カスタム：自由に制御できる独自の環境を構築

埋め込み

• iframes：シンプルですが、制限があります
• Web Components：分離性に優れています
• スクリプト埋め込み：最も柔軟です

関連スキル

• api-onboarding：オンボーディングツールとしてのプレイグラウンド
• docs-as-marketing：ドキュメント内のインタラクティブな例
• sdk-dx：プレイグラウンドでの利用に適した SDK の設計
• developer-metrics：プレイグラウンドの効果測定
• developer-audience-context：デモ内容の理解