Tổng quan về JS APIs

Tại sao cần JS APIs?

AI App chạy bên trong host (V-App, ChatGPT, ...) dưới dạng iframe. Mỗi host cung cấp một bộ API riêng để widget tương tác với nền tảng:

Host	Global object	Ví dụ
ChatGPT	window.openai	window.openai.openExternal({ url })
V-App	window.vsf	window.vsf.openDeeplink({ url })

Nếu widget gọi trực tiếp window.openai hay window.vsf, code sẽ bị gắn chặt vào một host và không chạy được trên host khác.

Framework giải quyết vấn đề này bằng cách cung cấp một bộ JS APIs thống nhất — tự động chuyển tiếp lời gọi tới đúng host API tương ứng với môi trường đang chạy.

Widget code
    │
    ▼
@v-miniapp/ai/apis    ← API thống nhất, có TypeScript types
    │
    ├── V-App host     → window.vsf.*
    └── ChatGPT host   → window.openai.*

Lợi ích

• Viết một lần, chạy mọi host — không cần if/else kiểm tra môi trường
• Type-safe — đầy đủ TypeScript types cho input/output, callback
• Async support — hỗ trợ cả callback lẫn async/await

---

Cài đặt & Import

JS APIs đã có sẵn trong @v-miniapp/ai, không cần cài thêm package:

import apis from '@v-miniapp/ai/apis'

Hoặc dùng phiên bản async/await:

import { apisAsync } from '@v-miniapp/ai/apis'

---

Cách sử dụng

Dạng Callback

Tất cả API đều hỗ trợ 3 callback: success, fail, complete:

import apis from '@v-miniapp/ai/apis'

apis.openDeeplink({
  url: 'vapp://miniapp/some-page',
  success: (res) => {
    console.log('Mở thành công', res)
  },
  fail: (err) => {
    console.error('Lỗi', err)
  },
  complete: () => {
    console.log('Hoàn tất')
  },
})

Dạng Async/Await

import { apisAsync } from '@v-miniapp/ai/apis'

try {
  const res = await apisAsync.openDeeplinkAsync({
    url: 'vapp://miniapp/some-page',
  })
  console.log('Mở thành công', res)
} catch (err) {
  console.error('Lỗi', err)
}

---

Danh sách API hiện có

API	Mô tả	Tham số
openDeeplink	Mở deep link trong app	url: string (bắt buộc)

ghi chú

Danh sách API sẽ được bổ sung thêm trong các phiên bản tiếp theo. Nếu bạn cần một API cụ thể, vui lòng liên hệ đội phát triển.

---

So sánh với host API gốc

Bảng dưới đây so sánh cách gọi API trực tiếp từ host vs qua framework:

Tác vụ	ChatGPT (window.openai)	V-App (window.vsf)	Framework (@v-miniapp/ai/apis)
Mở link ngoài	openai.openExternal({ url })	vsf.openDeeplink({ url })	apis.openDeeplink({ url })

Không nên gọi host API trực tiếp

Tránh gọi window.openai.* hay window.vsf.* trực tiếp trong widget. Sử dụng @v-miniapp/ai/apis để đảm bảo app hoạt động trên mọi host được hỗ trợ.