Mulai Berjalan

Pasang

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

Pengaturan iOS

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

Persyaratan

• Gunakan iOS 16.1 atau lebih baru untuk target aplikasi dan target Ekstensi Widget.
• Tes pada perangkat iOS atau simulator yang kompatibel. Dynamic Island hanya muncul pada model perangkat yang didukung; perangkat lain menggunakan presentasi Layar Kunci.
• Tetapkan data statis dan dinamis ActivityKit di bawah batas 4 KB 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 Langsung.
4. Matikan Termasuk Konfigurasi Niat kecuali aplikasi juga memerlukan widget yang dapat dikonfigurasi.
5. Pastikan ekstensi yang dihasilkan diintegrasikan ke target aplikasi utama.

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

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

Menambahkan target sendiri tidak cukup. Aplikasi asli atau plugin harus memanggil API request, update, dan end dari ActivityKit. Ekstensi harus berisi SwiftUI code yang dapat menerjemahkan dan menampilkan yang sama ActivityAttributes dan status konten yang digunakan oleh panggilan tersebut. Termasuk model ActivityKit yang dapat dibagikan di kedua target aplikasi utama dan Ekstensi Widget. Template Aktivitas Live yang dihasilkan Xcode tidak secara otomatis menampilkan layout JSON yang dikirimkan ke plugin ini; ekstensi juga memerlukan renderer layout native yang kompatibel.

2. Aktifkan Aktivitas Langsung

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

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

Jika proyek menghasilkan generasinya Info.plist, tambahkan Dukungan Aktivitas Langsung dengan nilai Boolean YES di bawah target properti iOS utama’s custom

3. Konfigurasi App Group untuk Gambar Bersama

Grup Aplikasi hanya diperlukan ketika menggunakan saveImage, removeImage, listImagesatau cleanupImagesSalin ke clipboard

group.<MAIN_APP_BUNDLE_ID>.liveactivities

harus menggunakan: com.example.delivery Salin ke clipboard

group.com.example.delivery.liveactivities

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

4. Konfigurasi Tautan dalam

Judul bagian “4. Konfigurasi Tautan dalam”

When menggunakan behavior.widgetUrl atau sebuah urutan timer tapUrl, daftarkan skema URL yang sesuai atau Universal Link di aplikasi utama. Untuk skema kustom seperti myapp://order/12345, tambahkan skema di bawah pengaturan target aplikasi utama Info > Jenis URL .

5. Opsional: Aktifkan Pengaturan Server-Driven

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

• Tambahkan Pemberitahuan Push ke target aplikasi utama.
• Mengambil token push ActivityKit dan kirimkan ke server.
• Mengirimkan pemberitahuan ActivityKit melalui APNs menggunakan jenis push. liveactivity Tambahkan
• ke aplikasi utama NSSupportsLiveActivitiesFrequentUpdates hanya ketika kasus penggunaan memerlukan pembaruan push yang sering. Info.plist Token push ActivityKit berbeda dari token perangkat-notifikasi pengguna standar. Mengaktifkan kemampuan Pemberitahuan Push sendiri tidak cukup; pembaruan yang dikendalikan oleh server memerlukan pengelolaan token asli dan backend APNs.

Daftar Periksa Pengaturan Nativ

Judul bagian “Daftar Periksa Pengaturan Nativ”

, pastikan bahwa: startActivityaktif pada target aplikasi utama.

• NSSupportsLiveActivities Mengambil token push ActivityKit dan kirimkan ke server.
• Ekstensi Widget diintegrasikan dan mendaftarkan diri sebagai ActivityConfiguration.
• Implementasi Aktivitas Nativ dan Ekstensi Widget menggunakan ActivityAttributes jenis.
• Target pengembangan aplikasi dan Ekstensi Widget adalah iOS 16.1 atau lebih baru.
• Aktivitas Langsung diaktifkan untuk aplikasi di Pengaturan iOS.
• Grup Aplikasi yang sesuai diaktifkan pada kedua target ketika menggunakan gambar yang dibagikan.
• Apapun skema URL khusus yang digunakan oleh widgetUrl atau tapUrl terdaftar.

Import

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

API Pengenalan

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 sedang berlangsung.

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 timer untuk olahraga/olahraga. 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

Tangguhkan urutan timer.

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

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

resumeTimerSequence

Tetapkan ulang urutan timer yang terhenti.

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

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

stopTimerSequence

Hentikan dan tutup urutan timer.

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

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

skipTimerStep

Lompat 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 status saat ini dari sebuah 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 dari memulai kegiatan.

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

UpdateActivityOptions

Opsi untuk memperbarui 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 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 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 gambar.

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

RemoveImageOptions

Opsi menghapus 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 menampilkan daftar gambar.

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

TimerSequenceOptions

Pilihan untuk memulai suatu 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 sync ketika API publik berubah di atas.

Lanjutkan dari Getting Started

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