Skip to content

Commit 1951a8b

Browse files
sgammonsgammon
committed
docs: add push-notifications plugin docs
Relates-To: tauri-apps/tauri#11652 Relates-To: tauri-apps/tauri#11651 Signed-off-by: Sam Gammon <[email protected]>
1 parent ad41906 commit 1951a8b

File tree

1 file changed

+241
-0
lines changed

1 file changed

+241
-0
lines changed

‎src/content/docs/plugin/push-notifications.mdx

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
---
2+
title: Push Notifications
3+
description: Push notifications to your cross-platform app.
4+
sidebar:
5+
badge:
6+
text: New
7+
variant: tip
8+
plugin: push-notifications
9+
---
10+
11+
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
12+
import CommandTabs from '@components/CommandTabs.astro';
13+
import PluginPermissions from '@components/PluginPermissions.astro';
14+
import PluginLinks from '@components/PluginLinks.astro';
15+
import Compatibility from '@components/plugins/Compatibility.astro';
16+
17+
<PluginLinks plugin={frontmatter.plugin} />
18+
19+
Push notifications for your cross-platform Tauri app.
20+
21+
## Supported Platforms
22+
23+
<Compatibility plugin={frontmatter.plugin} />
24+
25+
## Setup
26+
27+
First, enable the `push-notifications` feature in your `Cargo.toml` file:
28+
29+
```toml title="src-tauri/Cargo.toml" {3}
30+
[dependencies]
31+
tauri = { version = "1", features = ["push-notifications"] }
32+
```
33+
34+
Then, install the `push-notifications` plugin:
35+
36+
<Tabs>
37+
<TabItem label="Automatic">
38+
39+
Use your project's package manager to add the dependency:
40+
41+
{' '}
42+
43+
<CommandTabs
44+
npm="npm run tauri add push-notifications"
45+
yarn="yarn run tauri add push-notifications"
46+
pnpm="pnpm tauri add push-notifications"
47+
bun="bun tauri add push-notifications"
48+
cargo="cargo tauri add push-notifications"
49+
/>
50+
51+
</TabItem>
52+
<TabItem label="Manual">
53+
<Steps>
54+
55+
1. Run the following command in the `src-tauri` folder to add the plugin to the project's dependencies in `Cargo.toml`:
56+
57+
```sh frame=none
58+
cargo add tauri-plugin-push-notifications
59+
```
60+
61+
2. Modify `lib.rs` to initialize the plugin:
62+
63+
```rust title="src-tauri/src/lib.rs" ins={5-6}
64+
#[cfg_attr(mobile, tauri::mobile_entry_point)]
65+
pub fn run() {
66+
tauri::Builder::default()
67+
.setup(|app| {
68+
#[cfg(desktop)]
69+
app.handle().plugin(tauri_plugin_push_notifications::init());
70+
Ok(())
71+
})
72+
.run(tauri::generate_context!())
73+
.expect("error while running tauri application");
74+
}
75+
```
76+
77+
3. Install the JavaScript Guest bindings using your preferred JavaScript package manager:
78+
79+
<CommandTabs
80+
npm="npm install tauri-plugin-push-notifications"
81+
yarn="yarn add tauri-plugin-push-notifications"
82+
pnpm="pnpm add tauri-plugin-push-notifications"
83+
deno="deno add npm:tauri-plugin-push-notifications"
84+
bun="bun add tauri-plugin-push-notifications"
85+
/>
86+
87+
</Steps>
88+
89+
</TabItem>
90+
</Tabs>
91+
92+
## Configuration
93+
94+
Each platform requires specific configuration to enable push notifications. Each push provider (Apple, Google, Microsoft, etc.) typically
95+
requires credentials and/or entitlements to obtain and use a push token.
96+
97+
### Apple Platforms
98+
99+
To access the [Apple Push Notification Service][0] (APNS) on macOS and iOS, you need to create an APNS certificate or token, and you must
100+
add an entitlement to your application.
101+
102+
#### iOS Configuration
103+
104+
Add the following entitlement to your iOS app:
105+
106+
```xml title=src-tauri/entitlements.plist
107+
<key>aps-environment</key>
108+
<string>production</string>
109+
```
110+
111+
Here's an example of a full entitlements file (yours may vary, `...` values are placeholders):
112+
113+
```xml title=src-tauri/entitlements.plist
114+
<?xml version="1.0" encoding="UTF-8"?>
115+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
116+
<plist version="1.0">
117+
<dict>
118+
<key>com.apple.application-identifier</key>
119+
<string>...</string>
120+
<key>com.apple.developer.team-identifier</key>
121+
<string>...</string>
122+
<key>aps-environment</key>
123+
<string>production</string>
124+
</dict>
125+
</plist>
126+
```
127+
128+
#### macOS Configuration
129+
130+
Mac is similar to iOS. You still need an APNS certificate, which can be obtained from the Apple Developer portal. You also need to adjust your
131+
`Info.plist` and entitlements as shown below.
132+
133+
Add the following to your entitlements:
134+
135+
```xml title=src-tauri/entitlements.plist
136+
<key>com.apple.developer.aps-environment</key>
137+
<string>production</string>
138+
```
139+
140+
Here's an example of a full entitlements file (yours may vary, `...` values are placeholders):
141+
142+
```xml title=src-tauri/entitlements.plist
143+
<?xml version="1.0" encoding="UTF-8"?>
144+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
145+
<plist version="1.0">
146+
<dict>
147+
<key>com.apple.application-identifier</key>
148+
<string>...</string>
149+
<key>com.apple.developer.team-identifier</key>
150+
<string>...</string>
151+
<key>com.apple.developer.aps-environment</key>
152+
<string>production</string>
153+
</dict>
154+
</plist>
155+
```
156+
157+
### Android
158+
159+
Android uses [Firebase Cloud Messaging][1] (FCM) to send push notifications. To configure FCM, you need to create a Firebase project and add the
160+
`google-services.json` file to your project. You can find more information in the [Firebase documentation](https://firebase.google.com/docs/cloud-messaging/android/client).
161+
162+
Once these steps are complete, you can send push notifications to your Android app.
163+
164+
(TBD)
165+
166+
### Windows
167+
168+
Microsoft provides [Windows Notification System][2] (WNS) for pushing notifications to apps on Windows devices. WNS is newer than APNS and FCM,
169+
so it is not as widely used or supported, but it works in much the same way.
170+
171+
**Support for WNS in Tauri is experimental.**
172+
173+
Applications are automatically entitled for WNS on Windows. To obtain a push token, simply enable the `push-notifications` feature and use the plugin as described.
174+
175+
## Usage
176+
177+
The Push Notifications plugin is available in both JavaScript and Rust, allowing you to obtain a push token (where supported).
178+
179+
### Obtaining the push token
180+
181+
When the `push-notifications` feature is enabled within Tauri, the application will automatically request a push token from the underlying
182+
platform APIs when your app starts.
183+
184+
Then, from JavaScript or Rust guest code, you can obtain this token, and do whatever you need with it (usually send it to a server for
185+
later use when pushing notifications).
186+
187+
<Tabs syncKey="lang">
188+
189+
<TabItem label="JavaScript">
190+
191+
```javascript
192+
import { pushToken } from 'tauri-plugin-push-notifications';
193+
194+
// ... later ...
195+
196+
const token = await pushToken();
197+
198+
// `token` will be:
199+
//
200+
// - `null` if the platform does not support push notifications, or if
201+
// push is not configured, entitled, or enabled for the app; or
202+
//
203+
// - a base64-encoded string expressing the raw bytes of the push token.
204+
```
205+
206+
</TabItem>
207+
208+
<TabItem label="Rust">
209+
210+
```rust
211+
// coming soon
212+
```
213+
214+
</TabItem>
215+
216+
</Tabs>
217+
218+
:::note
219+
Obtaining a `pushToken` is an inert operation when the app is not entitled for push on iOS or macOS.
220+
:::
221+
222+
## Permissions
223+
224+
By default all potentially dangerous plugin commands and scopes are blocked and cannot be accessed. You must modify the permissions in your `capabilities` configuration to enable these.
225+
226+
See the [Capabilities Overview](/security/capabilities/) for more information and the [step by step guide](/learn/security/using-plugin-permissions/) to use plugin permissions.
227+
228+
```json title="src-tauri/capabilities/default.json" ins={4}
229+
{
230+
"permissions": [
231+
...,
232+
"push-notifications:default",
233+
]
234+
}
235+
```
236+
237+
<PluginPermissions plugin={frontmatter.plugin} />
238+
239+
[0]: https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns
240+
[1]: https://firebase.google.com/docs/cloud-messaging
241+
[2]: https://developer.microsoft.com/en-us/windows/apps/windows-push-notifications

0 commit comments

Comments
 (0)