跳过内容
Capgo - 为 Capacitor 应用程序提供实时更新 Capgo

Getting Started

GitHub

安装

标题为“安装”的部分

您可以使用我们的 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手动设置，安装插件并运行以下命令并遵循以下平台特定的说明:

终端窗口
bun add @capgo/capacitor-live-activities
bunx cap sync

iOS 设置

iOS 设置

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

需求

使用 iOS 16.1 或更高版本的应用目标和 Widget 扩展目标。
  • 在 iOS 设备或兼容的模拟器上进行测试。动态岛仅在支持的设备模型上可见；其他设备使用锁屏演示。
  • 确保 ActivityKit 数据（静态和动态）总和不超过 Apple 的 4 KB 限制。
  • 1. 创建一个 Widget 扩展

iOS 原生项目：

终端窗口

__CAPGO_KEEP_0__

__CAPGO_KEEP_1__
bunx cap open ios

然后：

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

必须包含一个Widget扩展 ActivityConfiguration 并在其 WidgetBundle中注册它。它必须提供每个所需的实时活动呈现:

  • 锁屏
  • 动态岛扩展
  • 动态岛紧凑的前导和尾随
  • 动态岛最小

仅添加目标是不够的。原生应用或插件必须调用ActivityKit的request、update和end API。扩展必须包含SwiftUIcode以解码和呈现与这些调用相同的 ActivityAttributes 和内容状态。将共享的ActivityKit模型添加到主应用和Widget扩展目标中。Xcode生成的实时活动模板不会自动渲染传递到此插件的JSON布局；扩展还需要兼容的原生布局渲染器。

2. 启用实时活动

标题为“2. 启用实时活动”

将以下键添加到主应用目标的 Info.plist:

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

如果项目生成其 Info.plist，添加 支持实时活动 的布尔值为 YES 在主应用目标的自定义 iOS 目标属性中

3. 配置共享图像的 App 组

标题为“3. 配置共享图像的 App 组”

仅当使用 saveImage, removeImage, listImages，或 cleanupImages，App 组才需要。该插件从主应用包标识符中派生 App 组标识符，使用以下格式：

group.<MAIN_APP_BUNDLE_ID>.liveactivities

例如，一个具有捆绑标识符的应用程序必须使用： com.example.delivery 必须使用：

group.com.example.delivery.liveactivities

在 Xcode 中，添加以下内容到主应用程序目标和 Widget Extension 目标，然后在两个目标上启用相同的标识符： Live Activity 扩展无法访问网络。下载远程图像在主应用程序中并将它们保存到共享 App Group，然后从 Live Activity 中引用它们。对于捆绑图像，还要在资产的目标成员资格中启用 Widget Extension。 4. 配置深度链接

标题：4. 配置深度链接

或计时序列时，

，在主应用程序中注册匹配的 URL 方案或 Universal Link。对于自定义方案例如 behavior.widgetUrl __CAPGO_KEEP_0__ tapUrl__CAPGO_KEEP_1__ myapp://order/12345，添加主应用目标下的方案 Info > URL 类型 设置。

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

标题为“5. 可选：启用服务器驱动更新”

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

  • 添加 推送通知 上下文：Capgo营销网站。角色：短的UI标签或导航项。消息键`push_notifications`（推送通知）。
  • 能力到主应用目标。
  • 获取ActivityKit推送令牌并将其发送到服务器。 liveactivity 通过使用的推送类型发送ActivityKit通知APNs。
  • 添加 NSSupportsLiveActivitiesFrequentUpdates 到主应用 Info.plist 只有在用例需要频繁推送更新时才添加。

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

原生设置清单

原生设置清单

在调用之前 startActivity请确认

  • NSSupportsLiveActivities 在主应用目标中已启用。
  • 小部件扩展嵌入并注册一个 ActivityConfiguration.
  • 原生ActivityKit实现和小部件扩展使用相同的 ActivityAttributes 类型。
  • 应用和 Widget 扩展部署目标是 iOS 16.1 或更高版本。
  • 在 iOS 设置中，Live 活动已启用。
  • 当使用共享图像时，匹配的 App 组已在两个目标上启用。
  • 任何由 widgetUrl 或 tapUrl 您是否考虑使用

已注册。

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

API Overview

API 概述

areActivitiesSupported

__CAPGO_KEEP_0__ 概述

检查该设备是否支持实时活动。 要求 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 容器中，以便在实时活动中使用。 图片必须保存到共享容器中才能从小部件扩展中访问。

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 活动和动态岛显示 在 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

pauseTimerSequence

停止并关闭计时器序列。

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`);

protectedTokens

类型参考

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;
}

真实数据来源

真实数据来源

本页面由插件生成 src/definitions.ts当公共API上游发生变化时，请重新同步。

继续从开始

继续从开始

如果您正在使用 开始 来规划仪表板和API操作，请将其连接到 使用@capgo/capacitor-live-activities 用于在使用@capgo/capacitor-live-activities中实现原生能力 API 介绍 为 API 介绍 的实现细节 介绍 为 介绍 的实现细节 API 密钥 为 API 密钥 的实现细节, 和 设备 为 设备 的实现细节。