包详细信息

j-queue-sdk-web

joinguyen4.3kMIT4.0.1

A TypeScript package to check WebSocket connection status and control web access with a popup

websocket, connection, popup, access-control

自述文件

J-Queue SDK Web

The J-Queue SDK Web is a JavaScript library for managing online queue systems in web applications. It provides a seamless integration with a WebSocket-based queue service, displaying a customizable popup UI to inform users about their queue status.

Features

  • Real-time Queue Management: Connects to a WebSocket server to receive real-time updates on queue position and status.
  • Customizable Popup UI: Displays a loading or queue position popup with customizable styles, colors, and languages (English and Korean).
  • Navigation Control: Prevents navigation during queue wait to ensure users don't lose their place.
  • Session Storage: Persists queue tokens and connect keys in sessionStorage for continuity.
  • Script Tag Configuration: Supports initialization via data-* attributes on the script tag for easy setup.
  • Event Listeners: Allows adding listeners for queue status updates.
  • Custom Events: Supports handling custom WebSocket events with utility functions.

Installation

Install the SDK via npm:

npm install j-queue-sdk-web

Or include it directly in your HTML using a CDN (replace x.x.x with the desired version):

<script src="https://unpkg.com/j-queue-sdk-web@<version>/dist/j-queue-sdk-web.js"></script>

Usage

Programmatic Initialization

Import and initialize the SDK in your JavaScript/TypeScript code:

import ConnectionJQueueSdkWeb from 'j-queue-sdk-web';

const config = {
  wsUrl: 'https://api-extra-queue.pressai.kr',
  apiUrl: 'https://api-extra-queue.pressai.kr',
  socketConfig: {
    query: { connect_key: 'your_connect_key' },
  },
  popupConfig: {
    isShowLoadingOnConnect: true,
    language: 'en',
    textColor: '#276bff',
    loaderGradientStart: '#276bff',
    loaderGradientEnd: 'rgba(39,107,255,0.05)',
  },
};

ConnectionJQueueSdkWeb.init(config)
  .then(({ disconnect }) => {
    console.log('J-Queue SDK initialized');
    // Store disconnect function for later use
  })
  .catch((error) => {
    console.error('Initialization failed:', error);
  });

// Add a status listener
ConnectionJQueueSdkWeb.addStatusListener((status) => {
  console.log('Queue status:', status);
});

Script Tag Initialization

Include the SDK script with data-* attributes to auto-initialize:

<script
  src="https://unpkg.com/j-queue-sdk-web@<version>/dist/j-queue-sdk-web.js"
  data-ws-url="https://api-extra-queue.pressai.kr"
  data-api-url="https://api-extra-queue.pressai.kr"
  data-connect-key="your_connect_key"
  data-show-loading="true"
  data-language="ko"
  data-mode="prod" 
  data-text-color="#276bff"
  data-loader-gradient-start="#276bff"
  data-loader-gradient-end="rgba(39,107,255,0.05)"
></script>

The SDK will automatically initialize using these attributes when the script loads.

Configuration Options

The InitConfig interface defines the configuration options:

  • wsUrl: WebSocket URL (default: https://api-extra-queue.pressai.kr for prod, https://dev-api-extra-queue.pressai.kr for dev).
  • apiUrl: API URL for operations like leaving the queue.
  • socketConfig: Socket.IO configuration.
    • query: Query parameters (e.g., { connect_key: 'your_key' }).
    • transports: Transport methods (default: ['websocket']).
    • reconnectionAttempts: Number of reconnection attempts (default: 3).
    • reconnectionDelay: Delay between reconnections (default: 1000ms).
  • popupConfig: Popup UI configuration.
    • content: Custom HTML or a function returning HTML based on queue position.
    • language: 'en' or 'ko' (default: 'ko').
    • textColor: Text color for popup content.
    • loaderGradientStart: Starting color for loader gradient.
    • loaderGradientEnd: Ending color for loader gradient.
    • style: Custom CSS for the popup.
    • isShowLoadingOnConnect: Show loading popup during connection (default: false).
  • customEvents: Handlers for custom WebSocket events.
  • option: Storage key settings.
    • storageTokenKey: sessionStorage key for queue token (default: 'queue_token').
    • storageConnectKey: sessionStorage key for connect key (default: 'connect_key').

Methods

  • init(config: InitConfig): Initializes the SDK. Returns a promise resolving to an object with a disconnect method.
  • addStatusListener(listener): Adds a callback to receive queue status updates.
  • removeStatusListener(listener): Removes a status listener.
  • getQueueStatus(): Returns the current queue status ({ uuid, position, status } or null).
  • initFromScriptAttributes(): Initializes the SDK using script tag attributes (called automatically on load).

Queue Statuses

Defined in the OnlineQueueStatus enum:

  • WAITING (1): User is waiting in the queue.
  • ACTIVE (2): User is active and can proceed.
  • EMPTY (3): Queue is empty or connect key is invalid.

Development

Prerequisites

  • Node.js >= 14
  • npm >= 6

Setup

git clone <repository-url>
cd j-queue-sdk-web
npm install

Running Tests

The SDK includes unit tests using Jest. Run them with:

npm test

Building

To build the SDK:

npm run build

Contributing

Contributions are welcome! Please submit a pull request or open an issue to discuss changes.

License

MIT

Repository