JavaScript ウィジェット埋め込み

概要説明

JavaScript ウィジェット埋め込み機能により、外部サイトで Naviplus プラットフォームのトレンド分析データを表示できます。API キーとドメイン検証による安全な認可を行い、許可されたサイトのみが特定データセットへアクセス可能です。ウィジェットは軽量・レスポンシブで、デザインに馴染むカスタマイズ性を備えています。

API は次の2つの主要コントローラを提供します:

• EmbedWidgetController: データセット一覧・詳細・履歴を提供
• ProductAnalyzerController: 商品分析・レビュー関連データを提供

アクティビティ図

flowchart TD
    A[Client Website] -->|Embed Script Tag| B[Load Widget]
    B -->|Request with API Key| C{Validate Request}
    C -->|Invalid| D[Return Error]
    C -->|Valid| E[Route to Controller]
    E --> F{Controller Type}
    F -->|EmbedWidget| G[Dataset Operations]
    F -->|ProductAnalyzer| H[Product Analysis]
    G --> I[Return Dataset Data]
    H --> J[Return Analysis Data]
    I --> K[Render Widget]
    J --> K
    K --> L[Interactive Data Visualization]

API エンドポイント

EmbedWidgetController のエンドポイント

ProductAnalyzerController のエンドポイント

ケースドキュメント

ケース1: ウィジェット埋め込み成功 - データセット操作

説明

クライアントサイトにデータセット情報ウィジェットを正常に埋め込み、表示します。

シーケンス図

sequenceDiagram
    participant Client as Client Website
    participant Widget as Widget Script
    participant API as EmbedWidgetController
    participant Auth as ValidateWidgetRequest
    participant Repo as EmbedJsWidgetRepository
    participant DataRepo as WishlistDatasetHistoryRepository
    participant DB as Database

    Note over Client,Widget: Step 1: Embed Script
    Client->>Widget: Include script tag with API key

    Note over Widget,API: Step 2: Initialize Widget
    Widget->>API: GET /api/v1/widget/{slug}
    
    Note over API,Auth: Step 3: Validate Request
    API->>Auth: Check API key & domain
    Auth->>Repo: findByApiKey(api_key)
    Repo->>DB: Query
    DB-->>Repo: Widget Data
    Repo-->>Auth: Widget Entity
    
    Note over Auth,DataRepo: Step 4: Validate Dataset
    Auth->>DataRepo: findBySlug(slug)
    DataRepo->>DB: Query
    DB-->>DataRepo: Dataset Data
    DataRepo-->>Auth: Dataset Entity
    Auth->>Auth: Check Group Permissions
    
    Note over Auth,API: Step 5: Request Authorized
    Auth-->>API: Request Authorized
    
    Note over API,Widget: Step 6: Return Data
    API-->>Widget: JSON Dataset Data
    
    Note over Widget,Client: Step 7: Render Widget
    Widget->>Client: Render Dataset Visualization

手順

Step 1: スクリプト埋め込み

• 説明: クライアントがウィジェットの <script> タグをサイトへ追加します
• 実装:

  <div class="widget-container">
    <tv-analysis-widget 
      id="id-widget"
      token="your_token" 
      slug="slug-name">
    </tv-analysis-widget>
  </div>
  <script type="module" src="https://trend-viewer.com/widget/widget.ce.js"></script>
  

• 検証:
  • API キーが有効であること
  • ドメインが登録・許可されていること

Step 2: ウィジェット初期化

• 説明: ウィジェットスクリプトを初期化し、データ取得の準備をします
• アクション:
  • ウィジェットコンテナの作成
  • スタイルとレイアウトの設定
  • ヘッダー付き HTTP リクエストの準備

Step 3: リクエスト検証

• 説明: API キーとドメインを検証します
• 検証:
  • API キー存在チェック
  • 登録ドメインとの照合
  • ウィジェットのステータス確認（active/inactive）
  • ドメインと API キーに基づくレート制限

Step 4: データセット検証

• 説明: リクエストされたデータセットの slug を検証します
• 検証:
  • データセット存在チェック
  • グループ権限チェック（ウィジェットのグループにアクセス権があるか）
  • データセットのステータス確認（active/inactive）

Step 5: データセットデータ返却

• 説明: リクエストされたデータセット情報を返します
• レスポンス:
  • 成功: 200 OK と JSON データ
  • エラー: 適切なエラーコードとメッセージ

Step 6: ウィジェット描画

• 説明: ウィジェットスクリプトがデータセットを可視化します
• アクション:
  • 受信データの処理
  • チャートと指標の生成
  • 任意のカスタムスタイルの適用

ケース2: 商品分析ウィジェット

説明

クライアントサイトに商品分析ウィジェットを正常に埋め込み、表示します。

シーケンス図

sequenceDiagram
    participant Client as Client Website
    participant Widget as Widget Script
    participant API as ProductAnalyzerController
    participant Auth as ValidateWidgetRequest
    participant Repo as EmbedJsWidgetRepository
    participant DataRepo as WishlistDatasetHistoryRepository
    participant DB as Database

    Note over Client,Widget: Step 1: Embed Script
    Client->>Widget: Include script tag with API key

    Note over Widget,API: Step 2: Initialize Widget
    Widget->>API: GET /api/v1/widget/{slug}/{wldh_slug}/products
    
    Note over API,Auth: Step 3: Validate Request
    API->>Auth: Check API key & domain
    Auth->>Repo: findByApiKey(api_key)
    Repo->>DB: Query
    DB-->>Repo: Widget Data
    Repo-->>Auth: Widget Entity
    
    Note over Auth,DataRepo: Step 4: Validate Dataset & History
    Auth->>DataRepo: findBySlug(slug)
    DataRepo->>DB: Query
    DB-->>DataRepo: Dataset Data
    DataRepo-->>Auth: Dataset Entity
    Auth->>Auth: Check Group Permissions
    
    Note over Auth,API: Step 5: Request Authorized
    Auth-->>API: Request Authorized
    
    Note over API,Widget: Step 6: Return Product Data
    API-->>Widget: JSON Product Analysis Data
    
    Note over Widget,Client: Step 7: Render Widget
    Widget->>Client: Render Product Analysis Visualization

