Merge branch 'next' into docs/features/fs

tauri-apps · Feb 27, 2024 · 5a41a58 · 5a41a58
2 parents edc9a0b + d8b8cd6
commit 5a41a58
Show file tree

Hide file tree

Showing 2 changed files with 209 additions and 5 deletions.
diff --git 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.
   <TabItem label="JavaScript">
 
 ```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
@@ -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';
 
 <PluginLinks plugin="deep-link" />
 
-<Stub>
-	Based on
-	https://github.com/tauri-apps/plugins-workspace/tree/v2/plugins/deep-link
-</Stub>
+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.
+
+<Tabs>
+  <TabItem label="Automatic">
+
+Use your project's package manager to add the dependency:
+
+{' '}
+
+<CommandTabs
+	npm="npm run tauri add deep-link"
+	yarn="yarn run tauri add deep-link"
+	pnpm="pnpm tauri add deep-link"
+	cargo="cargo tauri add deep-link"
+/>
+
+  </TabItem>
+  <TabItem label="Manual">
+
+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:
+
+  <CommandTabs
+      npm="npm install @tauri-apps/plugin-deep-link"
+      yarn="yarn add @tauri-apps/plugin-deep-link"
+      pnpm="pnpm add @tauri-apps/plugin-deep-link"
+  />
+  </TabItem>
+</Tabs>
+
+## 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}
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>com.apple.developer.associated-domains</key>
+	<array>
+		<string>applinks:your.website.com</string>
+		<string>applinks:nother.site.br</string>
+	</array>
+</dict>
+</plist>
+```
+
+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.
+
+<Tabs>
+  <TabItem label="JavaScript">
+
+```js
+import { onOpenUrl } from '@tauri-apps/plugin-deep-link';
+
+await onOpenUrl((urls) => {
+	console.log('deep link:', urls);
+});
+```
+
+  </TabItem>
+  <TabItem label="Rust">
+
+```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");
+}
+```
+
+  </TabItem>
+</Tabs>
+
+## 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.  |