OpenIn 4
Documentation - 02. Browsers
Table of content
Enabled
If you aren’t planning to use OpenIn for handling Web links on your Mac, you can disable it completely, so OpenIn will not try to check if other apps are set as default for handling Web links.
Applications
Remove all applications
OpenIn automatically discovers applications that can handle Web links on your system. You can remove all applications and rebuild the list on your own.
Add application…
OpenIn shows a dialog with all the applications that can handle Web links found on your system, if you are planning to rewrite the URL to a different scheme you can browse for other applications in your system.
Select applications from the Add applications list and press Add to add them to the list of the applications for the Web Links.
You can add the same application more than once, that helps for example to configure them differently. For example, you can add Safari twice. One to open normally, second one to open in Private Mode.
Order of the applications
OpenIn uses the defined order of the applications, when it shows the App Selection menu, when you click the link.
You can change the order by dragging applications by ≋
.
Edit application
Based on the type of the Browser or application, you might see slightly different configurations.
- Name - you can give any name to the application, it does not change the name of the app on the system.
- Icon overlay - you can add an icon overlay, this is useful if you, for example, add the same browser or application with different configurations
Safari and Firefox Private Mode
You can use Safari and Firefox Private Mode in SetApp distribution of the application, or if you have OpenIn Helper installed for App Store version.
For Safari.app and Safari Technology Preview.app you can enable Private Mode. Safari does not have API for us to send link to Private Window, so we need to use Accessibility features of MacOS.
For Firefox.app and Firefox Developer Preview.app you can enable Private Mode. OpenIn will send the links using
Contents/MacOS/firefox
cli tool from the distribution of this browser.
Safari Profiles
You can use Safari Profiles in SetApp distribution of the application, or if you have OpenIn Helper installed for App Store version. There are two configurations you need to do to use Safari Profiles. One is to set the Profile Name, and second is to set the Profile Number. 0 is the default profile number, and number 1 would be the first created profile. Please read the blog post How OpenIn can help you to work with Safari Profiles.
Chromium profiles
You can use Chromium Profiles in SetApp distribution of the application, or if you have OpenIn Helper installed for App Store version.
Chromium profiles available for browsers that are built on Chromium engine (Chrome, Brave, etc), and support multiple profiles.
You can select Use profile to start using profiles. Instead of launching browser as is, OpenIn will launch it via command line with the configured profile.
We use command line options to start Chromium browser based on its source code. To launch it with specific profile we supply
--profile-directory=...
, and to start it in incognito, we add--incognito
If you decided to use profiles, make sure to input correct name of the profile directory. Open this browser under profile
you want to use, open page chrome://version
and copy the last part of Profile Path, usually it will be Default, Profile 1, Profile 2, etc
You can also configure it to launch in Incognito mode.
Some other applications are parsing that directory to discover profiles. OpenIn will never do that, as under each Profile folder you will find a
README
file with content Google Chrome settings and storage represent user-selected preferences and information and MUST not be extracted, overwritten or modified except through Google Chrome defined APIs.
Troubleshooting Chromium Profiles
Sometimes Chromium profiles can be corrupted, which causes weird issues with the opening browsers with specific profiles.
You can test how Chromium browser behaves with the following command in Terminal (modify the Profile Name to the one
selected, and you can add --incognito
before the --profile-directory
)
open -a 'Google Chrome.app' --new --args \
--profile-directory='Default' https://apple.com
If this command behaves not how you expect, you might want to recreate your profiles. Double-check the profile names.
URL Rewrite
If you have added application that does not support http(s)://
scheme, you need to rewrite the URL to a supported
scheme. You will see a warning if you aren’t rewriting URL, and OpenIn discovered that editing application does not
support http(s)://
scheme.
Rewriting with Regular Expressions
You can modify the URL using Regular Expression. For example, for music.apple.com URLs you can try sending them to Music.app by using the following expression
- Expression -
https://(.*)
- Substitution -
music://$1
Where we replace scheme from https
to music
.
Rewriting with Scripts
You can also rewrite URLs with JavaScript, if you select Script. After selecting script you can open script editor with Edit script… button.
Script Editor provides simple examples for how to rewrite URL scheme, similar to
url.protocol = "apollo"
For learning more about what objects are available, please read 07. JavaScript Editor for Apps.
Launch Configurations
You can configure how OpenIn launches the application
- New instance - Whether you want the system to launch a new instance of the app. For Chromium browsers to be able to open a URL in a specific profile, we always need to launch a new instance of the browser. The same for Safari In Private mode.
- Adds To Recent Items - Whether to add the app or documents to the Recent Items menu, if application supports that.
- Activates - Whether the system activates the app and brings it to the foreground. You can uncheck that to launch URL in background.
- Hides - Whether you want the app to hide itself after it launches.
- Hides Others - Whether you want to hide all apps except the one that launched.
Rules
Rules help you to organize how OpenIn uses selected applications. If no rules are defined, it will show the selected apps in the App Selection menu, when you click the link. Similar if no rules match conditions, OpenIn will just show the list of the applications from above.
In the list you can edit or remove rules.
Order of the rules
Order of the rules matters. OpenIn goes from first rule of the list to next one, and verifying if the conditions are met.
The first that matches conditions will be executed. You can change the order of the rules by dragging ≋
.
Edit rule
You can configure the Name of the Rule to help you identify it. If you aren’t satisfied with the rule yet, you can Disable it, while trying to figure out what works best for you.
Conditions
You have several conditions to configure. If you have specified multiple conditions they will work as AND, except multiple domains matches and multiple sent from apps are executed as OR in those lists.
Execute only when
- With key Modifiers - you can configure this rule to execute only when those key modifiers are pressed, when you click the link.
- Launched from Share Extension or Services Menu - OpenIn provides Share extension or Services menu, if link is sent from it, this rule will be executed.
- Launched from Handoff - this rule will be executed only if you sent this link from other device with Handoff.
- Launched from AirDrop - this rule will be executed only if you send this link with the AirDrop.
NOTE: if you select all Share Extension, Handoff and AirDrop this rule will never be executed, as it is impossible to send a link that will match all of those conditions.
Execute only with Focus
OpenIn can be configured based on the selection of System Focus. OpenIn cannot read which focus is set, but you can configure Focus Hints parameters that you can use with the Focus editor in the System Settings. And when Focus Hint matches the one configured in the rule, this rule will be executed.
To learn more, please review Tutorial: Configuring rules based on the Focus selected in macOS system.
Execute only when Matches domains
You can add one or more domain matches. In case if you configured multiple domains just one of them needs to be matched.
Use *
for matching. If domain list is empty, rule matches any domain.
Examples:
example.com
matchesexample.com
andwww.example.com
, but notblog.example.com
*.example.com
matchesexample.com
,www.example.com
andblog.example.com
example.*
matchesexample.com
andexample.org
example.com/path/*
matchesexample.com/path/
andexample.com/path/path2
Execute only when Sent from apps
You can configure the to execute this rule only when link is sent from specific application. In case if you configured multiple applications in this list, just one of them needs to be matched. If list of apps is empty, rule matches any domain.
Use applications
You can configure how this Rule shows applications defined for in the list of Browsers.
- All - all applications from the list will be used
- All (running) - only running applications will be showed. If none of the applications are running, this rule is skipped.
- Selected - only applications that you have selected in the list will be used.
- Selected (running) - only running applications, that you have selected in the list will be used. If none of the applications are running, this rule will be skipped.
Custom script
You can define you custom JavaScript to change the URLs or select the browsers on your own custom condition.
For learning more about what objects are available, please read 08. JavaScript Editor for Rules.
Shortened URLs
URL shortening is a technique in which a URL may be made substantially shorter and still direct to the required page.
OpenIn can resolve the shortened URL, and it is required for OpenIn to run some domain specific rules. For example,
you might see a link as t.by/something
but it might actually redirect to https://apple.com/something...
. If you see
the link as t.by
, OpenIn will see it the same, so if you configured the Rule with matched domain apple.com
, it will
not work. That is why OpenIn at first might need to Resolve Shortened URLs from t.by
to apple.com
and after that run
the rules.
You can edit the list and add your own domains for which you want OpenIn to try to resolve where this URL goes.
By default, OpenIn imports the list of known Shortened Domains, but you can add your own as well.
Important details that OpenIn does not support not secure
http
links (onlyhttps
), that is another requirement of Sandboxed applications. It will try to just replacehttp
tohttps
, and try that. But if the domain expectshttp
only, OpenIn will fail to resolve the URL.
Troubleshooting shortened URLs
You can test in the Terminal how this URL behaves. If you run the curl
command you can check the output
curl -vL -o /dev/null https://bit.ly/3owmE4g
For this URL I will see
...
< HTTP/2 301
...
< location: https://t.co/wwG3nEJ69H?amp=1
...
< HTTP/2 301
...
< location: https://www.outcoldman.com/
...
...
< HTTP/2 200
...
So this example URL actually first redirects from bit.ly
to t.co
and after that to the final URL https://www.outcoldman.com/
Example: how author of OpenIn uses the OpenIn
The list of applications I have:
- Safari - standard Safari instance without any changes in the configurations.
- Safari - Safari instance with Lock* overlay icon, and Private Mode enabled.
- Chrome (OS) - Chrome browser configured with the work profile.
- Chrome (Personal) - Chrome browser configured with Personal profile.
- Chrome (Incognito) - Chrome browser configured with Personal profile in Incognito mode.
- Music - Music.app where I rewrite the URL with Regular Expression from
https://(.*)
tomusic://$1
- Apollo - Apollo (iOS) application where I rewrite URL with Script
url.protocol = "apollo"
- zoom.us - zoom application where I rewrite URL with Regular Expression from
https:\/\/([^.]+\.)?zoom\.us\/j\/(\d+)(\?(.*))
tozoommtg://$1zoom.us/join?confno=$2&$4
In the rules I have next set of rules
- reddit - where I have domains added
*.redditmail.com
and*.reddit.com
, and have Selected apps Safari and Apollo. So I can open Reddit links in Safari or Apollo. And in the script I have special case for*.redditmail.com
URLs, where I actually resolve the real reddit URL.
if (ctx.url.hostname.endsWith('redditmail.com')) {
ctx.url.href = decodeURIComponent(ctx.url.pathname.split("/", 3)[2])
}
- music.apple.com - matches domains
music.apple.com
and have only Music app selected - zoom - matches domains
*.zoom.us/j/*
and have only zoom.us app selected. - Cmd - With Key Modifiers ⌘ and Selected apps Safari, Safari (Private), Chrome (OS), Chrome (Personal), Chrome (Incognito).
- Default - My default rule with only one browser selected Safari.
For both rules Cmd and Default I also have Script defined as below, where I remove some tracking query params, and change amazon.com domain to smile.amazon.com
(function() {
let url = ctx.url
// remove tracking utm query
let keys = url.searchParams.keys()
keys.forEach(function (key) {
if (key.startsWith("utm_")
|| key.startsWith("uta_")) {
url.searchParams.delete(key)
}
})
// change amazon.com to smile.amazon.com
if (url.hostname == "amazon.com") {
url.hostname = "smile.amazon.com"
}
})()
With this configuration in most cases my links are opened in Safari, and when I press ⌘ I have the browser list selection.