Deep Links

    By the end of this tutorial, we will have set our app to intercept and handle any clicked URLs that start with a specific protocol. In this guide, the protocol we will use will be ““.

    First, we will import the required modules from electron. These modules help control our application lifecycle and create a native browser window.

    Next, we will proceed to register our application to handle all “electron-fiddle://“ protocols.

    1. if (process.defaultApp) {
    2.   if (process.argv.length >= 2) {
    3.     app.setAsDefaultProtocolClient('electron-fiddle', process.execPath, [path.resolve(process.argv[1])])
    4.   }
    5. } else {
    6.   app.setAsDefaultProtocolClient('electron-fiddle')
    7. }

    We will now define the function in charge of creating our browser window and load our application’s index.html file.

    1. const createWindow = () => {
    2.   // Create the browser window.
    3.   mainWindow = new BrowserWindow({
    4.     width: 800,
    5.     height: 600,
    6.     webPreferences: {
    7.       preload: path.join(__dirname, 'preload.js')
    8.     }
    9.   })
    11.   mainWindow.loadFile('index.html')
    12. }

    This code will be different in Windows compared to MacOS and Linux. This is due to Windows requiring additional code in order to open the contents of the protocol link within the same Electron instance. Read more about this .

    Windows code:

    1. const gotTheLock = app.requestSingleInstanceLock()
    3. if (!gotTheLock) {
    4.   app.quit()
    5. } else {
    6.   app.on('second-instance', (event, commandLine, workingDirectory) => {
    7.     // Someone tried to run a second instance, we should focus our window.
    8.     if (mainWindow) {
    9.       if (mainWindow.isMinimized()) mainWindow.restore()
    10.       mainWindow.focus()
    11.     }
    12.     // the commandLine is array of strings in which last element is deep link url
    13.     // the url str ends with /
    14.     dialog.showErrorBox('Welcome Back', `You arrived from: ${commandLine.pop().slice(0, -1)}`)
    15.   })
    17.   // Create mainWindow, load the rest of the app, etc...
    18.   app.whenReady().then(() => {
    19.     createWindow()
    20.   })
    21. }

    MacOS and Linux code:

    Finally, we will add some additional code to handle when someone closes our application.

    1. // Quit when all windows are closed, except on macOS. There, it's common
    2. // for applications and their menu bar to stay active until the user quits
    3. // explicitly with Cmd + Q.
    4. app.on('window-all-closed', () => {
    5.   if (process.platform !== 'darwin') app.quit()
    6. })

    Packaging

    On macOS and Linux, this feature will only work when your app is packaged. It will not work when you’re launching it in development from the command-line. When you package your app you’ll need to make sure the macOS Info.plist and the Linux .desktop files for the app are updated to include the new protocol handler. Some of the Electron tools for bundling and distributing apps handle this for you.

    If you’re using Electron Forge, adjust packagerConfig for macOS support, and the configuration for the appropriate Linux makers for Linux support, in your Forge configuration (please note the following example only shows the bare minimum needed to add the configuration changes):

    1. {
    2.   "config": {
    3.     "forge": {
    4.       "packagerConfig": {
    5.         "protocols": [
    6.           {
    7.             "name": "Electron Fiddle",
    8.             "schemes": ["electron-fiddle"]
    9.           }
    10.         ]
    11.       },
    12.       "makers": [
    13.         {
    14.           "name": "@electron-forge/maker-deb",
    15.           "config": {
    16.             "mimeType": ["x-scheme-handler/electron-fiddle"]
    17.           }
    18.         }
    19.       ]
    20.     }
    21.   }
    22. }

    Electron Packager

    If you’re using Electron Packager’s API, adding support for protocol handlers is similar to how Electron Forge is handled, except protocols is part of the Packager options passed to the packager function.

    1. const packager = require('electron-packager')
    3. packager({
    4.   // ...other options...
    5.   protocols: [
    6.       name: 'Electron Fiddle',
    7.       schemes: ['electron-fiddle']
    8.     }
    9.   ]
    11. }).then(paths => console.log(`SUCCESS: Created ${paths.join(', ')}`))
    12.   .catch(err => console.error(`ERROR: ${err.message}`))

    If you’re using Electron Packager’s CLI, use the --protocol and --protocol-name flags. For example:

    After you start your Electron app, you can enter in a URL in your browser that contains the custom protocol, for example "electron-fiddle://open" and observe that the application will respond and show an error dialog box.

    docs/fiddles/system/protocol-handler/launch-app-from-URL-in-another-app (23.0.0)

    • main.js
    • preload.js
    • index.html
    • renderer.js
    1. // Modules to control application life and create native browser window
    2. const { app, BrowserWindow, ipcMain, shell, dialog } = require('electron')
    3. const path = require('path')
    5. let mainWindow;
    7. if (process.defaultApp) {
    8.   if (process.argv.length >= 2) {
    9.     app.setAsDefaultProtocolClient('electron-fiddle', process.execPath, [path.resolve(process.argv[1])])
    10.   }
    11. } else {
    12.     app.setAsDefaultProtocolClient('electron-fiddle')
    13. }
    15. const gotTheLock = app.requestSingleInstanceLock()
    17. if (!gotTheLock) {
    18.   app.quit()
    19. } else {
    20.   app.on('second-instance', (event, commandLine, workingDirectory) => {
    21.     // Someone tried to run a second instance, we should focus our window.
    22.     if (mainWindow) {
    23.       if (mainWindow.isMinimized()) mainWindow.restore()
    24.       mainWindow.focus()
    25.     }
    27.     dialog.showErrorBox('Welcome Back', `You arrived from: ${commandLine.pop().slice(0,-1)}`)
    28.   })
    30.   // Create mainWindow, load the rest of the app, etc...
    31.   app.whenReady().then(() => {
    32.     createWindow()
    33.   })
    35.   app.on('open-url', (event, url) => {
    36.     dialog.showErrorBox('Welcome Back', `You arrived from: ${url}`)
    37.   })
    38. }
    40. function createWindow () {
    41.   // Create the browser window.
    42.   mainWindow = new BrowserWindow({
    43.     width: 800,
    44.     height: 600,
    45.     webPreferences: {
    46.       preload: path.join(__dirname, 'preload.js'),
    47.     }
    48.   })
    50.   mainWindow.loadFile('index.html')
    51. }
    53. // Quit when all windows are closed, except on macOS. There, it's common
    54. // for applications and their menu bar to stay active until the user quits
    55. // explicitly with Cmd + Q.
    56. app.on('window-all-closed', function () {
    57.   if (process.platform !== 'darwin') app.quit()
    58. })
    60. // Handle window controls via IPC
    61. ipcMain.on('shell:open', () => {
    62.   const pageDirectory = __dirname.replace('app.asar', 'app.asar.unpacked')
    63.   const pagePath = path.join('file://', pageDirectory, 'index.html')
    64.   shell.openExternal(pagePath)
    65. })
    1. // All of the Node.js APIs are available in the preload process.
    2. // It has the same sandbox as a Chrome extension.
    3. const { contextBridge, ipcRenderer } = require('electron')
    5. // Set up context bridge between the renderer process and the main process
    6. contextBridge.exposeInMainWorld(
    7.   'shell',
    8.     open: () => ipcRenderer.send('shell:open'),
    9.   }
    10. )
    1. <!DOCTYPE html>
    2. <html>
    4. <head>
    5.   <meta charset="UTF-8">
    6.   <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
    7.   <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
    8.   <meta http-equiv="X-Content-Security-Policy" content="default-src 'self'; script-src 'self'">
    9.   <title>app.setAsDefaultProtocol Demo</title>
    10. </head>
    12. <body>
    13.   <h1>App Default Protocol Demo</h1>
    15.   <p>The protocol API allows us to register a custom protocol and intercept existing protocol requests.</p>
    16.   <p>These methods allow you to set and unset the protocols your app should be the default app for. Similar to when a
    17.     browser asks to be your default for viewing web pages.</p>
    19.   <p>Open the <a href="https://www.electronjs.org/docs/api/protocol">full protocol API documentation</a> in your
    20.     browser.</p>
    22.   -----
    24.   <h3>Demo</h3>
    25.   <p>
    26.     First: Launch current page in browser
    27.     <button id="open-in-browser" class="js-container-target demo-toggle-button">
    28.         Click to Launch Browser
    29.       </button>
    30.   </p>
    32.   <p>
    33.     Then: Launch the app from a web link!
    34.     <a href="electron-fiddle://open">Click here to launch the app</a>
    35.   </p>
    37.   ----
    39.   <p>You can set your app as the default app to open for a specific protocol. For instance, in this demo we set this app
    40.     as the default for <code>electron-fiddle://</code>. The demo button above will launch a page in your default
    41.     browser with a link. Click that link and it will re-launch this app.</p>
    44.   <h3>Packaging</h3>
    45.   <p>This feature will only work on macOS when your app is packaged. It will not work when you're launching it in
    46.     development from the command-line. When you package your app you'll need to make sure the macOS <code>plist</code>
    47.     for the app is updated to include the new protocol handler. If you're using <code>electron-packager</code> then you
    48.     can add the flag <code>--extend-info</code> with a path to the <code>plist</code> you've created. The one for this
    49.     app is below:</p>
    51.   <p>
    52.   <h5>macOS plist</h5>
    53.   <pre><code>
    54.     &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    55.     &lt;!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"&gt;
    56.             &lt;plist version="1.0"&gt;
    57.                 &lt;dict&gt;
    58.                     &lt;key&gt;CFBundleURLTypes&lt;/key&gt;
    59.                     &lt;array&gt;
    60.                         &lt;dict&gt;
    61.                             &lt;key&gt;CFBundleURLSchemes&lt;/key&gt;
    62.                             &lt;array&gt;
    63.                                 &lt;string&gt;electron-api-demos&lt;/string&gt;
    64.                             &lt;/array&gt;
    65.                             &lt;key&gt;CFBundleURLName&lt;/key&gt;
    66.                             &lt;string&gt;Electron API Demos Protocol&lt;/string&gt;
    67.                         &lt;/dict&gt;
    68.                     &lt;/array&gt;
    69.                     &lt;key&gt;ElectronTeamID&lt;/key&gt;
    70.                     &lt;string&gt;VEKTX9H2N7&lt;/string&gt;
    71.                 &lt;/dict&gt;
    72.             &lt;/plist&gt;
    73.         </code>
    74.     </pre>
    75.   <p>
    77.     <!-- You can also require other files to run in this process -->
    78.     <script src="./renderer.js"></script>
    79. </body>