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 adisconnect
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 }
ornull
).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