Super MiniApp SDK - API Documentation

Tự động sinh từ events.json — 57 events.

Demo Links (GitHub Pages):

• Demo Vanilla JS
• Demo React
• Demo Vue
• Demo Angular

1. Getting Started

1.1 Cài đặt

Package đã publish public trên npm với tên vdf-webview-miniapp-sdk. Có 3 cách tích hợp:

Cách	Phù hợp với	Nguồn
npm registry	React, Vue, Angular (có bundler)	npm install vdf-webview-miniapp-sdk
file .tgz (offline)	Môi trường không ra được npm registry	vdf-webview-miniapp-sdk-2.0.0.tgz
bundle.js	Vanilla JS, HTML thuần (không cần bundler)	dist/bundle.js

---

Cách 1: npm registry (khuyến nghị — React / Vue / Angular)

npm install vdf-webview-miniapp-sdk

Package đã kèm sẵn type declaration (.d.ts) — không cần cài thêm @types.

---

Cách 2: file .tgz (offline)

Bước 1: Lấy file vdf-webview-miniapp-sdk-2.0.0.tgz (sinh bằng npm pack từ packages/core) và copy vào thư mục core-lib/ trong project

mkdir -p core-lib
cp vdf-webview-miniapp-sdk-2.0.0.tgz core-lib/

Bước 2: Thêm dependency vào package.json

{
  "dependencies": {
    "vdf-webview-miniapp-sdk": "file:core-lib/vdf-webview-miniapp-sdk-2.0.0.tgz"
  }
}

Bước 3: Cài đặt

npm install

---

Cách 3: bundle.js (Vanilla JS / HTML thuần)

Không cần npm, không cần bundler — chỉ cần 1 file bundle.js (bản IIFE, build bằng npm run build:js ra dist/bundle.js).

Bước 1: Copy bundle.js vào project

Bước 2: Thêm script tag vào HTML

<script src="bundle.js"></script>

Bước 3: Sử dụng qua global WebviewSdk

var app = WebviewSdk.getSharedMiniApp({ debug: true })
app.ready()

// Gọi API
var res = await WebviewSdk.getLocation()
if (WebviewSdk.isSuccess(res)) {
  console.log(res.latitude)
}

Tất cả API functions đều có sẵn trên object WebviewSdk — giống hệt cách dùng với npm package.

1.2 Bắt đầu nhanh

import { getSharedMiniApp, getLocation, appOpenWebview, isSuccess } from 'vdf-webview-miniapp-sdk'

const app = getSharedMiniApp({ debug: true })
app.ready()

// Gọi API qua generated function (type-safe)
const res = await getLocation()
if (isSuccess(res)) {
  console.log(res.latitude)
}

// Gọi API có tham số
await appOpenWebview({ data: { url: 'https://example.com', serviceName: 'Demo' } })

// Gọi API qua invoke (dynamic)
const res2 = await app.invoke('GET_LOCATION')

React

import { useEffect } from 'react'
import { getSharedMiniApp, getLocation, isSuccess } from 'vdf-webview-miniapp-sdk'

const app = getSharedMiniApp({ debug: true })

function App() {
  useEffect(() => { app.ready() }, [])

  const handleClick = async () => {
    const res = await getLocation()
    if (isSuccess(res)) console.log(res.latitude)
  }

  return <button onClick={handleClick}>Get Location</button>
}

Vue 3

<script setup>
import { onMounted } from 'vue'
import { getSharedMiniApp, getLocation, isSuccess } from 'vdf-webview-miniapp-sdk'

const app = getSharedMiniApp({ debug: true })
onMounted(() => { app.ready() })

async function handleClick() {
  const res = await getLocation()
  if (isSuccess(res)) console.log(res.latitude)
}
</script>

<template>
  <button @click="handleClick">Get Location</button>
</template>

Angular

import { Component } from '@angular/core'
import { getSharedMiniApp, MiniApp, getLocation, isSuccess } from 'vdf-webview-miniapp-sdk'

@Component({
  template: `<button (click)="handleClick()">Get Location</button>`
})
export class AppComponent {
  private app: MiniApp

  constructor() {
    this.app = getSharedMiniApp({ debug: true })
    this.app.ready()
  }

  async handleClick() {
    const res = await getLocation()
    if (isSuccess(res)) console.log(res.latitude)
  }
}

Vanilla JS (bundle.js)

<script src="bundle.js"></script>
<script>
  var app = WebviewSdk.getSharedMiniApp({ debug: true })
  app.ready()

  async function handleClick() {
    var res = await WebviewSdk.getLocation()
    if (WebviewSdk.isSuccess(res)) console.log(res.latitude)
  }
</script>

<button onclick="handleClick()">Get Location</button>

2. API Reference

2.1 Khởi tạo

npm package:

import { getSharedMiniApp } from 'vdf-webview-miniapp-sdk'

const app = getSharedMiniApp({
  appId: 'com.example.miniapp',  // ID ứng dụng
  debug: true,                    // Bật log debug
  token: '',                      // Token xác thực
  timeout: 5000                   // Timeout mỗi request (ms), mặc định 90000
})

bundle.js:

var app = WebviewSdk.getSharedMiniApp({
  appId: 'com.example.miniapp',
  debug: true,
  token: '',
  timeout: 5000
})

getSharedMiniApp() tạo singleton — gọi nhiều lần vẫn trả về cùng 1 instance, tự động wire generated API.

2.2 Giao tiếp với Native

Method	Mô tả
app.invoke(api, data?)	Gọi native API, trả về Promise với kết quả
app.sendRaw(msg)	Gửi MiniAppRequestBase trực tiếp, đây là core method
app.emit(event, data?)	Gửi sự kiện 1 chiều đến native
app.on(event, callback)	Lắng nghe sự kiện từ native
app.once(event, callback)	Lắng nghe sự kiện 1 lần
app.off(event, callback?)	Hủy lắng nghe. Bỏ callback để hủy tất cả

2.3 Lifecycle

Method	Mô tả
app.ready()	Đánh dấu SDK sẵn sàng, xả hàng đợi message
app.destroy()	Hủy SDK, dọn dẹp tài nguyên
app.onReady(cb)	Gọi khi SDK sẵn sàng
app.onShow(cb)	Gọi khi app hiển thị
app.onHide(cb)	Gọi khi app bị ẩn
app.onError(cb)	Gọi khi có lỗi
app.onDestroy(cb)	Gọi khi app bị hủy

2.4 Plugin

app.use({
  name: 'analytics',
  install(app) {
    app.on('navigate', (data) => {
      app.emit('analytics.pageView', { url: data.url })
    })
  }
})

2.5 Middleware

app.useMiddleware(async (message, next) => {
  console.log('Before:', message.event, message)
  await next()
  console.log('After:', message.event)
})