{"_id":"@cliffhelsel/capacitor-live-activity","name":"@cliffhelsel/capacitor-live-activity","dist-tags":{"latest":"7.0.1-cliff.1"},"versions":{"7.0.1-cliff.1":{"name":"@cliffhelsel/capacitor-live-activity","version":"7.0.1-cliff.1","description":"A Capacitor plugin for managing iOS Live Activities using ActivityKit and Swift.","main":"dist/plugin.cjs.js","module":"dist/esm/index.js","types":"dist/esm/index.d.ts","unpkg":"dist/plugin.js","author":{"name":"Kisimedia.de"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/kisimediaDE/capacitor-live-activity.git"},"bugs":{"url":"https://github.com/kisimediaDE/capacitor-live-activity/issues"},"keywords":["capacitor","live-activity","activitykit","ios","plugin","swift","capacitor-plugin"],"scripts":{"verify":"npm run verify:ios && npm run verify:web","verify:ios":"xcodebuild -scheme CapacitorLiveActivity -destination generic/platform=iOS","verify:web":"npm run build","lint":"npm run eslint && npm run prettier -- --check && npm run swiftlint -- lint","fmt":"npm run eslint -- --fix && npm run prettier -- --write && npm run swiftlint -- --fix --format","eslint":"eslint . --ext ts","prettier":"prettier \"**/*.{css,html,ts,js,java}\" --plugin=prettier-plugin-java","swiftlint":"node-swiftlint","docgen":"docgen --api LiveActivityPlugin --output-readme README.md --output-json dist/docs.json","build":"npm run clean && npm run docgen && tsc && rollup -c rollup.config.mjs","clean":"rimraf ./dist","watch":"tsc --watch","prepublishOnly":"npm run build"},"devDependencies":{"@capacitor/core":"^7.4.1","@capacitor/docgen":"^0.3.0","@capacitor/ios":"^7.4.1","@ionic/eslint-config":"^0.4.0","@ionic/prettier-config":"^4.0.0","@ionic/swiftlint-config":"^2.0.0","eslint":"^8.57.1","prettier":"^3.6.2","prettier-plugin-java":"^2.7.1","rimraf":"^6.0.1","rollup":"^4.44.2","swiftlint":"^2.0.0","typescript":"^5.8.3"},"peerDependencies":{"@capacitor/core":">=7.0.0"},"prettier":"@ionic/prettier-config","swiftlint":"@ionic/swiftlint-config","eslintConfig":{"extends":"@ionic/eslint-config/recommended"},"capacitor":{"ios":{"src":"ios"}},"_id":"@cliffhelsel/capacitor-live-activity@7.0.1-cliff.1","gitHead":"01f4ce66e596ef2dd22345093bfd0d1cb6d80082","homepage":"https://github.com/kisimediaDE/capacitor-live-activity#readme","_nodeVersion":"20.19.5","_npmVersion":"10.8.2","dist":{"integrity":"sha512-LMOh2y3t9Ig1+Y2x0gI5qeObGN07LVHeJocLvXzGz0uU/MAgXutCwNTkxmZmMschaxNb+iPZGnzWik86qyERIw==","shasum":"31065ff3a9b4c76c7c663454ee832dff40cfa9ec","tarball":"https://registry.npmjs.org/@cliffhelsel/capacitor-live-activity/-/capacitor-live-activity-7.0.1-cliff.1.tgz","fileCount":23,"unpackedSize":65033,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIG9gp0tK5Z5b3nISY5XAiyGAS3oOnDAMI/4wLCrdyTveAiEAgSCWjHBcdPb1P/EmHgrlgsB+JvA07nUGGCj12IDfN18="}]},"_npmUser":{"name":"pagescholar","email":"npm@pagescholar.com"},"directories":{},"maintainers":[{"name":"pagescholar","email":"npm@pagescholar.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/capacitor-live-activity_7.0.1-cliff.1_1760647043259_0.9802802445853604"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-16T20:37:23.195Z","7.0.1-cliff.1":"2025-10-16T20:37:23.446Z","modified":"2025-10-16T20:37:23.777Z"},"maintainers":[{"name":"pagescholar","email":"npm@pagescholar.com"}],"description":"A Capacitor plugin for managing iOS Live Activities using ActivityKit and Swift.","homepage":"https://github.com/kisimediaDE/capacitor-live-activity#readme","keywords":["capacitor","live-activity","activitykit","ios","plugin","swift","capacitor-plugin"],"repository":{"type":"git","url":"git+https://github.com/kisimediaDE/capacitor-live-activity.git"},"author":{"name":"Kisimedia.de"},"bugs":{"url":"https://github.com/kisimediaDE/capacitor-live-activity/issues"},"license":"MIT","readme":"# 📡 capacitor-live-activity\n\n[![npm](https://img.shields.io/npm/v/capacitor-live-activity)](https://www.npmjs.com/package/capacitor-live-activity)\n[![bundle size](https://img.shields.io/bundlephobia/minzip/capacitor-live-activity)](https://bundlephobia.com/result?p=capacitor-live-activity)\n[![License: MIT](https://img.shields.io/npm/l/capacitor-live-activity)](./LICENSE)\n[![Platforms](https://img.shields.io/badge/platforms-iOS-orange)](#-platform-behavior)\n[![Capacitor](https://img.shields.io/badge/capacitor-7.x-blue)](https://capacitorjs.com/)\n\nA Capacitor plugin for managing iOS Live Activities using ActivityKit and Swift.\n\n> [!TIP]\n> 🚀 Looking for a ready-to-run demo? → [Try the Example App](./example-app/)\n\n## 🧭 Table of contents\n\n- [🧭 Table of contents](#-table-of-contents)\n- [📦 Install](#-install)\n- [🧩 Widget Setup (Required)](#-widget-setup-required)\n  - [1. Add a Widget Extension in Xcode](#1-add-a-widget-extension-in-xcode)\n  - [2. Configure the Widget (Example)](#2-configure-the-widget-example)\n  - [3. Add GenericAttributes.swift to your Widget Target](#3-add-genericattributesswift-to-your-widget-target)\n    - [To make it available in your widget extension:](#to-make-it-available-in-your-widget-extension)\n    - [Why is this needed?](#why-is-this-needed)\n  - [4. Add Capability](#4-add-capability)\n  - [5. Ensure Inclusion in Build](#5-ensure-inclusion-in-build)\n- [📱 Example App](#-example-app)\n- [🛠 API](#-api)\n\n## 📦 Install\n\n```bash\nnpm install capacitor-live-activity\nnpx cap sync\n```\n\n> [!NOTE]\n> This plugin requires **iOS 16.2+** to work properly due to `ActivityKit` API usage.\n\n> [!IMPORTANT]\n> This plugin **requires a Live Activity widget extension** to be present and configured in your Xcode project.  \n> Without a widget, Live Activities will not appear on the lock screen or Dynamic Island.\n\n## 🧩 Widget Setup (Required)\n\nTo use Live Activities, your app must include a widget extension that defines the UI for the Live Activity using ActivityKit. Without this, the Live Activity will not appear on the Lock Screen or Dynamic Island.\n\n### 1. Add a Widget Extension in Xcode\n\n1.  Open your app’s iOS project in Xcode.\n2.  Go to File > New > Target…\n3.  Choose Widget Extension.\n4.  Name it e.g. LiveActivityWidget.\n5.  Check the box “Include Live Activity”.\n6.  Finish and wait for Xcode to generate the files.\n\n### 2. Configure the Widget (Example)\n\nMake sure the widget uses the same attribute type as the plugin (e.g. GenericAttributes.swift):\n\n```swift\nimport ActivityKit\nimport WidgetKit\nimport SwiftUI\n\nstruct LiveActivityWidgetLiveActivity: Widget {\n    var body: some WidgetConfiguration {\n        ActivityConfiguration(for: GenericAttributes.self) { context in\n            // Lock Screen UI\n            VStack {\n                Text(context.state.values[\"title\"] ?? \"⏱\")\n                Text(context.state.values[\"status\"] ?? \"-\")\n            }\n        } dynamicIsland: { context in\n            DynamicIsland {\n                DynamicIslandExpandedRegion(.leading) {\n                    Text(context.state.values[\"title\"] ?? \"\")\n                }\n                DynamicIslandExpandedRegion(.trailing) {\n                    Text(context.state.values[\"status\"] ?? \"\")\n                }\n                DynamicIslandExpandedRegion(.bottom) {\n                    Text(context.state.values[\"message\"] ?? \"\")\n                }\n            } compactLeading: {\n                Text(\"🔔\")\n            } compactTrailing: {\n                Text(context.state.values[\"status\"] ?? \"\")\n            } minimal: {\n                Text(\"🎯\")\n            }\n        }\n    }\n}\n```\n\n### 3. Add GenericAttributes.swift to your Widget Target\n\nTo support Live Activities with dynamic values, this plugin uses a shared Swift struct called GenericAttributes.\n\n> By default, it’s located under: Pods > CapacitorLiveActivity > LiveActivityPlugin > Shared > GenericAttributes.swift\n\n#### To make it available in your widget extension:\n\n1. Open Xcode and go to the File Navigator.\n2. Expand Pods > CapacitorLiveActivity > Shared.\n3. Copy GenericAttributes.swift to Widget Extension Target, e.g. LiveActivityWidget\n4. Make sure to select \"Copy files to destination\"\n\n#### Why is this needed?\n\nXcode doesn’t automatically include files from a CocoaPods plugin into your widget target.\nWithout this step, your widget won’t compile because it cannot find GenericAttributes.\n\n### 4. Add Capability\n\nGo to your main app target → Signing & Capabilities tab and add:\n\n- Background Modes → Background fetch\n\n### 5. Ensure Inclusion in Build\n\n- In your **App target’s Info.plist**, ensure:\n\n```xml\n<key>NSSupportsLiveActivities</key>\n<true/>\n```\n\n- Clean and rebuild the project (Cmd + Shift + K, then Cmd + B).\n\n## 📱 Example App\n\nThis plugin includes a fully functional demo app under the [`example-app/`](./example-app) directory.\n\nThe demo is designed to run on real iOS devices and showcases multiple Live Activity types like delivery, timer, taxi, workout, and more.\n\n- Launch and test various Live Activities interactively\n- Trigger updates and alert banners\n- View JSON state changes in a live log console\n\n> [!NOTE]\n> For full instructions, see [example-app/README.md](./example-app/README.md)\n\n## 🛠 API\n\n<docgen-index>\n\n* [`startActivity(...)`](#startactivity)\n* [`startObservingPushToStartToken()`](#startobservingpushtostarttoken)\n* [`addListener('pushToStartToken', ...)`](#addlistenerpushtostarttoken-)\n* [`updateActivity(...)`](#updateactivity)\n* [`endActivity(...)`](#endactivity)\n* [`isAvailable()`](#isavailable)\n* [`isRunning(...)`](#isrunning)\n* [`getCurrentActivity(...)`](#getcurrentactivity)\n* [Interfaces](#interfaces)\n* [Type Aliases](#type-aliases)\n\n</docgen-index>\n\n<docgen-api>\n<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->\n\n### startActivity(...)\n\n```typescript\nstartActivity(options: StartActivityOptions) => Promise<void>\n```\n\nStarts a new Live Activity on iOS using the provided options.\n\n| Param         | Type                                                                  |\n| ------------- | --------------------------------------------------------------------- |\n| **`options`** | <code><a href=\"#startactivityoptions\">StartActivityOptions</a></code> |\n\n**Since:** 0.0.1\n\n--------------------\n\n\n### startObservingPushToStartToken()\n\n```typescript\nstartObservingPushToStartToken() => Promise<void>\n```\n\n--------------------\n\n\n### addListener('pushToStartToken', ...)\n\n```typescript\naddListener(eventName: 'pushToStartToken', listenerFunc: (data: { token: string; }) => void) => Promise<PluginListenerHandle>\n```\n\n| Param              | Type                                               |\n| ------------------ | -------------------------------------------------- |\n| **`eventName`**    | <code>'pushToStartToken'</code>                    |\n| **`listenerFunc`** | <code>(data: { token: string; }) =&gt; void</code> |\n\n**Returns:** <code>Promise&lt;<a href=\"#pluginlistenerhandle\">PluginListenerHandle</a>&gt;</code>\n\n--------------------\n\n\n### updateActivity(...)\n\n```typescript\nupdateActivity(options: UpdateActivityOptions) => Promise<void>\n```\n\nUpdates the currently active Live Activity.\n\n| Param         | Type                                                                    |\n| ------------- | ----------------------------------------------------------------------- |\n| **`options`** | <code><a href=\"#updateactivityoptions\">UpdateActivityOptions</a></code> |\n\n**Since:** 0.0.1\n\n--------------------\n\n\n### endActivity(...)\n\n```typescript\nendActivity(options: EndActivityOptions) => Promise<void>\n```\n\nEnds the Live Activity and optionally provides a final state and dismissal policy.\n\n| Param         | Type                                                              |\n| ------------- | ----------------------------------------------------------------- |\n| **`options`** | <code><a href=\"#endactivityoptions\">EndActivityOptions</a></code> |\n\n**Since:** 0.0.1\n\n--------------------\n\n\n### isAvailable()\n\n```typescript\nisAvailable() => Promise<boolean>\n```\n\nReturns whether Live Activities are available on this device and allowed by the user.\n\n**Returns:** <code>Promise&lt;boolean&gt;</code>\n\n**Since:** 0.0.1\n\n--------------------\n\n\n### isRunning(...)\n\n```typescript\nisRunning(options: { id: string; }) => Promise<boolean>\n```\n\nReturns true if a Live Activity with the given ID is currently running.\n\n| Param         | Type                         |\n| ------------- | ---------------------------- |\n| **`options`** | <code>{ id: string; }</code> |\n\n**Returns:** <code>Promise&lt;boolean&gt;</code>\n\n**Since:** 0.0.1\n\n--------------------\n\n\n### getCurrentActivity(...)\n\n```typescript\ngetCurrentActivity(options?: { id?: string | undefined; } | undefined) => Promise<LiveActivityState | undefined>\n```\n\nReturns the current active Live Activity state, if any.\n\nIf an ID is provided, returns that specific activity.\nIf no ID is given, returns the most recently started activity.\n\n| Param         | Type                          |\n| ------------- | ----------------------------- |\n| **`options`** | <code>{ id?: string; }</code> |\n\n**Returns:** <code>Promise&lt;<a href=\"#liveactivitystate\">LiveActivityState</a>&gt;</code>\n\n**Since:** 0.0.1\n\n--------------------\n\n\n### Interfaces\n\n\n#### StartActivityOptions\n\nOptions for starting a Live Activity.\n\n| Prop               | Type                                                            | Description                                               |\n| ------------------ | --------------------------------------------------------------- | --------------------------------------------------------- |\n| **`id`**           | <code>string</code>                                             | Unique ID to identify the Live Activity.                  |\n| **`attributes`**   | <code><a href=\"#record\">Record</a>&lt;string, string&gt;</code> | Immutable attributes that are part of the Live Activity.  |\n| **`contentState`** | <code><a href=\"#record\">Record</a>&lt;string, string&gt;</code> | Initial content state (dynamic values).                   |\n| **`timestamp`**    | <code>number</code>                                             | Optional timestamp (Unix) when the Live Activity started. |\n\n\n#### PluginListenerHandle\n\n| Prop         | Type                                      |\n| ------------ | ----------------------------------------- |\n| **`remove`** | <code>() =&gt; Promise&lt;void&gt;</code> |\n\n\n#### UpdateActivityOptions\n\nOptions for updating a Live Activity.\n\n| Prop               | Type                                                              | Description                                                                      |\n| ------------------ | ----------------------------------------------------------------- | -------------------------------------------------------------------------------- |\n| **`id`**           | <code>string</code>                                               | ID of the Live Activity to update.                                               |\n| **`contentState`** | <code><a href=\"#record\">Record</a>&lt;string, string&gt;</code>   | Updated content state (dynamic values).                                          |\n| **`alert`**        | <code><a href=\"#alertconfiguration\">AlertConfiguration</a></code> | Optional alert configuration to show a notification banner or Apple Watch alert. |\n| **`timestamp`**    | <code>number</code>                                               | Optional timestamp (Unix) when the update occurred.                              |\n\n\n#### AlertConfiguration\n\nConfiguration for alert notifications.\n\n| Prop        | Type                | Description                            |\n| ----------- | ------------------- | -------------------------------------- |\n| **`title`** | <code>string</code> | Optional title of the alert.           |\n| **`body`**  | <code>string</code> | Optional body text of the alert.       |\n| **`sound`** | <code>string</code> | Optional sound file name or \"default\". |\n\n\n#### EndActivityOptions\n\nOptions for ending a Live Activity.\n\n| Prop                | Type                                                            | Description                                                                            |\n| ------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------- |\n| **`id`**            | <code>string</code>                                             | ID of the Live Activity to end.                                                        |\n| **`contentState`**  | <code><a href=\"#record\">Record</a>&lt;string, string&gt;</code> | Final state to show before dismissal.                                                  |\n| **`timestamp`**     | <code>number</code>                                             | Optional timestamp (Unix) when the end occurred.                                       |\n| **`dismissalDate`** | <code>number</code>                                             | Optional dismissal time in the future (Unix). If not provided, system default applies. |\n\n\n#### LiveActivityState\n\nRepresents an active Live Activity state.\n\n| Prop            | Type                                                            | Description                                     |\n| --------------- | --------------------------------------------------------------- | ----------------------------------------------- |\n| **`id`**        | <code>string</code>                                             | The unique identifier of the activity.          |\n| **`values`**    | <code><a href=\"#record\">Record</a>&lt;string, string&gt;</code> | The current dynamic values of the activity.     |\n| **`isStale`**   | <code>boolean</code>                                            | Whether the activity is stale.                  |\n| **`isEnded`**   | <code>boolean</code>                                            | Whether the activity has ended.                 |\n| **`startedAt`** | <code>string</code>                                             | ISO string timestamp when the activity started. |\n\n\n### Type Aliases\n\n\n#### Record\n\nConstruct a type with a set of properties K of type T\n\n<code>{\r [P in K]: T;\r }</code>\n\n</docgen-api>\n","readmeFilename":"README.md","_rev":"1-a38880afc6fd36bb88d694006e3b5cf4"}