connector-javascript
Before getting started please read the documentation to get acquainted with server-side connectors.
The connector was developed with TypeScript and verified using Nodejs v.8.12 and Express v.4.16.
You can find the latest released version here. or download latest npm package from here.
Implementation
The connector validation must be done on all requests except requests for static and cached pages, resources like images, css files and ....
So, if you add the connector validation logic to a central place, then be sure that the Triggers only fire on page requests (including ajax requests) and not on e.g. image.
The following is an example route in express/nodejs which shows how to validate that a user has been through the queue.
It assumes that your integration configuration file is located in root of the web application.
const QUEUEIT_FAILED_HEADERNAME = "x-queueit-failed";
const QUEUEIT_CONNECTOR_EXECUTED_HEADER_NAME = 'x-queueit-connector';
const QUEUEIT_CONNECTOR_NAME = "nodejs";
const QueueIT_Settings = {
QUEUEIT_CUSTOMER_ID: "",
QUEUEIT_SECRET_KEY: "",
QUEUEIT_API_KEY: "",
QUEUEIT_ENQT_ENABLED: true,
QUEUEIT_ENQT_VALIDITY_TIME: 4 * 60 * 1000,
QUEUEIT_ENQT_KEY_ENABLED: false
};
var express = require('express');
var router = express.Router();
var fs = require('fs');
var QueueItConnector = require('@queue-it/connector-javascript');
function isIgnored(req){
return req.method == 'HEAD' || req.method == 'OPTIONS'
}
router.get('/', function (req, res, next) {
try {
res.header(QUEUEIT_CONNECTOR_EXECUTED_HEADER_NAME, QUEUEIT_CONNECTOR_NAME);
if(isIgnored(req)){
res.render('index', {
node_version: process.version,
express_version: require('express/package').version
});
return;
}
var integrationsConfigString = fs.readFileSync('integrationconfiguration.json', 'utf8');
var customerId = QueueIT_Settings.QUEUEIT_CUSTOMER_ID;
var secretKey = QueueIT_Settings.QUEUEIT_SECRET_KEY;
var enqueueTokenValidityTime = QueueIT_Settings.QUEUEIT_ENQT_VALIDITY_TIME;
var enqueueTokenEnabled = QueueIT_Settings.QUEUEIT_ENQT_ENABLED;
var enqueueTokenKeyEnabled = QueueIT_Settings.QUEUEIT_ENQT_KEY_ENABLED;
var settings = { customerId, secretKey, enqueueTokenEnabled, enqueueTokenValidityTime, enqueueTokenKeyEnabled };
var contextProvider = initializeExpressContextProvider(req, res, settings);
var connector = QueueITConnector.KnownUser;
var queueitToken = req.query[connector.QueueITTokenKey];
var requestUrl = contextProvider.getHttpRequest().getAbsoluteUri();
var requestUrlWithoutToken = getRequestUrlWithoutToken(requestUrl);
var validationResult = connector.validateRequestByIntegrationConfig(
requestUrlWithoutToken, queueitToken, integrationsConfigString,
customerId, secretKey, contextProvider);
if (validationResult.doRedirect()) {
res.set({
'Cache-Control': 'no-cache, no-store, must-revalidate, max-age=0',
'Pragma': 'no-cache',
'Expires': 'Fri, 01 Jan 1990 00:00:00 GMT'
});
if (validationResult.isAjaxResult) {
const headerName = validationResult.getAjaxQueueRedirectHeaderKey();
res.set(headerName, validationResult.getAjaxRedirectUrl());
res.set('Access-Control-Expose-Headers', headerName);
res.render('index', {
node_version: process.version,
express_version: require('express/package').version
});
}
else {
res.redirect(validationResult.redirectUrl);
}
}
else {
if (requestUrl !== requestUrlWithoutToken && validationResult.actionType === "Queue") {
res.redirect(requestUrlWithoutToken);
}
else {
res.render('index', {
node_version: process.version,
express_version: require('express/package').version
});
}
}
}
catch (e) {
console.log("ERROR:" + e);
res.header(QUEUEIT_FAILED_HEADERNAME, 'true');
}
});
function getRequestUrlWithoutToken(requestUrl){
try {
const url = new URL(requestUrl);
const params = new URLSearchParams(url.search);
params.delete(QueueITConnector.KnownUser.QueueITTokenKey);
url.search = params.toString();
return url.toString();
} catch (e) {
console.error('[Queue IT] Could not remove token in URL', e);
return requestUrl;
}
}
module.exports = router;
Code to initialize a contextProvider in Express (requires node module 'cookie-parser'):
function initializeExpressContextProvider(req, res, settings) {
return {
getCryptoProvider: function() {
return {
getSha256Hash: function(secretKey, plaintext) {
const crypto = require('crypto');
const hash = crypto.createHmac('sha256', secretKey)
.update(plaintext)
.digest('hex');
return hash;
}
};
},
getEnqueueTokenProvider: function(){
if(!settings.enqueueTokenEnabled){
return null;
}
return initializeEnqueueTokenProvider(req, settings);
},
getHttpRequest: function () {
var httpRequest = {
getUserAgent: function () {
return this.getHeader("user-agent");
},
getHeader: function (headerName) {
if(headerName === 'x-queueit-clientip')
return this.getUserHostAddress();
var headerValue = req.header(headerName);
if (!headerValue)
return "";
return headerValue;
},
getAbsoluteUri: function () {
return req.protocol + '://' + req.get('host') + req.originalUrl;
},
getUserHostAddress: function () {
return req.ip;
},
getCookieValue: function (cookieKey) {
return req.cookies[cookieKey];
}
};
return httpRequest;
},
getHttpResponse: function () {
var httpResponse = {
setCookie: function (cookieName, cookieValue, domain, expiration, isCookieHttpOnly, isCookieSecure) {
if (domain === "")
domain = null;
const expirationDate = new Date(expiration * 1000);
res.cookie(
cookieName,
cookieValue,
{
expires: expirationDate,
path: "/",
domain: domain,
secure: isCookieSecure,
httpOnly: isCookieHttpOnly
});
}
};
return httpResponse;
}
};
}
Code to initialize a EnqueueTokenProvider in Express
const {Token, Payload} = require("@queue-it/queue-token");
function initializeEnqueueTokenProvider(req, settings){
let enqueueTokenProvider = new QueueITConnector.DefaultEnqueueTokenProvider(
settings.customerId,
settings.secretKey,
settings.enqueueTokenValidityTime,
req.ip,
settings.enqueueTokenKeyEnabled,
Token,
Payload);
return enqueueTokenProvider;
}
QueueIT variables
Variable | Required | Value |
---|
QUEUEIT_CUSTOMER_ID | Yes | Find your Customer ID in the GO Queue-it Platform. |
QUEUEIT_SECRET_KEY | Yes | Your 72 char secret key as specified in Go Queue-it self-service platform. |
QUEUEIT_ENQT_ENABLED | No | Default: true If you do not need to add the enqueue token then set the value to false. |
QUEUEIT_ENQT_VALIDITY_TIME | No | Recommandation: 240000 ms or > 30000 ms |
QUEUEIT_ENQT_KEY_ENABLED | No | Default: false If you need to include custom key in the enqueue token then set value to true. |
Implementation using inline queue configuration
Specify the configuration in code without using the Trigger/Action paradigm. In this case it is important only to queue-up page requests and not requests for resources or AJAX calls. This can be done by adding custom filtering logic before caling the connector.resolveQueueRequestByLocalConfig()
method.
The following is an example (using Express/Nodejs) of how to specify the configuration in code:
const QUEUEIT_FAILED_HEADERNAME = "x-queueit-failed";
const QUEUEIT_CONNECTOR_EXECUTED_HEADER_NAME = 'x-queueit-connector';
const QUEUEIT_CONNECTOR_NAME = "nodejs"
var express = require('express');
var router = express.Router();
var fs = require('fs');
var QueueITConnector = require('@queue-it/connector-javascript');
function isIgnored(req){
return req.method == 'HEAD' || req.method == 'OPTIONS'
}
router.get('/', function (req, res, next) {
try {
res.header(QUEUEIT_CONNECTOR_EXECUTED_HEADER_NAME, QUEUEIT_CONNECTOR_NAME);
if(isIgnored(req)){
res.render('index', {
node_version: process.version,
express_version: require('express/package').version
});
return;
}
var integrationsConfigString = fs.readFileSync('integrationconfiguration.json', 'utf8');
var customerId = QueueIT_Settings.QUEUEIT_CUSTOMER_ID;
var secretKey = QueueIT_Settings.QUEUEIT_SECRET_KEY;
var enqueueTokenValidityTime = QueueIT_Settings.QUEUEIT_ENQT_VALIDITY_TIME;
var enqueueTokenEnabled = QueueIT_Settings.QUEUEIT_ENQT_ENABLED;
var enqueueTokenKeyEnabled = QueueIT_Settings.QUEUEIT_ENQT_KEY_ENABLED;
var settings = { customerId, secretKey, enqueueTokenEnabled, enqueueTokenValidityTime, enqueueTokenKeyEnabled };
var queueConfig = new QueueITConnector.QueueEventConfig();
queueConfig.eventId = ""
queueConfig.queueDomain = "xxx.queue-it.net"
queueConfig.cookieValidityMinute = 15
queueConfig.extendCookieValidity = true
var contextProvider = initializeExpressContextProvider(req, res,settings);
var connector = QueueITConnector.KnownUser;
var queueitToken = req.query[connector.QueueITTokenKey];
var requestUrl = contextProvider.getHttpRequest().getAbsoluteUri();
var requestUrlWithoutToken = getRequestUrlWithoutToken(requestUrl);
var validationResult = connector.resolveQueueRequestByLocalConfig(
requestUrlWithoutToken, queueitToken, queueConfig,
customerId, secretKey, contextProvider);
if (validationResult.doRedirect()) {
res.set({
'Cache-Control': 'no-cache, no-store, must-revalidate, max-age=0',
'Pragma': 'no-cache',
'Expires': 'Fri, 01 Jan 1990 00:00:00 GMT'
});
if (validationResult.isAjaxResult) {
const headerName = validationResult.getAjaxQueueRedirectHeaderKey();
res.set(headerName, validationResult.getAjaxRedirectUrl());
res.set('Access-Control-Expose-Headers', headerName);
res.render('index', {
node_version: process.version,
express_version: require('express/package').version
});
}
else {
res.redirect(validationResult.redirectUrl);
}
}
else {
if (requestUrl !== requestUrlWithoutToken && validationResult.actionType === "Queue") {
res.redirect(requestUrlWithoutToken);
}
else {
res.render('index', {
node_version: process.version,
express_version: require('express/package').version
});
}
}
}
catch (e) {
console.log("ERROR:" + e);
res.header(QUEUEIT_FAILED_HEADERNAME, 'true');
}
});
function getRequestUrlWithoutToken(requestUrl){
try {
const url = new URL(requestUrl);
const params = new URLSearchParams(url.search);
params.delete(QueueITConnector.KnownUser.QueueITTokenKey);
url.search = params.toString();
return url.toString();
} catch (e) {
console.error('[Queue IT] Could not remove token in URL', e);
return requestUrl;
}
}
module.exports = router;
EnqueueToken
An enqueue token can be used for allowing access to waiting room(s). Any user without it can't join the queue. The token will be included when the user is redirected from the connector to the queue.
QueueToken package has been used to generate this token. The generated token will be valid for 4 minute.
Follow the steps below to enable use of enqueue token:
- The waiting room should be configured to require token to enter it. Use Queue-it Go platform or API to setup your waiting room.
- Add a variable with name QUEUEIT_ENQT_ENABLED in settings as mentioned in the example code and value 'true'.
Request body trigger (advanced)
The connector supports triggering on request body content. An example could be a POST call with specific item ID where you want end-users to queue up for.
For this to work, you will need to contact Queue-it support or enable request body triggers in your integration settings in your GO Queue-it platform account.
Once enabled you will need to update your integration so request body is available for the connector.
You may need to add the following middleware in your express app:
const bodyParser = require('body-parser');
app.use(bodyParser.text());
And then add this to the httpRequest object in your http context provider:
getRequestBodyAsString: function () {
if(!req.body || !req.body.toString){
return "";
}
return JSON.stringify(req.body.toString());
}