手順

Step 1-3: データセット操作と同様

Step 4: データセット & 履歴の検証

• 説明: データセット slug と履歴 wldh_slug の両方を検証します
• 検証:
  • データセットの存在確認
  • 履歴レコードの存在確認
  • データセットおよび履歴に対するグループ権限チェック
  • 両エンティティのステータス確認

Step 5: 商品分析データ返却

• 説明: 商品分析情報を返します
• 利用可能なエンドポイント:
  • ベース商品一覧
  • 類似商品分析
  • 商品比較テーブル
  • レビュー文
  • レビューチャート（一般、ビューポイント別、売上トレンド）

Step 6: 商品分析ウィジェット描画

• 説明: ウィジェットスクリプトが商品分析を可視化します
• アクション:
  • 商品データの処理
  • 比較チャートの生成
  • レビュー分析の表示
  • トレンドの可視化

ケース3: 不正アクセス試行

説明

有効な API キーを使っているが、許可されていないサイトからのアクセス試行。

シーケンス図

sequenceDiagram
    participant Client as Unauthorized Website
    participant Widget as Widget Script
    participant API as WidgetController
    participant Auth as ValidateWidgetRequest
    participant Repo as EmbedJsWidgetRepository

    Note over Client,Widget: Step 1: Embed Script
    Client->>Widget: Include script tag with API key

    Note over Widget,API: Step 2: Initialize Widget
    Widget->>API: GET /api/v1/widget/{slug}
    
    Note over API,Auth: Step 3: Validate Request
    API->>Auth: Check API key & domain
    Auth->>Repo: findByApiKey(api_key)
    Repo-->>Auth: Widget Entity
    
    Note over Auth,API: Step 4: Domain Validation Fails
    Auth->>Auth: Compare Origin domain with registered domain
    Auth-->>API: Domain not authorized (403)
    
    Note over API,Widget: Step 5: Return Error
    API-->>Widget: 403 Forbidden
    
    Note over Widget,Client: Step 6: Display Error
    Widget->>Client: Render Error Message

手順

Step 1: スクリプト埋め込み

• 説明: 許可されていないサイトがスクリプトを読み込みます
• アクション: 成功ケースと同様だが、ドメインが未許可

Step 2: 初期化

• 説明: 成功ケースと同様

Step 3: リクエスト検証

• 説明: ドメイン不一致を検出
• 検証:
  • API キーは有効
  • ドメインが登録ドメインと一致しない
  • セキュリティ警告をログ出力

Step 4: エラー返却

• 説明: 認可エラーを返す
• レスポンス: 403 Forbidden とエラーメッセージ

Step 5: エラー表示

• 説明: ウィジェットがエラーメッセージを表示
• アクション: 利用者に適切なエラーメッセージを表示

データベース関連テーブル & フィールド

erDiagram
    EMBED_JS_WIDGETS {
        bigint id
        string name
        string domain
        string api_key
        bigint group_id
        enum status
        datetime created_at
        datetime updated_at
    }
    GROUPS {
        bigint id
        string name
        datetime created_at
        datetime updated_at
    }
    WISHLIST_DATASET_HISTORIES {
        bigint id
        string slug
        string name
        datetime created_at
        datetime updated_at
    }
    WISHLIST_TO_GROUPS {
        bigint wishlist_id
        bigint group_id
    }

    EMBED_JS_WIDGETS ||--o{ GROUPS : belongs_to
    WISHLIST_DATASET_HISTORIES ||--o{ WISHLIST_TO_GROUPS : has
    GROUPS ||--o{ WISHLIST_TO_GROUPS : has

エラーハンドリング

• ログ

  • すべてのアクセス試行をセキュリティログに記録
  • 無効な API キーや未許可ドメインをフラグ
  • レート制限違反を追跡

• エラー詳細:

  ステータスコード	エラーメッセージ	説明
  401	"Invalid API key"	API キーが欠落/無効な場合
  403	"Domain not authorized"	リクエストドメインが未登録の場合
  403	"You do not have access to this dataset"	ウィジェットのグループがデータセットへアクセス不可の場合
  404	"Dataset not found"	指定されたデータセットの slug が存在しない場合
  404	"Dataset history not found"	指定された履歴 slug が存在しない場合
  429	"Too many requests"	レート制限を超過した場合

追加メモ

• パフォーマンス配慮

  • ウィジェットスクリプトは最小化・圧縮済み
  • アセットは CDN から配信
  • データペイロードはサイズ最適化

• セキュリティ対策

  • API キーは機密情報として扱う
  • ドメイン検証により不正な埋め込みを防止
  • レート制限で濫用を防止
  • CORS ヘッダーは厳格に設定

• 将来拡張

  • CSS 変数によるテーマカスタマイズ
  • インタラクティブなフィルタリング
  • 近リアルタイムなデータ更新
  • 単一ウィジェットで複数データセットのサポート