Documentation for how to use deep linking with Electron

[coreyjv]

Is your feature request related to a problem? Please describe.

Please publish documentation on how to use deep linking with Electron. My expectation is that I'd be able to provide the custom protocol to Electron which would subsequently be registered in a fashion like: app.setAsDefaultProtocolClient('com.domain.for.my.app').

Describe the solution you'd like

I'd like to understand how to use deep linking with Electron. My expectation is that I can use the addListener('appUrlOpen' model like we can on iOS and Android

import { Plugins } from "@capacitor/core";

const { App } = Plugins;

App.addListener('appUrlOpen', (data: any) => {
   console.log('App Open', data)
})

[IT-MikeS]

In your capacitor.config.json you set the server.hostname to the protocol you want to use as your custom one (myapp for example) then in the electron/src/index.ts file you pass the deepLinking.useDeeplinking into the createCapacitorElectronApp()

const myCapacitorApp = createCapacitorElectronApp({
  deepLinking: {
    useDeeplinking: true,
  }
});

Thats all the setup, after you just use the plugin as normal. Do note that you must at least package or build and run the electron app before it will work properly.

This way of doing config for the platform will be changed with Capacitor 3+ with the introduction of plugins using the config file (capacitor.config.json) ionic-team/capacitor#3141

[coreyjv]

Are their any side effects of using that value in the configuration for mobile and web parts of Capacitor?

https://capacitorjs.com/docs/basics/configuring-your-app

Will that issue you referenced result in not having to modify the index.ts file in the future?

[IT-MikeS]

Not that I am aware of but it would probably better to have the config live with the other config in the index.ts at the moment, I'll probably move it.

In the future I am thinking of having an electron key in the config file which will house some config, such as static values like whether or not to use the splash screen, but at the moment its just an idea and no guarantee it will actually move.

[IT-MikeS]

Addressed in #37

[coreyjv]

@IT-MikeS -- With the merge of #37 is it accurate to say that I would change electron/src/index.ts to be:

const myCapacitorApp = createCapacitorElectronApp({
  deepLinking: {
    customProtocol: "com.domain.for.my.app",
  }
});

[coreyjv]

It also looks like when applying the original configuration suggested above the Electron app doesn't start.

[IT-MikeS]

@IT-MikeS -- With the merge of #37 is it accurate to say that I would change electron/src/index.ts to be:

const myCapacitorApp = createCapacitorElectronApp({
  deepLinking: {
    customProtocol: "com.domain.for.my.app",
  }
});

Yes however you shouldnt use something like com.example.myapp, the idea is to use whatever the browser will read. So for example I set the customProtocol to myawesomeapp, when you enter the url myawesomeapp://somedatatobepassedin the browser will look for the app on your computer associated with the protocol myawesomeapp then send through the url to that app where its parsed by capacitor. You can use listeners at this point or define a on cold start function.

[coreyjv]

@IT-MikeS -- With the latest version of @capacitor-community/electron this still doesn't work for me. The app is brought to focus but the appUrlOpen listener is not called. What I've done is added the code below to my index.tsx of my web app:

import { Plugins } from "@capacitor/core";

const { App } = Plugins;

App.addListener('appUrlOpen', (data: any) => {
   console.log('App Open', data)
})

Modified the electron/src/index.ts like so:

const myCapacitorApp = createCapacitorElectronApp({
  deepLinking: {
    customProtocol: "myprotocol"
  }
});

The capacitor.config.json is unchanged because my understanding was that with this move we didn't need to use the server.hostname any longer.

What am I doing wrong?

[IT-MikeS]

Did you build the electron app then run the built app atleast once? Deeplinking with electron doesnt work if you just run in dev mode ie: npm run electron:start

I just ran through it here using the URL: myprotocol://test-data and I got console log of {url: 'myprotocol://test-data'}

[coreyjv]

@IT-MikeS -- I tried running npm run electron:build-mac and even when installing and using that app the deep link only brought the app to focus and it didn't run the listener I setup with appUrlOpen.

Would you be willing to publish your sample so I can take a look? Also it may be worth noting that the project I'm working with is a React-based Ionic project.

[IT-MikeS]

Here is what I did with an ionic react app. https://github.com/IT-MikeS/test-cap-electron-deeplinking

Do note I tested on my windows machine. I can test on my mac later but I'm not near it at the moment

[coreyjv]

It seems that it is broken on Mac. If you remove the will-finish-launching wrapper it works great: https://github.com/capacitor-community/electron/blob/main/packages/core/src/electron/ElectronDeepLinking.ts#L72

My suspicion is that the will-finish-launching event has already fired prior to this code being run.

[IT-MikeS]

I will run some tests tomorrow on my mac and see what i can do, thank your for investigating👍

[coreyjv]

@IT-MikeS -- Thank you. I'd be more than happy to submit a PR to remove that wrapping will-finish-launching wrapper.

[IT-MikeS]

You're welcome to, I just want to make sure that it doesn't break deeplinks on windows or Linux

[coreyjv]

That's fair. Let me know!

[IT-MikeS]

This is the new pattern for using deeplinking within electron.

import { app } from "electron";
import { createCapacitorElectronApp, createCapacitorElectronDeepinking } from "@capacitor-community/electron-core";


// The MainWindow object can be accessed via myCapacitorApp.getMainWindow()
const myCapacitorApp = createCapacitorElectronApp();

createCapacitorElectronDeepinking(myCapacitorApp, {
  customProtocol: 'proto'
});

// This method will be called when Electron has finished
// initialization and is ready to create browser windows.
// Some Electron APIs can only be used after this event occurs.
app.on("ready", () => {
  myCapacitorApp.init();
});

// Quit when all windows are closed.
app.on("window-all-closed", function () {
  // On OS X it is common for applications and their menu bar
  // to stay active until the user quits explicitly with Cmd + Q
  if (process.platform !== "darwin") {
    app.quit();
  }
});

app.on("activate", function () {
  // On OS X it's common to re-create a window in the app when the
  // dock icon is clicked and there are no other windows open.
  if(myCapacitorApp.getMainWindow().isDestroyed())
    myCapacitorApp.init();
});

// Define any IPC or other custom functionality below here

[coreyjv]

@IT-MikeS --

Thank you! When can I expect a version with these changes to be available?

[IT-MikeS]

I will release a new version to npm today

[IT-MikeS]

Sorry for the delay, but I have just push a new version to npm

[IT-MikeS]

Made a quick documentation of the new deeplinking on the docs site.

https://capacitor-community-electron-docs-site.vercel.app/usage/deeplinking/