Live Activities plugin Capacitor

Menggunakan @capgo/capacitor-live-activities

Interface plugin Capacitor Live Activities untuk mengelola iOS Live Activities.

Instal

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

Setup iOS

Memasang dan menyinkronkan plugin tidak membuat UI Live Activity native. Sebelum memanggil startActivity, konfigurasikan ActivityKit di Xcode:

1. Jalankan bunx cap open ios.
2. Tambahkan Ekstensi Widget target dan aktifkan Sertakan Live Activity.
3. Atur deployment target aplikasi dan Widget Extension ke iOS 16.1 atau lebih baru.
4. Pastikan extension sudah tertanam di aplikasi utama.
5. Tetap ActivityConfiguration tetap terdaftar di extension WidgetBundle, dengan tampilan Lock Screen dan semua presentasi Dynamic Island.
6. Tambah NSSupportsLiveActivities ke target aplikasi utama Info.plist.

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

Menambahkan target saja tidak cukup. Aplikasi native atau plugin harus memanggil API request, update, dan end dari ActivityKit. Widget Extension harus berisi SwiftUI code yang dapat melakukan decode dan render hal yang sama ActivityAttributes dan content state yang digunakan oleh panggilan tersebut. Sertakan model ActivityKit yang dibagikan di kedua target aplikasi utama dan Widget Extension. Template Live Activity buatan Xcode tidak secara otomatis merender layout JSON yang dikirim ke plugin ini; extension juga memerlukan renderer layout native yang kompatibel.

Gambar Bersama

Saat menggunakan metode manajemen gambar, tambahkan App Groups capability ke target aplikasi utama dan Widget Extension. Aktifkan grup yang sama pada kedua target menggunakan identifier yang tepat sesuai ekspektasi plugin:

group.<MAIN_APP_BUNDLE_ID>.liveactivities

Ekstensi Live Activity tidak dapat mengakses jaringan. Download gambar remote di aplikasi utama, simpan ke App Group bersama dengan saveImage, lalu referensikan gambar yang tersimpan tersebut dari layout. Asset yang dibundle juga harus termasuk dalam target Widget Extension.

Deep Links dan Push Updates

• Daftarkan skema URL kustom apa pun yang digunakan oleh behavior.widgetUrl atau tapUrl di bawah target aplikasi utama Info > Tipe URL di pengaturan.
• Untuk update berbasis server, tambahkan Notifikasi Push capability dan implementasikan penanganan push-token ActivityKit dengan APNs.
• Tambah NSSupportsLiveActivitiesFrequentUpdates hanya jika aplikasi memerlukan push update ActivityKit yang sering.

Mengaktifkan capability Push Notifications saja tidak cukup; update berbasis server memerlukan penanganan token native dan backend APNs.

ActivityKit membatasi gabungan data Live Activity statis dan dinamis sebesar 4 KB. Dynamic Island hanya muncul pada model perangkat yang mendukung; perangkat lain menggunakan tampilan Lock Screen.

Apa yang Diekspos Plugin Ini

• areActivitiesSupported - Cek apakah Live Activities didukung di perangkat ini. Memerlukan iOS 16.1+ dan dukungan perangkat.
• startActivity - Mulai Live Activity baru dengan layout dan data yang ditentukan.
• updateActivity - Update Live Activity yang sudah ada dengan data baru.
• endActivity - Akhiri Live Activity.

Contoh Penggunaan

areActivitiesSupported

Cek apakah Live Activities didukung di 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 Live Activity baru dengan layout 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

Update Live Activity yang sudah 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

Akhiri Live Activity.

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

Referensi Lengkap

• GitHub: https://github.com/Cap-go/capacitor-live-activities/
• Dokumentasi: /docs/plugins/live-activities/

Lanjutkan dari Menggunakan @capgo/capacitor-live-activities

Jika Anda menggunakan Menggunakan @capgo/capacitor-live-activities untuk merencanakan perilaku media dan antarmuka native, hubungkan dengan @capgo/capacitor-live-activities untuk detail implementasi di @capgo/capacitor-live-activities, Panduan Memulai untuk detail implementasi di Getting Started, Menggunakan @capgo/capacitor-video-player untuk kapabilitas native saat menggunakan @capgo/capacitor-video-player, @capgo/capacitor-video-player untuk detail implementasi di @capgo/capacitor-video-player, dan Menggunakan @capgo/capacitor-native-navigation untuk kapabilitas native saat menggunakan @capgo/capacitor-native-navigation.