From ff5c9b177789e9c00e5956c2b91fc17d43abcba2 Mon Sep 17 00:00:00 2001 From: Jason Tsai Date: Tue, 27 Feb 2024 19:24:38 +0800 Subject: [PATCH 1/2] docs(features): update deep-link page (#1886) * docs(features): update deep-link page * docs(features): add module import to cli javascript usage * docs: fix deep-link permission example --- src/content/docs/features/cli.mdx | 2 + src/content/docs/features/deep-linking.mdx | 212 ++++++++++++++++++++- 2 files changed, 209 insertions(+), 5 deletions(-) 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..90e0b3a7d5 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. | From d8b8cd6d96010090633358f37f1ebe0fb5e80496 Mon Sep 17 00:00:00 2001 From: dklassic Date: Tue, 27 Feb 2024 11:25:14 +0000 Subject: [PATCH 2/2] [ci] format --- src/content/docs/features/deep-linking.mdx | 58 +++++++++++----------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/src/content/docs/features/deep-linking.mdx b/src/content/docs/features/deep-linking.mdx index 90e0b3a7d5..98c8038d55 100644 --- a/src/content/docs/features/deep-linking.mdx +++ b/src/content/docs/features/deep-linking.mdx @@ -98,19 +98,19 @@ For [universal links](https://developer.apple.com/documentation/xcode/allowing-a ```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/" - } - ] - } - ] - } + "applinks": { + "details": [ + { + "appIDs": ["$DEVELOPMENT_TEAM_ID.$APP_BUNDLE_ID"], + "components": [ + { + "/": "/open/*", + "comment": "Matches any URL whose path starts with /open/" + } + ] + } + ] + } } ``` @@ -142,14 +142,14 @@ Under `tauri.conf.json > plugins > deep-link`, configure the domains you want to ```json title="tauri.conf.json" { - "plugins": { - "deep-link": { - "domains": [ - { "host": "your.website.com", "pathPrefix": ["/open"] }, - { "host": "another.site.br" } - ] - } - } + "plugins": { + "deep-link": { + "domains": [ + { "host": "your.website.com", "pathPrefix": ["/open"] }, + { "host": "another.site.br" } + ] + } + } } ``` @@ -161,10 +161,10 @@ The deep-link plugin is available in both JavaScript and Rust. ```js -import { onOpenUrl } from "@tauri-apps/plugin-deep-link"; +import { onOpenUrl } from '@tauri-apps/plugin-deep-link'; await onOpenUrl((urls) => { - console.log('deep link:', urls); + console.log('deep link:', urls); }); ``` @@ -206,15 +206,15 @@ See [Access Control List](/references/v2/acl) for more information. "windows": ["main"], "platforms": ["iOS", "android"], "permissions": [ - // Usually you will need event:default to listen to the deep-link event - "event:default", - "deep-link:default", - ] + // Usually you will need event:default to listen to the deep-link event + "event:default", + "deep-link:default" + ] } ``` -| Permission | Description | -| ----------------------- | ----------------------------------------------------------------- | +| 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. |