Mulai Berjalan

Pasang

Anda dapat menggunakan Setup AI-Assisted kami 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

Kemudian 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

Setup iOS

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

Persyaratan

• Gunakan iOS 16.1 atau lebih baru untuk target aplikasi dan target Widget Extension.
• Lakukan tes pada perangkat iOS atau simulator yang kompatibel. Iseng-Iseng Dinamis hanya muncul pada model perangkat yang didukung; perangkat lain menggunakan presentasi Layar Kunci.
• Tetapkan data Aktivitas Kit statis dan dinamis kombinasi di bawah batas 4 KB yang ditetapkan oleh Apple.

1. Buat Ekstensi Widget

Buka proyek iOS native:

bunx cap open ios

Lalu:

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

Ekstensi Widget harus berisi sebuah ActivityConfiguration dan mendaftarkannya di WidgetBundle. Harus menyediakan setiap presentasi Aktivitas Hidup yang diperlukan:

• Lock Screen
• Dynamic Island yang diperluas
• Dynamic Island yang kompak di bagian depan dan belakang
• Dynamic Island minimal

Tidak cukup hanya menambahkan target tersebut. Aplikasi asli atau plugin harus memanggil API ActivityKit untuk request, update, dan end. Ekstensi harus memiliki SwiftUI code yang dapat menguraikan dan menampilkan konten yang sama ActivityAttributes dan status konten yang digunakan oleh panggilan tersebut. Termasuk model ActivityKit yang dibagikan di kedua target aplikasi utama dan Ekstensi Widget. 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.plist, tambahkan Supports Aktivitas Langsung dengan nilai Boolean dari YES di bawah properti target iOS utama yang diatur secara khusus

3. Konfigurasi Grup Aplikasi untuk Gambar Bersama

Grup Aplikasi hanya diperlukan ketika menggunakan saveImage, removeImage, listImages, atau cleanupImages. Plugin ini mendapatkan identifikasi Grup Aplikasi dari identifikasi bundle aplikasi utama menggunakan format ini secara tepat:

group.<MAIN_APP_BUNDLE_ID>.liveactivities

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

group.com.example.delivery.liveactivities

In Xcode, tambahkan kemampuan "App Groups" pada target aplikasi utama dan target Widget Extension, kemudian aktifkan identifikasi yang sama pada kedua target. App Groups Ekstensi Aktivitas Langsung tidak dapat mengakses jaringan. Unduh gambar remote di aplikasi utama dan simpan ke App Group bersama sebelum mengacu ke mereka dari Aktivitas Langsung. Untuk gambar yang dibundel, aktifkan juga Widget Extension pada anggota target aset.

4. Konfigurasi Tautan dalam

Bagian berjudul –4. Konfigurasi Tautan dalam”

atau urutan timer behavior.widgetUrl , daftarkan skema URL yang sesuai atau Tautan Universal di aplikasi utama. Untuk skema kustom seperti tapUrl, tambahkan skema di pengaturan –Info > Tipe URL” target aplikasi utama. myapp://order/123454 Konfigurasi Tautan

5. Opsional: Aktifkan Perbaruan yang Dijalankan oleh Server

Pemberitahuan Push tidak diperlukan untuk perbaruan lokal yang diinisiasi oleh aplikasi. Untuk memulai, mengupdate, atau mengakhiri Aktivitas Langsung dari server:

• Tambahkan Pemberitahuan Push ke target aplikasi utama.
• Peroleh token pemberitahuan ActivityKit dan kirimkan ke server.
• Kirimkan pemberitahuan ActivityKit melalui APNs menggunakan liveactivity jenis pemberitahuan.
• Tambahkan NSSupportsLiveActivitiesFrequentUpdates ke aplikasi utama Info.plist hanya ketika kasus penggunaan memerlukan perbaruan push yang sering.

Token push Aktivitas Kit berbeda dari token perangkat-notifikasi standar. Mengaktifkan kemampuan Notifikasi Push sendiri tidak cukup; pembaruan yang dikendalikan oleh server memerlukan pengelolaan token asli dan backend APNs.

Daftar Periksa Pengaturan Asli

pastikan bahwa: startActivityaktif pada target aplikasi utama.

• NSSupportsLiveActivities Ekstensi Widget diintegrasikan dan mendaftarkan sebuah
• Pengimplementasian Aktivitas Asli dan Ekstensi Widget menggunakan jenis yang sama. ActivityConfiguration.
• aplikasi dan target pengembangan Ekstensi Widget adalah iOS 16.1 atau lebih baru. ActivityAttributes Aktivitas Langsung diaktifkan untuk aplikasi di Pengaturan iOS.
• Grup Aplikasi yang sesuai diaktifkan pada kedua target ketika menggunakan gambar yang dibagikan.
• __CAPGO_KEEP_0__
• __CAPGO_KEEP_0__
• Apapun skema URL khusus yang digunakan oleh widgetUrl atau tapUrl terdaftar.

Import

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

API Ringkasan

areActivitiesSupported

Periksa jika 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 kegiatan hidup baru dengan tata letak yang ditentukan dan data.

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 kegiatan hidup 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

Akhirkan kegiatan hidup.

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 kegiatan hidup yang sedang aktif.

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

Tampilkan 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 sebuah urutan timer untuk olahraga/sukan. Di iOS: Tampil di Aktivitas Langsung dan Dynamic Island Di Android: Tampil sebagai peringatan latar depan dengan timer

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

Berhenti timer urutan.

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

Lompati 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

Dapatkan keadaan saat ini dari 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 dari pengecekan apakah kegiatan didukung.

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

StartActivityOptions

Opsi untuk memulai kegiatan hidup.

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 kegiatan.

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

UpdateActivityOptions

Opsi untuk memperbarui kegiatan hidup.

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 kegiatan hidup.

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 dari 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 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

Opsi 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

This page is generated from the plugin’s src/definitions.tsRe-run the sync when the public API changes upstream.

Teruskan dari Getting Started

Jika Anda menggunakan Getting Started untuk merencanakan dashboard dan API operasi, hubungkannya dengan Menggunakan @capgo/capacitor-live-aktivitas untuk kemampuan asli dalam Menggunakan @capgo/capacitor-live-aktivitas, Ringkasan API untuk detail implementasi dalam Ringkasan API, Pendahuluan untuk detail implementasi di Introduction, API Kunci untuk detail implementasi di API Kunci, dan Perangkat untuk detail implementasi di Perangkat.