Nhúng qua npm

Phương thức khuyến nghị cho mọi ứng dụng đã có sẵn build pipeline (Vite / webpack / Rollup / Next.js / Nuxt / Angular CLI…). SDK đi kèm TypeScript declarations và ES modules tree-shakable.

1. Cài đặt package

SDK được phát hành dưới dạng tarball nội bộ (zorio-webphone-sdk-1.0.0.tgz) hoặc qua npm scoped registry mà đội Zorio cung cấp riêng cho từng đối tác.

# Cách A — cài trực tiếp từ tarball Zorio cấp
npm install ./zorio-webphone-sdk-1.0.0.tgz

# Cách B — qua scoped registry (nếu đối tác đã được cấp quyền)
npm install @zorio/webphone-sdk

Phiên bản

SDK v1 dùng sip.js@0.21.x làm transport WebRTC + SIP signaling. Bundle ~85 KB gzipped, đã include sẵn SIP.js — bạn không cần tự cài thêm.

2. Import + khởi tạo

import { ZorioWebphone } from '@zorio/webphone-sdk'

const phone = await ZorioWebphone.connect({
  apiBase: 'https://acme.zorio.example',
  token:   bearerToken,
  mount:   '#zorio-phone', // bỏ trống nếu chạy headless
})

ZorioWebphone.connect() trả về một Promise — đợi resolve trước khi gọi phone.call() hoặc subscribe events.

3. TypeScript

Package đã kèm .d.ts, bạn import type trực tiếp:

import type {
  ConnectOptions,
  ZorioCall,
  ZorioWebphoneError,
  CallOptions,
  DiagnoseResult,
} from '@zorio/webphone-sdk'

const opts: ConnectOptions = {
  apiBase: import.meta.env.VITE_ZORIO_API_BASE,
  token:   import.meta.env.VITE_ZORIO_TOKEN,
  mount:   '#zorio-phone',
  layout:  'docked',
  theme:   'auto',
  locale:  'vi',
  autoRegister: true,
}

const phone = await ZorioWebphone.connect(opts)

4. Ví dụ tích hợp Vue 3 (Composition API)

<script setup lang="ts">
import { onMounted, onBeforeUnmount, ref } from 'vue'
import { ZorioWebphone } from '@zorio/webphone-sdk'

const phoneRef = ref<ZorioWebphone | null>(null)

onMounted(async () => {
  phoneRef.value = await ZorioWebphone.connect({
    apiBase: 'https://acme.zorio.example',
    token:   await getBearerToken(),
    mount:   '#zorio-phone',
  })

  phoneRef.value.on('incoming_call', ({ call, contact }) => {
    console.log('Cuộc gọi đến:', contact?.full_name || call.number)
  })
})

onBeforeUnmount(async () => {
  await phoneRef.value?.disconnect()
})
</script>

<template>
  <div id="zorio-phone" />
</template>

5. Ví dụ tích hợp React

import { useEffect, useRef } from 'react'
import { ZorioWebphone } from '@zorio/webphone-sdk'

export function WebphoneWidget({ token }: { token: string }) {
  const phoneRef = useRef<ZorioWebphone | null>(null)

  useEffect(() => {
    let cancelled = false
    ;(async () => {
      const phone = await ZorioWebphone.connect({
        apiBase: 'https://acme.zorio.example',
        token,
        mount:   '#zorio-phone',
      })
      if (cancelled) { await phone.disconnect(); return }
      phoneRef.current = phone
    })()
    return () => {
      cancelled = true
      phoneRef.current?.disconnect()
    }
  }, [token])

  return <div id="zorio-phone" />
}

6. Tính năng v7 quan trọng

Auto-reconnect + re-register supervisor

SDK v7 tự động re-register SIP khi WebSocket bị throttle (tab nền) hoặc network drop. Anh chị không cần code thêm logic reconnect — chỉ nên lắng nghe event auto_reconnect để hiển thị banner "Đang khôi phục kết nối…" cho user.

Pagehide cleanup

Khi user đóng tab, SDK tự unregister sạch về Zorio PBX để tránh stale registration (gây miss inbound trong window timeout). Hoạt động cả khi nhúng qua bundler.

Early media

Outbound call qua di động sẽ phát ringback / IVR carrier announcement ngay từ SIP 183 Session Progress thay vì im lặng tới khi callee bốc máy. Bật mặc định trong SDK v7 (earlyMedia: true).

7. Bundler config gợi ý

Vite / Rollup mặc định tree-shake tốt. Nếu dùng webpack < 5 và gặp lỗi Cannot resolve module, thêm:

// webpack.config.js
module.exports = {
  resolve: {
    fallback: { crypto: false, stream: false, buffer: false },
  },
}

Tham khảo thêm:

• API methods
• Events
• Quickstart HTML