Managing queues

Suppose you are planning an attraction at an upcoming experience. You anticipate it will be popular and you don't want to be put in a position where an unwieldy queue develops.

This is an ideal use case for the XPKit Queues service.

With this service you can add a visitor to a virtual queue and notify them via SMS or email once they have reached the head of the queue. Visitors can then go about their day without standing around getting impatient, waiting for minutes or even hours in a long line of people.

Creating a queue

In the following example our attraction will be a VR game that visitors can queue to play.

Let's create our queue in XPKit Portal, it will look something like this:

{
    "name": "Play VR game queue",
    "queue_id": "play-vr-game-queue",
    "experience_id": "developer-conference-2022",
}

Your applications can now use the Queue ID to monitor and update the queue in real time.

Add a user to the queue

The host of the attraction could sign visitors up and add them to the queue via a tablet web app that you write. The app would add a visitor (queueitem) like so:

{
    "status": "wait",
    "notification_sms": "+441234567890",
    "notification_data": {
        "first_name": "Sarah"
    }
}

The web app captures the visitor's SMS number so they can be notified later. Any data provided under notification_data will be made available in either SMS messages or email templates through personalisation tags.

Updating the queue

Once it is Sarah's time to play the game the host will use the tablet to change her status to call (previously it was wait - the default).

{
   "status": "call"
}

Notifications

To ensure Sarah is notified it is her time to play, let's update our queue (in XPKit Portal) so it has the correct rule to do so.

Prerequisite: you must have created an SMS notification campaign in XPKit Portal that we can use in the following rule.

{
    "name": "Play VR game queue",
    "queue_id": "play-vr-game-queue",
    "experience_id": "developer-conference-2022",
    "rules": [
        {
            "action": "send_notification",
            "action_field": "status",
            "action_value": "call",
            "action_identifier": "you-are-up-next"
        }
    ]
}

This rule will send the you-are-up-next notification campaign when the visitor's status in the queue has changed to call.

Keeping the queue tidy

Let's assume Sarah has already left the experience by the time she is called to play. We can update the queue with an additional cancel rule like so:

{
    "name": "Play VR game queue",
    "queue_id": "play-vr-game-queue",
    "experience_id": "developer-conference-2022",
    "rules": [
        {
            "action": "send_notification",
            "action_field": "status",
            "action_value": "call",
            "action_identifier": "you-are-up-next"
        },
        {
            "action": "cancel_item",
            "action_field": "status",
            "action_value": "call",
            "action_identifier": "3600"
        }
    ]
}

This means that 1 hour (3600 seconds) after being notified if the host does not update the visitor's status (to say play) they will be automatically removed from the queue.

Monitoring the queue

The host will probably want to see everyone in the queue and monitor the state at a glance. Maybe they need to repriortise a (VIP) guest or manually remove someone if they come back and say they are no longer interested in playing.

Your web app can listen for real time changes via a websocket connection. This is especially handy if there are multiple hosts and they all need to be notified when something changes. The flow would be:

1. Web app either adds (POST) or updates (PUT / PATCH) a queueitem using the XPKit endpoints
2. XPKit updates the queue
3. XPKit broadcasts the changed queueitem to tablet(s) listening for changes on that specific queue

JavaScript connection example:

const websocket = new WebSocket("wss://queues-status.emea.xpkit.net/<account-id>/play-vr-game-queue");
websocket.onmessage = function (event) {
    let data = JSON.parse(event.data);
    let queue_item = data.resource;
    console.log(`The priority for this queue item is ${queue_item.priority}`)
};