开始入门

复制一个包含安装步骤和本插件的全 Markdown 指南的设置提示.

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-live-activities`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/live-activities/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

安装

您可以使用我们的 AI 助手设置来安装插件。使用以下命令将 Capgo 技能添加到您的 AI 工具中：

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下提示：

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-live-activities` plugin in my project.

如果您prefer Manual Setup，安装插件并运行以下命令，然后遵循以下平台特定的说明：

bun add @capgo/capacitor-live-activities
bunx cap sync

iOS 设置

安装和同步插件不会创建原生 Live 活动 UI。ActivityKit 需要一个 Widget 扩展来注册一个 Live 活动配置，以便 startActivity 可以显示任何内容。

需求

请在应用目标和 Widget Extension 目标上使用 iOS 16.1 或更高版本。
在 iOS 设备或兼容的模拟器上进行测试。动态岛仅在支持的设备模型上可见；其他设备使用锁屏演示。
确保组合静态和动态 ActivityKit 数据不超过 Apple 的 4 KB 限值。

打开本机 iOS 项目：

bunx cap open ios

然后：

选择 文件 > 新建 > 目标.
添加一个 小工具扩展.
启用 包含实时活动.
禁用 包含配置意图 除非应用程序还需要一个可配置的小工具。
确保生成的扩展嵌入在主应用程序目标中。

小工具扩展必须包含一个 ActivityConfiguration 并在其 WidgetBundle中注册它。它必须提供每个所需的实时活动呈现形式：

锁屏
动态岛扩展
动态岛紧凑的首尾
动态岛最小

仅添加目标是不够的。原生应用或插件必须调用ActivityKit的request、update和end API。扩展必须包含SwiftUI code，可以解码和渲染相同的内容状态，包括ActivityKit的共享模型。主应用和小部件扩展目标都需要包含这些模型。如果使用Xcode生成的Live Activity模板，模板不会自动渲染传递给此插件的JSON布局；扩展也需要一个兼容的原生布局渲染器。 ActivityAttributes 2. 启用实时活动

标题：2. 启用实时活动

复制到剪贴板 Info.plist:

<key>NSSupportsLiveActivities</key>
<true/>

,请添加 Info.plist2. 启用实时活动 支持实时活动 __CAPGO_KEEP_0__ YES __CAPGO_KEEP_0__

3. 配置共享图片的 App 组

只有在使用 saveImage, removeImage, listImages, 或 cleanupImages。该插件通过以下格式从主应用程序包标识符中派生 App 组标识符：

group.<MAIN_APP_BUNDLE_ID>.liveactivities

例如，具有包标识符 com.example.delivery 必须使用：

group.com.example.delivery.liveactivities

In Xcode 中，添加 App 组 功能到主应用程序目标和 Widget 扩展目标，然后在两个目标上启用相同的标识符。

Live 活动扩展无法访问网络。下载远程图像在主应用程序中并将它们保存到共享 App 组，然后从 Live 活动引用它们。对于捆绑图像，也启用 Widget 扩展在资产的目标成员资格中。

4. 配置深度链接

使用 behavior.widgetUrl 或一个计时器序列 tapUrl，注册匹配的 URL 方案或 Universal 链接在主应用程序中。对于一个自定义方案，如 myapp://order/12345，在主应用程序目标的 Info > URL 类型 设置下添加该方案。

5. 可选：启用服务器驱动更新

本地更新由应用程序触发时，不需要推送通知。要从服务器开始、更新或结束实时活动：

添加 推送通知 将该功能添加到主应用程序目标。
获取 ActivityKit 推送令牌并将它们发送到服务器。
使用 liveactivity 推送类型
通过 APNs 将 ActivityKit 通知发送到服务器。 NSSupportsLiveActivitiesFrequentUpdates 将 Info.plist 仅在需要频繁推送更新的用例时添加到主应用程序中。

ActivityKit推送令牌与标准用户通知设备令牌是分开的。仅启用推送通知能力是不够的，服务器驱动的更新需要原生令牌处理和APNs后端。原生设置清单原生设置清单在调用之前，确保：

原生设置清单

是否在主应用目标上启用了。 startActivity小部件扩展已嵌入并注册了一个

NSSupportsLiveActivities 原生ActivityKit实现和小部件扩展使用相同的
类型。 ActivityConfiguration.
应用和小部件扩展的部署目标是iOS 16.1或更高。 ActivityAttributes 在iOS设置中为应用启用了实时活动。
当使用共享图像时，匹配的App组在两个目标上都已启用。
当使用共享图像时，匹配的App组在两个目标上都已启用。
当使用共享图像时，匹配的App组在两个目标上都已启用。
任何自定义 URL 方案由 widgetUrl 或 tapUrl 注册。

导入

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

API 概述

`areActivitiesSupported`

