{"id":15097967,"url":"https://github.com/ionic-team/capacitorwatch","last_synced_at":"2025-07-12T15:12:30.924Z","repository":{"id":182131009,"uuid":"660224922","full_name":"ionic-team/CapacitorWatch","owner":"ionic-team","description":"Build apps for watches with Capacitor","archived":false,"fork":false,"pushed_at":"2024-04-08T13:10:59.000Z","size":2123,"stargazers_count":44,"open_issues_count":5,"forks_count":6,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-01-28T04:41:11.927Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ionic-team.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-29T14:20:32.000Z","updated_at":"2024-11-02T11:45:05.000Z","dependencies_parsed_at":"2024-01-18T05:20:17.659Z","dependency_job_id":"546fb8c7-793e-4ed5-881a-391e2e3ea85f","html_url":"https://github.com/ionic-team/CapacitorWatch","commit_stats":null,"previous_names":["ionic-team/capacitorwatch"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ionic-team%2FCapacitorWatch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ionic-team%2FCapacitorWatch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ionic-team%2FCapacitorWatch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ionic-team%2FCapacitorWatch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ionic-team","download_url":"https://codeload.github.com/ionic-team/CapacitorWatch/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237172294,"owners_count":19266646,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-25T16:41:40.627Z","updated_at":"2025-02-04T18:31:49.854Z","avatar_url":"https://github.com/ionic-team.png","language":"Swift","readme":"# @capacitor/watch\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/ionic-team/capacitorwatch/actions?query=workflow%3ACI\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/ionic-team/capacitor/ci.yml?style=flat-square\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@capacitor/watch\"\u003e\u003cimg src=\"https://img.shields.io/npm/dw/@capacitor/watch?style=flat-square\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@capacitor/watch\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@capacitor/watch?style=flat-square\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@capacitor/watch\"\u003e\u003cimg src=\"https://img.shields.io/npm/l/@capacitor/watch?style=flat-square\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://capacitorjs.com/docs\"\u003e\u003cimg src=\"https://img.shields.io/static/v1?label=docs\u0026message=capacitorjs.com\u0026color=blue\u0026style=flat-square\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://twitter.com/capacitorjs\"\u003e\u003cimg src=\"https://img.shields.io/twitter/follow/capacitorjs\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n_CapacitorLABS_ - This project is experimental. Support is not provided. Please open issues when needed.\n\n---\n\nThe Capacitor Watch plugin allows you to define a UI for a watch in your web code and show it on a paired watch.\n\nThis currently only supports iOS. This guide assumes you've already added iOS to your capcacitor project.\n\nAlso note - all of this will only work with an actual Apple Watch. Simulators don't allow the app\u003c-\u003ewatch communcation like real devices do.\n\n## Install\n\nStep 1\n\nAdd the watch plugin to your capacitor project, and then open the Xcode project:\n\n```bash\nnpm install @capacitor/watch\nnpx cap sync\nnpx cap open ios\n```\n\nStep 2\n\nGo to add capabilities:\n\n\u003cimg src=\"https://raw.githubusercontent.com/ionic-team/CapacitorWatch/main/img/add-capability.png\" /\u003e\n\nAdd the 'Background Modes' and 'Push Notification' capabilities. Then in the Background Modes options, select 'Background Fetch', 'Remote Notifications', and 'Background Processing'. Your App target should look like this:\n\n\u003cimg src=\"https://raw.githubusercontent.com/ionic-team/CapacitorWatch/main/img/capabilities-final.png\" /\u003e\n\nStep 3\n\nOpen `AppDelegate.swift` and add `import WatchConnectivity`  and `import CapactiorWatch` to the top of the file, and the following code inside the `application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?)` method:\n\n```swift\nassert(WCSession.isSupported(), \"This sample requires Watch Connectivity support!\")\nWCSession.default.delegate = CapWatchSessionDelegate.shared\nWCSession.default.activate()\n```\n\nStep 4\n\nSelect File -\u003e New -\u003e Target in Xcode, and then the watchOS tab, and 'App':\n\n\u003cimg src=\"https://raw.githubusercontent.com/ionic-team/CapacitorWatch/main/img/target-watch.png\" /\u003e\n\nClick 'Next' then fill out the options like so:\n\n\u003cimg src=\"https://raw.githubusercontent.com/ionic-team/CapacitorWatch/main/img/watch-target-options.png\" /\u003e\n\nThis dialog can be a little confusing, the key thing is your 'Bundle Identifier' must be `[your apps bundle ID].watchapp` for the watch\u003c-\u003eapp pairing to work. You must also pick SwiftUI for the Interface and Swift for the language. The project should be `App`.\n\nStep 5\n\nWe're going to add the code that makes Capacitor Watch work in the watch application.\n\n---\n\nIf you are using \u003cb\u003eXcode 15 or beyond\u003c/b\u003e you then need to add the Capacitor Watch Swift Package from your node_modules:\n\nFirst go to the project package dependancies\n\n\u003cimg src=\"https://raw.githubusercontent.com/ionic-team/CapacitorWatch/main/img/spm-project-dependancies.png\" /\u003e\n\nThen choose 'Add Local'\n\n\u003cimg src=\"https://raw.githubusercontent.com/ionic-team/CapacitorWatch/main/img/spm-add-local.png\" /\u003e\n\nThen navigate into the `node_modules/@capacitor/watch/CapWatch-Watch-SPM` folder and click 'Add Package'\n\n\u003cimg src=\"https://raw.githubusercontent.com/ionic-team/CapacitorWatch/main/img/spm-nav-to-package.png\" /\u003e\n\nThen in the column on the right pick your watch app to be the target and click 'Add Package'\n\n\u003cimg src=\"https://raw.githubusercontent.com/ionic-team/CapacitorWatch/main/img/spm-pick-target.png\" /\u003e\n\nOnce this is done your Package Dependancies should look like this:\n\n\u003cimg src=\"https://raw.githubusercontent.com/ionic-team/CapacitorWatch/main/img/spm-finished.png\" /\u003e\n\n---\n\nWith \u003cb\u003eXcode 14\u003c/b\u003e you will need to go here https://github.com/ionic-team/CapacitorWatch/tree/main/packages/iOS-capWatch-watch/Sources/iOS-capWatch-watch and copy all the files into your Watch project and make sure the target selected is your watch app. It should look like so:\n\n\u003cimg src=\"https://raw.githubusercontent.com/ionic-team/CapacitorWatch/main/img/watch-sources-added.png\" /\u003e\n\nStep 6\n\nThen open the watch app's 'Main' file which should be `watchappApp.swift`. Add the lines `import WatchConnectivity` and `import iOS_capWatch_watch`  above the `@main` statement. Then replace the line that says `ContentView()` with this:\n\nThe finished file should look like this:\n\n```swift\nimport SwiftUI\nimport WatchConnectivity\nimport iOS_capWatch_watch\n\n@main\nstruct watchddgg_Watch_AppApp: App {\n    var body: some Scene {\n        WindowGroup {\n            CapWatchContentView()\n                .onAppear {\n                    assert(WCSession.isSupported(), \"This sample requires Watch Connectivity support!\")\n                    WCSession.default.delegate = WatchViewModel.shared\n                    WCSession.default.activate()\n                }\n        }\n    }\n}\n```\n\nStep 7\n\nAdd the 'Background Modes' capability to the watch app target, and enable 'Remote Notifications':\n\n\u003cimg src=\"https://raw.githubusercontent.com/ionic-team/CapacitorWatch/main/img/watch-remote-not.png\" /\u003e\n\nYou should be ready to develop for Capcacitor Watch now!\n\n## Development workflow\n\nYou can still develop your iOS app like a normal capacitor app, but getting things to run on the watch requires you to change the target and destination in Xcode. You can change this with the 'Target Dropdown' near the center-top of Xcode:\n\n\u003cimg src=\"https://raw.githubusercontent.com/ionic-team/CapacitorWatch/main/img/target-dropdown.png\" /\u003e\n\nThe right half of this bar lets you pick the destination device or simulator. You will need to pick the watch paired with the phone and then hit the 'Run' button or use the 'cmd+r' run shortcut.\n\nThere can be some challenges in syncing the watch and phone apps. Sometimes you will get an error in the xcode console complaining the compainion app is not present. The best solution in this case is to re-build and re-install the apps on both devices.\n\n## Building the watch UI and sending it to the watch\n\nYou will use a long string to define the watch UI. A newline delimits components. Currently this plugin only supports a vertical scroll view of either Text or Button components.\n\nOnce you've defined your UI you can send it to the watch using the `updateWatchUI()` method:\n\n```typescript\nasync uploadMyWatchUI() {\n    const watchUI = \n        `Text(\"Capacitor WATCH\")\n         Button(\"Add One\", \"inc\")`;\n\n    await Watch.updateWatchUI({\"watchUI\": watchUI});\n}\n```\n\nWill produce this:\n\n\u003cimg src=\"https://raw.githubusercontent.com/ionic-team/CapacitorWatch/main/img/example-watchui.png\" /\u003e\n\n## Communicating with the watch\n\nThis article provides a great summary on the native methods and their implications: https://alexanderweiss.dev/blog/2023-01-18-three-ways-to-communicate-via-watchconnectivity\n\nOn the phone side, you can implement these methods using the Capacitor Background Runner Plugin (https://github.com/ionic-team/capacitor-background-runner). Currently the watch plugin will mainly handle the `didReceiveUserInfo` method, and you can recieve envents from the watch while your app is in the background using the following code in your runner.js:\n\n```javascript\naddEventListener(\"WatchConnectivity_didReceiveUserInfo\", (args) =\u003e {\n  console.log(args.message.jsCommand);\n})\n```\n\nYou can also implment the `runCommand` event listener for foreground procesing:\n\n```typescript\nWatch.addListener(\"runCommand\", (data: {command: string}) =\u003e {\n  console.log(\"PHONE got command - \" + data.command);\n})\n```\n\nThe commands are the 2nd paramter in the `Button()` definition of the watch UI. This can be any string.\n\n## Updating watch data\n\nYou can add variables to `Text()` elements by using a `$` variable and updating with the `updateWatchData` command:\n\n```\nText(\"Show my $number\")\n```\n\nThis example will update `$number` when executed: \n\n```typescript\nvar stateData = {\n  number: 0\n}\n\nasync function counterIncrement() {\n  stateData.counter++  \n  await Watch.updateWatchData({\"data\": convertValuesOfObjectToStringValues(stateData)})\n}\n```\n\n# Persistance on the Watch\n\nCapacitor Watch will persist the last UI you sent with `updateWatchUI()`. State from `updateWatchData()` is NOT preserved.\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fionic-team%2Fcapacitorwatch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fionic-team%2Fcapacitorwatch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fionic-team%2Fcapacitorwatch/lists"}