Mulai Menggunakan

Instal

Anda dapat menggunakan Pengaturan Bantu AI untuk menginstal plugin. Tambahkan Capgo kemampuan ke alat AI Anda menggunakan perintah berikut:

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

Lalu gunakan prompt berikut:

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

Jika Anda lebih suka Setup Manual, instal plugin dengan menjalankan perintah-perintah berikut dan ikuti instruksi spesifik platform di bawah ini:

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

Pengaturan iOS

Pemasangan dan sinkronisasi plugin tidak menciptakan UI Aktivitas Live native. ActivityKit memerlukan Ekstensi Widget yang mendaftarkan konfigurasi Aktivitas Live sebelum dapat menampilkan apa pun. startActivity Dapat menampilkan apa saja.

Requirements

• Gunakan iOS 16.1 atau lebih baru untuk target aplikasi dan target Ekstensi Widget.
• Test on an iOS device or a compatible simulator. The Dynamic Island only appears on supported device models; other devices use the Lock Screen presentation.
• Jangan melebihi batas 4 KB data statis dan dinamis ActivityKit yang dikombinasikan.

Membuat 1. Ekstensi Widget

Buka proyek iOS native:

bunx cap open ios

Lalu:

1. Pilih File > Baru > Target.
2. Tambahkan Ekstensi Widget.
3. Aktifkan Termasuk Aktivitas Langsung.
4. Mengaktifkan Masukkan Konfigurasi Niat kecuali aplikasi juga memerlukan widget yang dapat disesuaikan.
5. Pastikan ekstensi yang dihasilkan diintegrasikan ke dalam target aplikasi utama.

Ekstensi Widget harus mengandung sebuah ActivityConfiguration dan mendaftarkannya di dalam WidgetBundlenya. Ekstensi harus menyediakan setiap presentasi Live Activity yang diperlukan:

• Layar Blokir
• Dynamic Island yang diperluas
• Dynamic Island yang padat di bagian depan dan belakang
• Dynamic Island yang minimal

Menambahkan target saja tidak cukup. Aplikasi native atau plugin harus memanggil API request, update, dan end dari ActivityKit. Ekstensi harus mengandung SwiftUI code yang dapat menerjemahkan dan menampilkan hal yang sama. ActivityAttributes dan keadaan konten yang digunakan oleh panggilan-panggilan tersebut. Termasuk model ActivityKit bersama dalam aplikasi utama dan target Widget Extension. Template Live Activity yang dihasilkan Xcode tidak secara otomatis menampilkan tata letak JSON yang dikirim ke plugin ini; ekstensi juga memerlukan renderer tata letak native yang kompatibel.

2. Aktifkan Aktivitas Langsung

Tambahkan kunci berikut ke target aplikasi utama’s Info.plist:

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

Jika proyek menghasilkan Info.plisttambahkan Aktivitas Langsung Dapat Dikontrol dengan nilai Boolean YES di bawah target properti iOS kustom aplikasi utama’s alih-alih.

3. Konfigurasi Grup Aplikasi untuk Gambar Bersama

Suatu Kelompok Aplikasi hanya diperlukan ketika menggunakan saveImage, removeImage, listImages, atau cleanupImages. Plugin ini mendapatkan identifikasi Kelompok Aplikasi dari identifikasi bundle aplikasi utama menggunakan format ini tepatnya:

group.<MAIN_APP_BUNDLE_ID>.liveactivities

Contoh, aplikasi dengan identifikasi bundle com.example.delivery harus digunakan:

group.com.example.delivery.liveactivities

Dalam Xcode, tambahkan kemampuan Kelompok Aplikasi kemampuan untuk target aplikasi utama dan target Widget Extension, kemudian aktifkan identifikasi yang sama pada kedua target tersebut.

Ekstensi Aktivitas Langsung tidak dapat mengakses jaringan. Unduh gambar remote di aplikasi utama dan simpan mereka ke Kelompok Aplikasi yang dipisahkan sebelum mengacu mereka dari Aktivitas Langsung. Untuk gambar yang dibundel, aktifkan juga Ekstensi Widget pada anggota target asset.

4. Konfigurasi Tautan dalam

Menggunakan behavior.widgetUrl atau urutan timer tapUrlmendaftarkan skema URL yang sesuai atau Universal Link di aplikasi utama. Untuk skema kustom seperti myapp://order/12345tambahkan skema di bawah pengaturan target aplikasi utama di Pengaturan > Jenis URL .

5. Opsional: Aktifkan Update yang Dijalankan oleh Server

Pemberitahuan Push Tidak Diperlukan untuk Update Lokal yang Diinisiasi oleh Aplikasi. Untuk memulai, mengupdate, atau mengakhiri Aktivitas Hidup dari server:

• Tambahkan Pemberitahuan Push kemampuan ke aplikasi target utama.
• Dapatkan token push ActivityKit dan kirim mereka ke server.
• Kirim pemberitahuan ActivityKit melalui APNs menggunakan jenis push. liveactivity Tambahkan
• Add NSSupportsLiveActivitiesFrequentUpdates Kembali ke aplikasi utama Info.plist Hanya ketika kasus penggunaan memerlukan pembaruan push yang sering.

ActivityKit push tokens are separate from standard user-notification device tokens. Enabling the Push Notifications capability alone is not sufficient; server-driven updates require native token handling and an APNs backend.

Judul bagian “Daftar Periksa Pengaturan Nativ”

Sebelum melakukan panggilan startActivityPeriksa bahwa:

• NSSupportsLiveActivities dapat diaktifkan pada target aplikasi utama.
• Widget Extension terintegrasi dan mendaftarkan diri sebagai ActivityConfiguration.
• Implementasi Aktivitas Kit asli dan Widget Extension menggunakan tipe yang sama. ActivityAttributes type.
• Aplikasi dan target pengembangan Widget Extension adalah iOS 16.1 atau lebih baru.
• Aktivitas Langsung diaktifkan untuk aplikasi di Pengaturan iOS.
• Grup Aplikasi yang Sesuai diaktifkan pada kedua target saat menggunakan gambar yang dibagikan.
• URL scheme kustom yang digunakan oleh widgetUrl or tapUrl Terdaftar.

Import

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

Ringkasan API

areActivitiesSupported

Periksa apakah Aktivitas Langsung mendukung perangkat ini. Memerlukan iOS 16.1+ dan dukungan perangkat.

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

Mulai Aktivitas Langsung baru dengan tata letak dan data yang ditentukan.

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

Perbarui Aktivitas Langsung yang ada dengan data baru.

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

Berhenti Aktivitas Langsung.

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

Dapatkan semua Aktivitas Langsung yang Aktif Sekarang.

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

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

saveImage

Simpan gambar ke kontainer App Group bersama untuk digunakan dalam Aktivitas Langsung. Gambar harus disimpan ke kontainer bersama untuk dapat diakses dari ekstensi widget.

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

Hapus gambar yang disimpan dari kontainer bersama.

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

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

listImages

Daftar semua gambar yang disimpan di kontainer bersama.

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

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

cleanupImages

Hapus semua gambar yang disimpan dari kontainer bersama.

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

await CapgoLiveActivities.cleanupImages();

startTimerSequence

Mulai urutan penghitung untuk olahraga/olahraga. Di iOS: Tampil di Aktivitas Langsung dan Dynamic Island Di Android: Tampil sebagai peringatan latar depan dengan penghitung

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

Jeda urutan penghitung.

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

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

resumeTimerSequence

Mulai ulang urutan timer yang terhenti.

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

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

stopTimerSequence

Berhenti dan tutup urutan timer.

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

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

skipTimerStep

Lewati ke langkah berikutnya dalam urutan.

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

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

previousTimerStep

Kembali ke langkah sebelumnya dalam urutan.

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

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

getTimerState

Peroleh status saat ini dari suatu urutan timer.

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

Referensi Tipe

AreActivitiesSupportedResult

Hasil pengecekan apakah aktivitas didukung.

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

StartActivityOptions

Opsi untuk memulai Aktivitas Langsung.

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

Hasil memulai suatu kegiatan.

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

UpdateActivityOptions

Opsi untuk memperbarui suatu Aktivitas Langsung.

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

Opsi untuk mengakhiri suatu Aktivitas Langsung.

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

Hasil getAllActivities.

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

SaveImageOptions

Opsi untuk menyimpan sebuah gambar.

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

Hasil menyimpan sebuah gambar.

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

RemoveImageOptions

Opsi untuk menghapus sebuah gambar.

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

RemoveImageResult

Hasil menghapus sebuah gambar.

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

ListImagesResult

Hasil daftar gambar.

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

TimerSequenceOptions

Pilihan untuk memulai urutan timer.

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

Sumber Kebenaran

Halaman ini dihasilkan dari plugin’s src/definitions.ts. Re-run sinkronisasi ketika API publik berubah di atas.

Teruskan dari Getting Started

Jika Anda menggunakan Mulai Berjalan untuk merencanakan dashboard dan API operasi, hubungkannya dengan Menggunakan @capgo/capacitor-aktivitas-hidup untuk kemampuan asli dalam Menggunakan @capgo/capacitor-aktivitas-hidup Ringkasan API untuk detail implementasi dalam Ringkasan API Pendahuluan untuk detail implementasi dalam Pendahuluan Kunci API untuk detail implementasi dalam Kunci API, dan Perangkat Untuk detail implementasi di perangkat.