检查此设备是否支持实时活动。需要 iOS 16.1+ 和设备支持。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { supported, reason } = await CapgoLiveActivities.areActivitiesSupported();
if (supported) {
  console.log('Live Activities are supported!');
} else {
  console.log('Not supported:', reason);
}

`startActivity`

使用指定的布局和数据启动一个新的实时活动。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { activityId } = await CapgoLiveActivities.startActivity({
  layout: {
    type: 'container',
    direction: 'horizontal',
    children: [
      { type: 'text', content: 'Order #{{orderNumber}}', fontSize: 16, fontWeight: 'bold' },
      { type: 'text', content: '{{status}}', fontSize: 14, color: '#666666' }
    ]
  },
  dynamicIslandLayout: {
    expanded: {
      leading: { type: 'image', source: 'sfSymbol', value: 'box.truck' },
      trailing: { type: 'text', content: '{{eta}}' },
      center: { type: 'text', content: '{{status}}' },
      bottom: { type: 'progress', value: 'progress' }
    },
    compactLeading: { type: 'image', source: 'sfSymbol', value: 'box.truck' },
    compactTrailing: { type: 'text', content: '{{eta}}' },
    minimal: { type: 'image', source: 'sfSymbol', value: 'box.truck' }
  },
  data: {
    orderNumber: '12345',
    status: 'On the way',
    eta: '10 min',
    progress: 0.6
  }
});
console.log('Started activity:', activityId);

`updateActivity`

使用新数据更新一个现有的实时活动。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.updateActivity({
  activityId: 'abc123',
  data: {
    status: 'Arrived!',
    eta: 'Now',
    progress: 1.0
  },
  alertConfiguration: {
    title: 'Delivery Update',
    body: 'Your order has arrived!'
  }
});

`endActivity`

结束一个实时活动。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.endActivity({
  activityId: 'abc123',
  data: { status: 'Delivered' },
  dismissalPolicy: 'after',
  dismissAfter: Date.now() + 3600000 // 1 hour from now
});

`getAllActivities`

获取当前所有活跃的实时活动。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { activities } = await CapgoLiveActivities.getAllActivities();
activities.forEach(activity => {
  console.log(`Activity ${activity.activityId}: ${activity.state}`);
});

`saveImage`

将图片保存到共享App Group容器中，以便在Live Activities中使用。图片必须保存到共享容器中才能从小部件扩展中访问。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { success, imageName } = await CapgoLiveActivities.saveImage({
  imageData: 'base64EncodedImageData...',
  name: 'product-image',
  compressionQuality: 0.8
});
// Use in layout with: { type: 'image', source: 'saved', value: imageName }

`removeImage`

从共享容器中删除已保存的图片。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { success } = await CapgoLiveActivities.removeImage({ name: 'product-image' });

`listImages`

列出共享容器中已保存的所有图片。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { images } = await CapgoLiveActivities.listImages();
console.log('Saved images:', images);

`cleanupImages`

从共享容器中删除所有已保存的图片。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.cleanupImages();

`startTimerSequence`

开始运动计时序列。在 iOS 上：在 Live Activity 和 Dynamic Island 中显示在 Android 上：以计时器形式显示在前台通知中

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { sequenceId } = await CapgoLiveActivities.startTimerSequence({
  title: 'HIIT Workout',
  steps: [
    { duration: 30, title: 'Jumping Jacks', subtitle: 'Warm up', color: '#FF6B00', icon: 'figure.jumprope' },
    { duration: 10, title: 'Rest', color: '#00C853', icon: 'pause.circle' },
    { duration: 45, title: 'Burpees', subtitle: 'High intensity', color: '#FF0000', icon: 'flame.fill' },
    { duration: 15, title: 'Rest', color: '#00C853', icon: 'pause.circle' },
    { duration: 45, title: 'Mountain Climbers', color: '#FF0000', icon: 'figure.run' },
    { duration: 15, title: 'Rest', color: '#00C853', icon: 'pause.circle' },
  ],
  loop: true,
  loopCount: 3,
  soundEnabled: true,
  vibrateEnabled: true,
  countdownBeeps: true,
  tapUrl: 'myapp://workout/hiit'
});

`pauseTimerSequence`

暂停计时序列。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.pauseTimerSequence({ sequenceId: 'abc123' });

`resumeTimerSequence`

恢复暂停的计时序列。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.resumeTimerSequence({ sequenceId: 'abc123' });

`stopTimerSequence`

停止并关闭计时序列。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.stopTimerSequence({ sequenceId: 'abc123' });

`skipTimerStep`

跳过当前步骤序列

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.skipTimerStep({ sequenceId: 'abc123' });

`previousTimerStep`

返回上一个步骤序列

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.previousTimerStep({ sequenceId: 'abc123' });

`getTimerState`

获取计时器序列的当前状态

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const state = await CapgoLiveActivities.getTimerState({ sequenceId: 'abc123' });
console.log(`Step ${state.currentStepIndex + 1}/${state.totalSteps}: ${state.currentStep.title}`);
console.log(`Time remaining: ${state.remainingSeconds}s`);

