Technical Requirements
This page describes what SmartSub needs from a computer, browser, and network to work properly. It is written for district and school IT staff, but anyone troubleshooting a connection problem may find it useful.
Table of Contents
Browsers
SmartSub runs in any current version of these browsers:
- Chrome (recommended)
- Edge
- Firefox
- Safari, including Safari on iPhone and iPad
The browser must allow the following for SmartSub:
| Feature | Why SmartSub needs it |
|---|---|
| JavaScript | SmartSub's pages are interactive and do not work with JavaScript turned off. |
| Cookies | Keep you signed in. SmartSub only uses its own cookies; third-party cookies are not required. |
| Local storage | Remembers page settings such as grid layouts, and remembers how your browser connects to SmartSub (see Automatic fallback). |
Keep your browser up to date. Older versions may be missing features SmartSub relies on.
Network Access
Computers that use SmartSub need HTTPS (port 443) access to the following addresses:
| Address | Used for | Needed by |
|---|---|---|
smartsub.com and www.smartsub.com |
The SmartSub web application, including its WebSocket connection | Everyone |
accounts.google.com |
Sign in with Google | Users who sign in with Google |
login.microsoftonline.com |
Sign in with Microsoft | Users who sign in with Microsoft |
appleid.apple.com |
Sign in with Apple | Users who sign in with Apple |
api.smartsub.com |
SmartSub's API for system integrations | Only systems that integrate with SmartSub, not web browsers |
WebSockets
What they are
Most websites work by having the browser ask for a page, receive it, and then disconnect. SmartSub keeps a connection open between your browser and our server while you use it. This lets the page update immediately when you click, type, or when something changes on the server, such as a substitute accepting an opening.
That open connection uses a standard technology called WebSockets. It runs over the same secure HTTPS port (443) as the rest of the site, at this address:
wss://smartsub.com/_blazor
What happens when WebSockets are blocked
Some web filters, firewalls, and HTTPS (SSL) inspection tools block WebSocket connections or interfere with them, while still allowing ordinary web pages through. When that happens:
- You can sign in, but the page then stays on the "Loading..." screen.
- After a short wait, SmartSub may show "SmartSub can't finish loading."
- The same account usually works on a phone or on a different network, because those connections do not pass through the same filter.
Automatic fallback
If your browser cannot connect over WebSockets within a few seconds, SmartSub automatically reloads the page and connects a different way, called Long Polling, which uses ordinary web requests instead of an open connection. Your browser remembers this for 24 hours, so later pages load directly without the wait. After that it tries WebSockets again, in case the network has been fixed.
Long Polling works, but it is noticeably slower. Pages take longer to load and respond, so it should be treated as a temporary workaround, not a solution. If you see "SmartSub can't finish loading", Long Polling did not work either, and the network needs to be fixed.
How IT staff can confirm the problem
- On an affected computer, open SmartSub and sign in.
- While the page is on "Loading...", press F12 to open the browser's developer tools and select the Console tab.
-
Look for a message like:
WebSocket connection to 'wss://smartsub.com/_blazor?id=...' failedThat message means the WebSocket connection is being blocked.
-
As a second check, connect the same computer to a different network, such as a phone hotspot, and try again:
- If SmartSub loads normally, the block is on the network (for example, a web filter or firewall).
- If it still fails, the block is coming from software installed on the computer (for example, a security agent or a browser extension managed by your district).
How to fix it
Allow the following for smartsub.com and www.smartsub.com:
- WebSocket connections (
wss://). - An exemption from HTTPS/SSL inspection, if your filter or firewall performs inspection.
Allowing SmartSub in a content filter is often not enough on its own. HTTPS inspection in particular commonly breaks WebSocket connections and usually needs to be bypassed for them to work reliably.
Checklist for IT Staff
- HTTPS (port 443) is allowed to
smartsub.comandwww.smartsub.com. - WebSocket connections (
wss://) are allowed tosmartsub.comandwww.smartsub.com. smartsub.comandwww.smartsub.comare exempt from HTTPS/SSL inspection.- The sign-in provider your users use (Google, Microsoft, or Apple) is reachable.
- Browsers are current and allow JavaScript, cookies, and local storage for SmartSub.
Getting Help
If SmartSub still does not load after checking the items above, contact SmartSub support and include:
- The date and time of the problem, and your time zone
- The browser and device being used
- Whether the problem happens on other networks, such as a phone hotspot
- Any messages shown in the browser's Console tab
For other common questions, see the FAQ.