Cara Menggunakan Apple Intelligence di Aplikasi Capacitor

Untuk menggunakan Apple Intelligence di aplikasi Capacitor, instal @capgo/capacitor-llm, panggil setModel({ path: 'Apple Intelligence' }), cek getReadiness(), lalu buat chat dan stream balasan melalui textFromAi event. Di balik layar, plugin ini menggunakan framework Foundation Models milik Apple yang diperkenalkan di iOS 26, yang menjalankan model bahasa on-device Apple tanpa API key, tanpa biaya per request, dan tanpa data yang keluar dari ponsel.

Panduan ini membahas fitur framework, persyaratan perangkat, integrasi TypeScript lengkap, context window 4.096-token, error handling, catatan App Review, dan cara menjalankan code yang sama di Android.

Apa yang ditawarkan Apple Intelligence bagi developer aplikasi

Dengan iOS 26, Apple membuka on-device foundation model miliknya untuk aplikasi pihak ketiga melalui Foundation Models framework. Di Swift, Anda bekerja dengan SystemLanguageModel dan LanguageModelSession. Plugin ini membungkusnya agar code web Anda bisa menggunakannya:

Model ini memiliki sekitar 3 miliar parameter. Model ini bagus untuk meringkas, menulis ulang, ekstraksi, klasifikasi, dan pembuatan teks pendek. Ini bukan pengganti model cloud besar untuk pertanyaan pengetahuan terbuka, dan Apple menyatakan hal itu dalam panduannya sendiri. Rancang fitur seputar teks yang sudah dimiliki pengguna.

Persyaratan perangkat dan OS

Jika proyek Anda masih bisa build dengan Xcode versi lama, lihat Persyaratan Xcode 26 dari Apple untuk app Capacitor. Minimum deployment target aplikasi Anda tidak perlu diubah. Plugin ini mendukung iOS 15 ke atas dan hanya mengakses Foundation Models pada iOS 26.

Install plugin

bun add @capgo/capacitor-llm
bunx cap sync ios

Gunakan plugin 8.x dengan Capacitor 8. Tidak perlu key Info.plist atau entitlement untuk Apple Intelligence. Jika Anda masih menggunakan Capacitor 7, maka panduan upgrade Capacitor 8 harus dilakukan terlebih dahulu. Dokumentasi referensi: /docs/plugins/llm/.

Langkah 1: Pilih model dan cek ketersediaan

setModel({ path: 'Apple Intelligence' }) memilih model sistem dan langsung resolve. Ketersediaan aktual berasal dari getReadiness(), yang memetakan enum ketersediaan Apple ke string yang mudah dibaca:

import { Capacitor } from '@capacitor/core';
import { CapgoLLM } from '@capgo/capacitor-llm';

export type AIState = 'ready' | 'enable-in-settings' | 'preparing' | 'unsupported';

export async function initAppleIntelligence(): Promise<AIState> {
  if (Capacitor.getPlatform() !== 'ios') return 'unsupported';

  await CapgoLLM.setModel({ path: 'Apple Intelligence' });
  const { readiness } = await CapgoLLM.getReadiness();

  if (readiness === 'ready') return 'ready';
  if (readiness.includes('not enabled')) return 'enable-in-settings';
  if (readiness.includes('not ready')) return 'preparing';
  return 'unsupported';
}

Cek kembali saat aplikasi kembali ke foreground. Pengguna sering mengaktifkan Apple Intelligence setelah melihat petunjuk Anda, dan pengunduhan model bisa selesai saat aplikasi Anda sedang di background.

import { App } from '@capacitor/app';

App.addListener('appStateChange', async ({ isActive }) => {
  if (isActive) updateAIState(await initAppleIntelligence());
});

Langkah 2: Buat chat dengan instruksi

Satu chat dipetakan ke satu LanguageModelSession, yang menyimpan riwayat percakapan. Bagian yang diketik createChat() tidak memerlukan opsi, jadi masukkan instruksi Anda di awal pesan pertama:

const INSTRUCTIONS =
  'You summarize meeting notes. Reply with at most 5 bullet points. ' +
  'Keep names and dates exactly as written. Do not add information.';

const { id: chatId } = await CapgoLLM.createChat();

Gunakan satu chat per tugas. Chat yang terus bertambah ukurannya pada akhirnya akan mencapai batas konteks yang dijelaskan di bawah.

Langkah 3: Stream respons ke UI

Di iOS, setiap textFromAi event membawa snapshot respons sejauh ini, karena begitulah cara Foundation Models melakukan streaming. Di Android dengan Gemini Nano, event hanya membawa teks baru. Helper ini menangani keduanya dan memberikan hasil teks akhir:

import { CapgoLLM } from '@capgo/capacitor-llm';

function mergeChunk(current: string, chunk: string) {
  return chunk.startsWith(current) ? chunk : current + chunk;
}

export async function ask(chatId: string, message: string, onText: (t: string) => void) {
  let text = '';
  let finish!: (value: string) => void;
  let fail!: (error: Error) => void;
  const done = new Promise<string>((resolve, reject) => {
    finish = resolve;
    fail = reject;
  });

  const handles = await Promise.all([
    CapgoLLM.addListener('textFromAi', (e) => {
      if (e.chatId !== chatId) return;
      text = mergeChunk(text, e.text);
      onText(text);
    }),
    CapgoLLM.addListener('aiFinished', (e) => {
      if (e.chatId === chatId) finish(text);
    }),
    CapgoLLM.addListener('generationError', (e) => {
      if (!e.chatId || e.chatId === chatId) fail(new Error(e.error));
    }),
  ]);

  try {
    await CapgoLLM.sendMessage({ chatId, message });
    return await done;
  } finally {
    await Promise.all(handles.map((h) => h.remove()));
  }
}