类型参考

`AreActivitiesSupportedResult`

检查活动是否支持的结果

export interface AreActivitiesSupportedResult {
  /** Whether Live Activities are supported on this device */
  supported: boolean;
  /** Reason if not supported */
  reason?: string;
}

`StartActivityOptions`

启动实时活动的选项。

export interface StartActivityOptions {
  /** Main activity layout (lock screen widget) */
  layout: ActivityLayout;
  /** Dynamic Island layout configuration */
  dynamicIslandLayout: DynamicIslandLayout;
  /** Activity behavior settings */
  behavior?: LiveActivitiesBehavior;
  /** Dynamic data for the activity */
  data: Record<string, unknown>;
  /** Stale date timestamp (activity becomes stale after this) */
  staleDate?: number;
  /** Relevance score for activity ordering (0-100) */
  relevanceScore?: number;
}

`StartActivityResult`

启动活动的结果。

export interface StartActivityResult {
  /** Unique activity identifier */
  activityId: string;
}

`UpdateActivityOptions`

更新实时活动的选项。

export interface UpdateActivityOptions {
  /** Activity ID to update */
  activityId: string;
  /** Updated data */
  data: Record<string, unknown>;
  /** Optional alert to show with update */
  alertConfiguration?: ActivityAlertConfiguration;
  /** Updated stale date */
  staleDate?: number;
  /** Updated relevance score */
  relevanceScore?: number;
}

`EndActivityOptions`

结束实时活动的选项。

export interface EndActivityOptions {
  /** Activity ID to end */
  activityId: string;
  /** Final data to display */
  data?: Record<string, unknown>;
  /** Dismissal policy */
  dismissalPolicy?: 'immediate' | 'default' | 'after';
  /** Dismiss after timestamp (when dismissalPolicy is 'after') */
  dismissAfter?: number;
}

`GetAllActivitiesResult`

获取所有活动的结果

export interface GetAllActivitiesResult {
  /** List of activities */
  activities: ActivityInfo[];
}

`SaveImageOptions`

保存图片的选项

export interface SaveImageOptions {
  /** Base64 encoded image data */
  imageData: string;
  /** Name to save the image as */
  name: string;
  /** JPEG compression quality (0-1, default 0.8) */
  compressionQuality?: number;
}

`SaveImageResult`

保存图片的结果

export interface SaveImageResult {
  /** Whether the save was successful */
  success: boolean;
  /** Saved image name */
  imageName: string;
}

`RemoveImageOptions`

删除图片的选项

export interface RemoveImageOptions {
  /** Name of the image to remove */
  name: string;
}

`RemoveImageResult`

移除图片的结果。

export interface RemoveImageResult {
  /** Whether the removal was successful */
  success: boolean;
}

`ListImagesResult`

列出图片的结果。

export interface ListImagesResult {
  /** List of saved image names */
  images: string[];
}

`TimerSequenceOptions`

开始定时器序列的选项。

export interface TimerSequenceOptions {
  /** Array of steps in the sequence */
  steps: TimerStep[];
  /** Overall title for the sequence (e.g., "HIIT Workout", "Tabata") */
  title?: string;
  /** Whether to loop the sequence when complete */
  loop?: boolean;
  /** Number of times to loop (if loop is true, 0 means infinite) */
  loopCount?: number;
  /** Play sound on step change (default: true) */
  soundEnabled?: boolean;
  /** Vibrate on step change (default: true) */
  vibrateEnabled?: boolean;
  /** Play countdown beeps in last 3 seconds (default: true) */
  countdownBeeps?: boolean;
  /** Deep link URL when tapping the notification/activity */
  tapUrl?: string;
  /** Keep screen on during timer (Android only, default: false) */
  keepScreenOn?: boolean;
}

真实数据来源

This page is generated from the plugin’s src/definitions.ts当公共资源API发生更改时，请重新同步。

继续从Getting Started

如果您正在使用 Getting Started 规划仪表板和API操作，请将其连接到使用@capgo/capacitor-live-activities 为native能力在使用@capgo/capacitor-live-activities中 API概述为API概述中的实现细节介绍介绍中的实现细节 API Keys 介绍中的API Keys的实现细节，以及设备设备中的实现细节。

开始入门

安装

iOS 设置

需求

1. 创建 Widget Extension

标题：2. 启用实时活动

3. 配置共享图片的 App 组

4. 配置深度链接

5. 可选：启用服务器驱动更新

原生设置清单

导入

API 概述

areActivitiesSupported

startActivity

updateActivity

endActivity

getAllActivities

saveImage

removeImage

listImages

cleanupImages

startTimerSequence

pauseTimerSequence

resumeTimerSequence

stopTimerSequence

skipTimerStep

previousTimerStep

getTimerState