AdvancedSockets aims to help handling connectivity issues from the client side when using ColdFusion's WebSockets.
Below is a simple example of how to implement. The data attributes defined in the body are the default values and do not have to be set but can be overridden. For more information on how and where they are set refer to the Attributes / Properties section.
<body data-auto-connect = "true"
data-name = "ws"
data-channels = "channelname"
data-debug = "true"
data-do-message = "doMessage"
data-online-timer = "30"
data-offline-timer = "5"
data-reconnect-timer = ".5"
data-ping-url = "/ping/">
<div id="status-message"></div>
<cfwebsocket name = "ws"
onMessage = "AdvancedSocket.onMessage"
onOpen = "AdvancedSocket.onOpen"
onClose = "AdvancedSocket.onClose"
onError = "AdvancedSocket.onError">
<script src="dist/advancedsocket.min.js"></script>
<script>
function doMessage( obj ){
console.log( obj );
}
</script>
</body>
- autoConnect
Controls the auto connect feature of the AdvancedSocket.
Defaults totrue
but can be managed by thedata-auto-connect
attribute in the body tag. It also requires a pingURL to be defined. - ipApiLookup
Controls the ip api lookup feature.
Defaults tofalse
but can be managed by thedata-api-lookup
attribute in the body tag. - ipApiService
The ip api service that is used when feature is enabled.
Defaults toip-api.com
but can be managed by thedata-api-service
attribute in the body tag. Please note, this only allows for either ip-api.com or ipapi.com. At the current moment ip-api.com does not require a key as HTTPS calls are not enabled. Once we support this feature, then an API Key will be required. ipapi.com does allow for HTTPS requests.
Important
Please review the sites for these services for more information.
- ipApiKey
The api key for the ip api service.
Can be managed by thedata-api-key
attribute in the body tag. Currently, this is only required for ipapi.com. - name
The name of your global websocket variable name.
Defaults tows
but can be managed by thedata-name
attribute in the body tag. - channels
Comma separated list of channels to subscribe to.
Managed by thedata-channels
attribute in the body tag. - clientID
The subscriber ID returned from ColdFusion on a succesful connection. This is used when the autoConnect feature is enabled to make sure that we are still an active subscriber. - clientInfo
This is a key-value object that is passed when creating a connection. By default AdvancedSocket uses a third party request to find out additional geo-based data of the request. This is also used to pass in a username and any additional info you may want to. - doMessage
Defines the global function to run on a succesful message. Defaults todoMessage
. If the function is not defined or does not exists a log message will be displayed (if debug is enabled).
Defaults todoMessage
but can be managed by thedata-do-message
attribute in the body tag. - timer
Used for the check AdvancedSocket.checkConnection setTimeout - pingURL
The URL that will be used to ping if we are still a good connection. Should return a JSON object with a success value of true or false.
Managed by thedata-ping-url
attribute in the body tag. - onlineTimer
The timeout value to ping if autoConnect is enabled while we have a good connection.
Defaults to30 seconds
but can be managed by thedata-online-timer
attribute in the body tag. - offlineTimer
The timeout value to ping if autoConnect is enabled while we have a bad connection.
Defaults to5 seconds
but can be managed by thedata-offline-timer
attribute in the body tag. - reconnectTimer
The timeout value call a reconnect attempt when aFORCE-RECONNECT
value is received from the server.
Defaults to500ms
but can be managed by thedata-reconnect-timer
attribute in the body tag. - timerCount
The timeout value that is used on reconnect calls. It is automally updated to either the online or offline value based on current state. - debug
Boolean value to display log messages.
Defaults tofalse
but can be managed by thedata-debug
attribute in the body tag. - statusLabel
The status document element defined by an id of status-message.
Defaults tostatus-message
but can be managed by thedata-status-label
attribute in the body tag.
- init
Initializes theAdvancedSocket
with options defined in the body's data attributes. - checkConnection
Sets up timer and request firstping()
call ifautoConnect
is enabled. - dispatchEvent
Creates and dispatches custom events. - forceReconnect
Fired when a FORCE-RECONNECT message is received and executesCFWebSocketWrapper.closeConnection()
andCFWebSocketWrapper.openConnection()
which executeonOpen()
when the socket is open again. - getIPInfo
Calls the IP API Service if enabled and adds the result to the subscribers information on connection underclientInfo.geo
. - handleConnectionError
Handles a connection error event. - handleGoodConnection
Handles a good connection event. - handleRequireConnection
Handles a require connection event. - handleOffline
Handles an offline event. - handleOnline
Handles an online event. - ping
Polls request to the server to check if connection is still valid. Expects anapplication/json
response as follows:
{ "success" : true|false }
- processAuthentication Handles an authentication request and logs error or continues on success.
- processMessage
OnFORCE-RECONNECT
messages fires theforceReconnect()
based on thereconnectCount
and forwards the message to the Global Function defined in the options. - setTimer
Handles setting the timer that fires off the check connection event usingwindow.setTimeout
- setupListeners
Handles setting the listeners for connection events. - subscribe
Loops thru the defined channels and executes theCFWebSocketWrapper.subscribe()
function for each. - onClose [ executed from
CFWebSocketWrapper
]
Fired on connection close - onError [ executed from
CFWebSocketWrapper
]
Fired on connection errors - onMessage [ executed from
CFWebSocketWrapper
]
Handles messages received and routes based onreqType
. If none match, it routes toprocessMessage()
.welcome
Sets clientID and executesconnecting()
authenticate
ExecutesprocessAuthentication()
subscribe
Executesconnected()
- onOpen [ executed from
CFWebSocketWrapper
]
Fired onced the connection is open. If authentication is required, it calls theCFWebSocketWrapper.authenticate()
function if not passes to thegetIPInfo()
if feature enabled orsubscribe()
if not. - disconnected 🤘 (overwrite to customize)
Fired when a socket is disconnected. Updates the status label. - connecting 🤘 (overwrite to customize)
Fired when the socket is connecting. Updates the status label. - connected 🤘 (overwrite to customize)
Fired when the socket is connected. Updates the status label. - doLog
Outputs console logs if debug is set to true. This can be defined with the body data-debug attribute.