Getting Started

Instalasi

Kamu bisa menggunakan Setup Bantuan AI untuk menginstal plugin ini. Tambahkan Capgo kemampuan ke alat AI kamu 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 kamu 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

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

Judul Bagian: “Persyaratan”

• Uji coba pada perangkat iOS atau simulator yang kompatibel. Layar Dinamis hanya muncul pada model perangkat yang didukung; perangkat lain menggunakan presentasi Layar Kunci.
• Hindari melebihi batas ukuran data statis dan dinamis ActivityKit 4 KB yang ditetapkan oleh Apple.
• 1. Buat Ekstensi Widget

Judul Bagian: “1. Buat Ekstensi Widget”

Tampilan Jendela Terminal

bunx cap open ios

Lalu:

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

Widget Extension harus mengandung sebuah ActivityConfiguration dan mendaftarkannya di WidgetBundle. Ia harus menyediakan setiap presentasi Aktivitas Langsung yang diperlukan:

• Lock Screen
• Dynamic Island yang diperluas
• Dynamic Island yang padat di sisi kiri dan kanan
• Dynamic Island yang minimal

Menambahkan target tunggal tidak cukup. Aplikasi asli atau plugin harus memanggil API request, update, dan end dari ActivityKit. Ekstensi harus mengandung SwiftUI code yang dapat menerjemahkan dan menampilkan konten yang sama ActivityAttributes dan status konten yang digunakan oleh panggilan tersebut. Termasuk model Aktivitas Langsung yang dipisahkan di kedua target aplikasi utama dan Widget Extension. Template Live Activity yang dihasilkan Xcode tidak secara otomatis menampilkan tata letak JSON yang dikirimkan 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.plistnya, tambahkan Mendukung Aktivitas Langsung dengan nilai Boolean YES di bawah properti target iOS utama yang disesuaikan

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 dengan format yang tepat ini:

group.<MAIN_APP_BUNDLE_ID>.liveactivities

Contoh, aplikasi dengan identifier paket com.example.delivery harus menggunakan:

group.com.example.delivery.liveactivities

Pada Xcode, tambahkan kemampuan App Groups ke target aplikasi utama dan target Ekstensi Widget, kemudian aktifkan identifier yang sama pada kedua target.

Ekstensi Aktivitas Hidup tidak dapat mengakses jaringan. Unduh gambar remote di aplikasi utama dan simpan ke App Group bersama sebelum mengacu ke mereka dari Aktivitas Hidup. Untuk gambar yang dibundel, juga aktifkan Ekstensi Widget pada anggota target aset.

4. Konfigurasi Tautan dalam-Depth

Menggunakan behavior.widgetUrl atau urutan timer tapUrl, daftarkan skema URL yang sesuai atau Tautan Universal di aplikasi utama. Untuk skema kustom seperti myapp://order/12345Tambahkan skema di bawah target aplikasi utama. Info > Tipe URL Pengaturan.

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 Langsung dari server:

• Tambahkan kemampuan Pemberitahuan Push context: Halaman/area: Situs web pemasaran Capgo. Peran: Label UI pendek atau item navigasi. Kunci pesan `push_notifications` (Pemberitahuan Push).
• ke target aplikasi utama.
• Olehkan token push ActivityKit dan kirimkan ke server. liveactivity Kirimkan pemberitahuan ActivityKit melalui APNs menggunakan jenis push.
• Tambahkan NSSupportsLiveActivitiesFrequentUpdates ke aplikasi utama Info.plist hanya ketika kasus penggunaan memerlukan pembaruan push yang sering.

Token push ActivityKit berbeda dari token perangkat-notifikasi pengguna standar. Mengaktifkan kemampuan Push Notifications saja tidak cukup; pembaruan yang dikendalikan server memerlukan pengelolaan token asli dan backend APNs.

Daftar Periksa Pengaturan Nativ

Sebelum memanggil startActivity, pastikan bahwa:

• NSSupportsLiveActivities dihubungkan pada target aplikasi utama.
• Ekstensi Widget terintegrasi dan mendaftarkan sebuah ActivityConfiguration.
• Implementasi ActivityKit natif dan Ekstensi Widget menggunakan tipe yang sama. ActivityAttributes sebelum memanggil fungsi APNs.
• Aplikasi dan target ekstensi Widget telah diterapkan pada iOS 16.1 atau lebih lanjut.
• Live Activities diaktifkan untuk aplikasi di Pengaturan iOS.
• Grup Aplikasi yang sesuai diaktifkan pada kedua target ketika menggunakan gambar yang dibagikan.
• Apapun skema URL kustom yang digunakan oleh widgetUrl atau tapUrl Apakah Anda ingin meninggalkan Capgo dan menggunakan alternatif lain seperti Appflow atau Capawesome?

Apakah Anda ingin meninggalkan Capgo dan menggunakan alternatif lain seperti Appflow?

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

API Overview

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

Akhir 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

Peroleh semua kegiatan hidup yang aktif saat ini.

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 Kegiatan Hidup. 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 yang dibagikan.

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

await CapgoLiveActivities.cleanupImages();

startTimerSequence

Mulai urutan timer untuk olahraga/sukan. Di iOS: Tampil di Aktivitas Hidup 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

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 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 Periksa Jika Aktivitas Dapat Dibuka.

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

StartActivityOptions

Opsi untuk memulai Aktivitas 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 memulai aktivitas.

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

UpdateActivityOptions

Opsi untuk memperbarui Aktivitas 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

Pilihan 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 dari getAllActivities.

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

SaveImageOptions

Pilihan 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 dari menyimpan gambar.

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

RemoveImageOptions

Pilihan untuk menghapus gambar.

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

RemoveImageResult

Hasil penghapusan 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.tsRe-run sinkronisasi 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 di Menggunakan @capgo/capacitor-live-activities, API Pengenalan untuk detail implementasi di API Pengenalan, Pendahuluan untuk detail implementasi di Pendahuluan, API Kunci untuk detail implementasi di API Kunci, dan Perangkat untuk detail implementasi di Perangkat.