diff --git a/src/content/docs/features/cli.mdx b/src/content/docs/features/cli.mdx index 3dee0c514f..ff35f6861f 100644 --- a/src/content/docs/features/cli.mdx +++ b/src/content/docs/features/cli.mdx @@ -210,6 +210,8 @@ The CLI plugin is available in both JavaScript and Rust. ```js +import { getMatches } from '@tauri-apps/plugin-cli'; + const matches = await getMatches(); if (matches.subcommand?.name === 'run') { // `./your-app run $ARGS` was executed diff --git a/src/content/docs/features/deep-linking.mdx b/src/content/docs/features/deep-linking.mdx index bada8cc4f1..98c8038d55 100644 --- a/src/content/docs/features/deep-linking.mdx +++ b/src/content/docs/features/deep-linking.mdx @@ -7,12 +7,214 @@ sidebar: variant: tip --- -import Stub from '@components/Stub.astro'; import PluginLinks from '@components/PluginLinks.astro'; +import { Tabs, TabItem } from '@astrojs/starlight/components'; +import CommandTabs from '@components/CommandTabs.astro'; - - Based on - https://github.com/tauri-apps/plugins-workspace/tree/v2/plugins/deep-link - +Set your Tauri application as the default handler for an URL. + +## Supported Platforms + +- Android +- iOS + +## Setup + +_This plugin requires a Rust version of at least **1.75**_ + +Install the deep-link plugin to get started. + + + + +Use your project's package manager to add the dependency: + +{' '} + + + + + + +1. Run `cargo add tauri-plugin-deep-link` to add the plugin to the project's dependencies in `Cargo.toml`. + +2. Modify `lib.rs` to initialize the plugin: + +```rust title="lib.rs" ins={4} +#[cfg_attr(mobile, tauri::mobile_entry_point)] +fn run() { + tauri::Builder::default() + .plugin(tauri_plugin_deep_link::init()) + .run(tauri::generate_context!()) + .expect("error while running tauri application"); +} +``` + +3. Install the JavaScript Guest bindings using your preferred JavaScript package manager: + + + + + +## Setting up + +### Android + +For [app links](https://developer.android.com/training/app-links#android-app-links), you need a server with a `.well-known/assetlinks.json` endpoint that must return a text response in the given format: + +```json title=".well-known/assetlinks.json" +[ + { + "relation": ["delegate_permission/common.handle_all_urls"], + "target": { + "namespace": "android_app", + "package_name": "$APP_BUNDLE_ID", + "sha256_cert_fingerprints": [ + $CERT_FINGERPRINT + ] + } + } +] +``` + +Where `$APP_BUNDLE_ID` is the value defined on `tauri.conf.json > identifier` with `-` replaced with `_` and `$CERT_FINGERPRINT` is a list of SHA256 fingerprints of your app's signing certificates, see [verify android applinks](https://developer.android.com/training/app-links/verify-android-applinks#web-assoc) for more information. + +### iOS + +#### Server + +For [universal links](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content?language=objc), you need a server with a `.well-known/apple-app-site-association` endpoint that must return a text response in the given format: + +```json title=".well-known/apple-app-site-association" +{ + "applinks": { + "details": [ + { + "appIDs": ["$DEVELOPMENT_TEAM_ID.$APP_BUNDLE_ID"], + "components": [ + { + "/": "/open/*", + "comment": "Matches any URL whose path starts with /open/" + } + ] + } + ] + } +} +``` + +Where `$DEVELOPMENT_TEAM_ID` is the value defined on `tauri.conf.json > tauri > bundle > iOS > developmentTeam` or the `TAURI_APPLE_DEVELOPMENT_TEAM` environment variable and `$APP_BUNDLE_ID` is the value defined on `tauri.conf.json > identifier`. See [applinks.details](https://developer.apple.com/documentation/bundleresources/applinks/details) for more information. + +#### App + +You also need to add the associated domains to your app's `entitlements` file: + +```xml title="src-tauri/gen/apple/[App Name]_iOS/[App Name]_iOS.entitlements" ins={5-9} + + + + + com.apple.developer.associated-domains + + applinks:your.website.com + applinks:nother.site.br + + + +``` + +See [supporting associated domains](https://developer.apple.com/documentation/xcode/supporting-associated-domains?language=objc) for more information. + +## Configuration + +Under `tauri.conf.json > plugins > deep-link`, configure the domains you want to associate with your application: + +```json title="tauri.conf.json" +{ + "plugins": { + "deep-link": { + "domains": [ + { "host": "your.website.com", "pathPrefix": ["/open"] }, + { "host": "another.site.br" } + ] + } + } +} +``` + +## Usage + +The deep-link plugin is available in both JavaScript and Rust. + + + + +```js +import { onOpenUrl } from '@tauri-apps/plugin-deep-link'; + +await onOpenUrl((urls) => { + console.log('deep link:', urls); +}); +``` + + + + +```rust title="src-tauri/src/lib.rs" +use tauri_plugin_cli::CliExt; + +#[cfg_attr(mobile, tauri::mobile_entry_point)] +fn run() { + tauri::Builder::default() + .plugin(tauri_plugin_deep_link::init()) + .setup(|app| { + app.listen("deep-link://new-url", |url| { + dbg!(url); + }); + Ok(()) + }) + .run(tauri::generate_context!()) + .expect("error while running tauri application"); +} +``` + + + + +## Permissions + +By default all plugin commands are blocked and cannot be accessed. +You must define a list of permissions in your `capabilities` configuration. + +See [Access Control List](/references/v2/acl) for more information. + +```json title="src-tauri/capabilities/main.json" ins={9} +{ + "$schema": "./schemas/mobile-schema.json", + "identifier": "mobile-capability", + "windows": ["main"], + "platforms": ["iOS", "android"], + "permissions": [ + // Usually you will need event:default to listen to the deep-link event + "event:default", + "deep-link:default" + ] +} +``` + +| Permission | Description | +| ----------------------------- | ----------------------------------------------------------------- | +| `deep-link:default` | Allows reading the opened deep link via the get_current command. | +| `deep-link:allow-get-current` | Enables the get_current command without any pre-configured scope. | +| `deep-link:deny-get-current` | Denies the get_current command without any pre-configured scope. |