Menggabungkannya: ringkas catatan di perangkat

export async function summarizeNotes(notes: string, render: (t: string) => void) {
  const state = await initAppleIntelligence();
  if (state !== 'ready') throw new Error(`AI unavailable: ${state}`);

  const { id } = await CapgoLLM.createChat();
  const prompt = `${INSTRUCTIONS}\n\nNotes:\n${notes.slice(0, 8000)}\n\nSummary:`;
  return ask(id, prompt, render);
}

Panduan slice adalah cara kasar untuk mencegah input yang terlalu besar. Pendekatan yang lebih baik adalah meringkas dokumen panjang dalam potongan (chunks), lalu meringkas ringkasan tersebut, masing-masing dalam chat baru.

Dalam komponen framework, nonaktifkan tombol saat ask sedang berjalan. Plugin akan menolak sendMessage kedua pada chat yang sama dengan pesan “chat sedang merespons, harap tunggu sebelum mengajukan pertanyaan baru”.

Context window sebesar 4.096 token

Model on-device memiliki context window sebesar 4.096 token. Semuanya dihitung: instruksi, setiap giliran chat sebelumnya, prompt baru, dan respons yang sedang dibuat. Jika sesi melebihi batas, Foundation Models akan memunculkan error “exceeded context window size”, yang akan muncul sebagai generationError event dan yang di-reject sendMessage.

Aturan praktis:

• Satu chat per tugas, bukan satu chat per layar.
• Berikan instruksi yang singkat dan spesifik.
• Untuk chat multi-turn, mulai chat baru saat percakapan sudah terlalu panjang dan sertakan ringkasan singkat dari percakapan sebelumnya.
• Minta output yang ringkas. Jawaban panjang menggunakan kuota yang sama.

Menyesuaikan output

Pada jalur Apple Intelligence, plugin menggunakan pengaturan generasi default sistem. temperature, topk, dan maxTokens di setModel berlaku untuk path model LiteRT-LM dan MediaPipe kustom. Untuk mengarahkan model Apple, andalkan prompt: sebutkan seberapa panjang jawabannya, tentukan format (bullet, JSON, satu kalimat), dan sertakan satu contoh singkat jika formatnya penting.

code yang sama di Android

Hanya pemilihan model yang berubah:

const path = Capacitor.getPlatform() === 'ios' ? 'Apple Intelligence' : 'Gemini Nano';
await CapgoLLM.setModel({ path });

Di Android, setModel ditolak saat Gemini Nano tidak tersedia, dan Anda bisa melakukan fallback ke model Gemma yang bisa diunduh melalui plugin yang sama. Detailnya ada di cara menggunakan Gemini Nano di aplikasi Capacitor.

Pengujian

• Perangkat fisik: jalur yang andal. Gunakan iPhone yang didukung di iOS 26 dengan Apple Intelligence aktif.
• Simulator: model dapat digunakan jika Mac host menjalankan macOS 26 di Apple silicon dengan Apple Intelligence aktif. Perilaku dan kecepatannya berbeda dari ponsel, jadi pastikan di hardware.
• Kondisi tidak didukung: uji dengan Apple Intelligence dimatikan untuk mengecek UI “enable in Settings” Anda, dan di iPhone atau versi iOS yang lebih lama untuk memastikan fitur tersebut disembunyikan dengan rapi.

App Review dan privasi

Prompt dan respons tetap di perangkat, jadi generasi on-device sendiri tidak menambah pengumpulan data ke label privasi Anda. Dua hal masih jadi tanggung jawab Anda:

1. Apple menerbitkan persyaratan penggunaan yang dapat diterima untuk framework Foundation Models. Baca sebelum rilis, terutama untuk fitur yang menghasilkan konten yang ditampilkan ke pengguna lain.
2. Model ini punya guardrails bawaan dan mungkin menolak beberapa prompt atau output. Anggap penolakan sebagai hasil yang normal dan tampilkan pesan yang jelas.

Karena prompt adalah string biasa di code web Anda, Anda bisa menyempurnakannya setelah peluncuran dengan Live updates Capgo daripada menunggu build App Store baru. Perubahan pada code native, termasuk upgrade plugin, tetap butuh rilis store, yang bisa Anda build di cloud dengan Build Capgo.

Error umum dan solusinya

Kesimpulan

Apple Intelligence menghadirkan model bahasa gratis, privat, dan offline ke setiap iPhone yang memenuhi syarat di iOS 26, dan aplikasi Capacitor dapat menggunakannya hanya dengan beberapa baris TypeScript. Pilih modelnya, batasi UI pada getReadiness(), simpan setiap tugas dalam chat singkat tersendiri, stream snapshot ke UI, dan tangani penolakan serta error konteks sebagai hasil normal. Untuk ulasan lebih luas tentang merilis fitur AI di aplikasi hybrid, baca mengapa Capacitor cocok untuk aplikasi mobile AI.