Nhúng JavaScript Widget

Mô tả tổng quan

Tính năng Nhúng JavaScript Widget cho phép website bên ngoài nhúng và hiển thị dữ liệu phân tích xu hướng từ nền tảng Naviplus. Tính năng này dùng cơ chế xác thực an toàn qua API key và kiểm tra domain, đảm bảo chỉ website được ủy quyền mới truy cập các bộ dữ liệu cụ thể. Widget nhẹ, responsive, và có thể tùy biến để hòa hợp với thiết kế của khách hàng.

API cung cấp hai controller chính:

• EmbedWidgetController: Xử lý danh sách dataset, chi tiết, và lịch sử
• ProductAnalyzerController: Xử lý dữ liệu phân tích sản phẩm và đánh giá

Sơ đồ hoạt động

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 Endpoints

Endpoint của EmbedWidgetController

Endpoint của ProductAnalyzerController

Tài liệu tình huống (Case Documentation)

Case 1: Nhúng widget thành công - Thao tác dataset

Mô tả

Khách hàng nhúng và hiển thị widget thông tin dataset trên website thành công.

Sơ đồ tuần tự

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

Các bước

Step 1: Nhúng script

• Mô tả: Khách hàng thêm thẻ script của widget vào website
• Triển khai:

  <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>
  

• Kiểm tra:
  • API key phải hợp lệ
  • Domain phải được đăng ký và cho phép

Step 2: Khởi tạo widget

• Mô tả: Script widget khởi tạo và chuẩn bị tải dữ liệu
• Hành động:
  • Tạo container cho widget
  • Thiết lập style và layout
  • Chuẩn bị HTTP request cùng headers

Step 3: Xác thực request

• Mô tả: Hệ thống xác thực API key và domain
• Kiểm tra:
  • Kiểm tra sự tồn tại API key
  • So khớp domain với domain đã đăng ký
  • Kiểm tra trạng thái widget (active/inactive)
  • Rate limit theo domain và API key

Step 4: Xác thực dataset

• Mô tả: Hệ thống xác thực slug dataset được yêu cầu
• Kiểm tra:
  • Kiểm tra sự tồn tại của dataset
  • Kiểm tra quyền group (group của widget phải có quyền với dataset)
  • Kiểm tra trạng thái dataset (active/inactive)

Step 5: Trả dữ liệu dataset

• Mô tả: Hệ thống trả về thông tin dataset yêu cầu
• Phản hồi:
  • Thành công: 200 OK kèm dữ liệu JSON
  • Lỗi: Mã lỗi và thông điệp phù hợp

Step 6: Render widget

• Mô tả: Script widget render phần hiển thị dataset
• Hành động:
  • Xử lý dữ liệu nhận được
  • Tạo biểu đồ và metrics
  • Áp dụng style tuỳ chỉnh nếu có

Case 2: Widget phân tích sản phẩm

Mô tả

Khách hàng nhúng và hiển thị widget phân tích sản phẩm trên website thành công.

Sơ đồ tuần tự

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

Các bước

Step 1-3: Giống Case thao tác dataset

Step 4: Xác thực Dataset & History

• Mô tả: Hệ thống xác thực cả slug dataset và wldh_slug history
• Kiểm tra:
  • Kiểm tra sự tồn tại của dataset
  • Kiểm tra sự tồn tại của bản ghi history
  • Kiểm tra quyền group cho cả dataset và history
  • Kiểm tra trạng thái của cả hai thực thể

Step 5: Trả dữ liệu phân tích sản phẩm

• Mô tả: Hệ thống trả thông tin phân tích sản phẩm
• Endpoint sẵn có:
  • Danh sách sản phẩm cơ sở
  • Phân tích sản phẩm tương tự
  • Bảng so sánh sản phẩm
  • Câu review
  • Biểu đồ review (tổng quan, theo viewpoint, xu hướng doanh số)

Step 6: Render widget phân tích sản phẩm

• Mô tả: Script widget render phần hiển thị phân tích sản phẩm
• Hành động:
  • Xử lý dữ liệu sản phẩm
  • Tạo biểu đồ so sánh
  • Hiển thị phân tích review
  • Trình bày biểu đồ xu hướng

Case 3: Cố gắng truy cập trái phép

Mô tả

Website chưa được ủy quyền cố gắng dùng widget với API key hợp lệ.

Sơ đồ tuần tự

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

Các bước

Step 1: Nhúng script

• Mô tả: Website không được phép thêm thẻ script
• Hành động: Giống case thành công, nhưng domain không hợp lệ

Step 2: Khởi tạo

• Mô tả: Giống case thành công

Step 3: Xác thực request

• Mô tả: Hệ thống phát hiện domain không khớp
• Kiểm tra:
  • API key hợp lệ
  • Domain không khớp domain đã đăng ký
  • Ghi log cảnh báo bảo mật

Step 4: Trả lỗi

• Mô tả: Hệ thống trả lỗi ủy quyền
• Phản hồi: 403 Forbidden kèm thông điệp lỗi

Step 5: Hiển thị lỗi

• Mô tả: Widget hiển thị thông điệp lỗi
• Hành động: Hiển thị thông điệp phù hợp tới người dùng cuối

Bảng và cột liên quan Database

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

Xử lý lỗi

• Log

  • Ghi log mọi lần truy cập vào security log
  • Gắn cờ API key không hợp lệ và domain không được phép
  • Theo dõi vi phạm rate limit

• Chi tiết lỗi:

  Status Code	Thông điệp lỗi	Mô tả
  401	"Invalid API key"	Khi API key thiếu hoặc không hợp lệ
  403	"Domain not authorized"	Khi domain gửi request không được đăng ký
  403	"You do not have access to this dataset"	Khi group của widget không có quyền truy cập dataset
  404	"Dataset not found"	Khi dataset slug không tồn tại
  404	"Dataset history not found"	Khi history slug không tồn tại
  429	"Too many requests"	Khi vượt quá giới hạn rate limit

Ghi chú bổ sung

• Hiệu năng

  • Script widget được minify và nén
  • Tài nguyên được phục vụ qua CDN để tải nhanh
  • Payload dữ liệu tối ưu kích thước

• Bảo mật

  • API key phải được coi là thông tin nhạy cảm
  • Xác thực domain để ngăn nhúng trái phép
  • Rate limiting để tránh lạm dụng
  • Cấu hình CORS nghiêm ngặt

• Nâng cấp tương lai

  • Hỗ trợ tuỳ biến theme qua CSS variables
  • Tuỳ chọn lọc tương tác
  • Cập nhật dữ liệu theo thời gian gần thực
  • Hỗ trợ nhiều dataset trong một widget