Writing · JavaScript · Discord · Browsers
Opening the Discord app from a web page without opening the website too
An "Open in Discord" button should launch the app or the website, not both. The discord:// race, cold starts on Windows, and each browser's popup limits.
After you post a message with DWEEB, the confirmation has an Open in Discord button. The ideal behaviour is simple to state: if the Discord desktop app is installed, open the message there; if not, open it on discord.com in a new tab. Browsers give you no direct way to ask whether an app is installed, so every implementation of this is a race. Mine shipped with a bug that opened both, and fixing it meant learning how long each browser lets a click stay "a click".
The race
The approach most sites use:
- On click, navigate to the app's URL scheme, here
discord://-/channels/{guild}/{channel}/{message}. - If the app is installed, the operating system hands the link to it, and the browser window loses focus as the app comes to the front.
- If the page still has focus after a grace period, assume nothing handled the link and open the web URL.
let cancelPending = null;
export function openInDiscord(appUrl, webUrl) {
cancelPending?.(); // a repeat click replaces the previous race
let appTookOver = false;
const onHide = () => { appTookOver = true; };
const onVisibility = () => { if (document.hidden) appTookOver = true; };
window.addEventListener("blur", onHide);
document.addEventListener("visibilitychange", onVisibility);
const timer = setTimeout(() => {
cleanup();
if (!appTookOver && document.hasFocus()) window.open(webUrl, "_blank", "noopener");
}, graceMs());
function cleanup() {
clearTimeout(timer);
window.removeEventListener("blur", onHide);
document.removeEventListener("visibilitychange", onVisibility);
cancelPending = null;
}
cancelPending = cleanup;
window.location.href = appUrl;
}
Note that the test is "the page kept focus for the whole window", not "the page has focus when the timer fires". A blur at any point, even if focus comes back before the timer, means the app took over. The visibility check covers platforms where the page is hidden rather than blurred.
The bug: 800 milliseconds
The first version used an 800 ms grace period. It felt responsive in testing, on a machine where Discord was already running. On Windows, with the browser set to always allow discord:// links without asking, a Discord client that is starting cold regularly takes more than 800 ms to come to the front. The timer fired first, the web tab opened, and a moment later the app appeared as well. People got two copies of their message on screen and reasonably assumed the button was broken.
A longer window fixes it, but there's a hard limit on how long the window can be, and it's different in every browser.
The constraint: user activation
Browsers only allow window.open as a direct result of a user action. The HTML standard calls this transient user activation: a click grants it, and it expires after a browser-defined interval. Open a window after it expires and the popup blocker stops you. The fallback runs from a timer, so the grace period has to end while the click's activation is still valid.
| Engine | What allows the delayed open | Grace period I use |
|---|---|---|
| Chromium (Chrome, Edge…) | Transient activation lasts about 5 seconds | 2,500 ms |
| Firefox | Transient activation lasts about 5 seconds by default | 2,500 ms |
| Safari (WebKit) | Passes a click's activation through setTimeout only for delays up to 1 second | at most 1,000 ms |
On Chromium and Firefox, 2.5 seconds comfortably covers a cold app start and stays well inside the activation window. On Safari, a longer delay doesn't just fail quietly: a blocked popup there can turn into navigating the current tab to the web URL, which would take the person away from the page they were on. So Safari keeps a window of one second or less, and accepts that a very slow app start may occasionally open both.
function graceMs() {
// WebKit only forwards user activation through timers of <= 1s.
return isWebKit() ? 1000 : 2500;
}
Repeat clicks
Someone who clicks, sees nothing for a second and clicks again would, with a naïve implementation, start a second race and possibly get two fallback tabs. A module-level cancel function (cancelPending above) makes each click supersede the previous one instead of stacking.
Testing it
The behaviour depends on timing and focus, which unit tests handle well with fake timers. My test file covers the cases that matter: app takes over (blur before the deadline, so no web tab), app absent (focus held, so a web tab opens), blur then refocus inside the window (still counts as the app), a repeat click (one race, not two), and the per-engine grace periods. The file's comments explain why the numbers are what they are. It's the kind of constant someone will want to "tighten for snappiness" in a year, and the test is there to stop them.
Summary
- A custom-scheme deep link with a web fallback is always a race. Detect the app by focus loss during the whole window.
- Size the window for a cold app start, not a warm one. 800 ms was too short on Windows.
- Stay inside each engine's user-activation window: about 5 s for Chromium and Firefox, 1 s for timers in Safari.
- Let repeat clicks cancel the previous race.
