Nhúng qua UMD/CDN
Phương thức phù hợp cho website tĩnh, WordPress, CRM legacy không có bundler hoặc môi trường air-gapped không kết nối CDN ngoài. Chỉ cần một thẻ <script> là dùng được class ZorioWebphone qua biến global.
1. Cấu trúc file UMD
| File | Kích thước (~) | Dùng cho |
|---|---|---|
zorio-webphone.umd.cjs | 85 KB gzip | <script src=...> |
zorio-webphone.umd.js | 85 KB gzip | Alias CDN ổn định |
zorio-webphone.esm.js | 80 KB gzip | <script type="module"> |
Tất cả bundle đã include sẵn sip.js@0.21.x + các dependency runtime — không cần load thêm script ngoài.
2. Drop-in qua CDN Zorio
<!DOCTYPE html>
<html lang="vi">
<head>
<meta charset="UTF-8" />
<title>Demo Webphone</title>
</head>
<body>
<div id="zorio-phone" style="position:fixed;bottom:24px;right:24px"></div>
<script src="https://cdn.zorio.vn/webphone-sdk/v1/zorio-webphone.umd.cjs"></script>
<script>
const { ZorioWebphone } = window.ZorioWebphoneSDK
ZorioWebphone.connect({
apiBase: 'https://acme.zorio.example',
token: '<bearer-token-from-login>',
mount: '#zorio-phone',
}).then((phone) => {
window.phone = phone // tiện debug
phone.on('incoming_call', ({ call, contact }) => {
console.log('Cuộc gọi đến:', contact?.full_name || call.number)
})
})
</script>
</body>
</html>Global namespace
UMD bundle expose window.ZorioWebphoneSDK. Class chính lấy ra qua destructuring: const { ZorioWebphone } = window.ZorioWebphoneSDK. Anh chị không nên đụng tới window.SIP (SIP.js nội bộ) — luôn dùng qua class ZorioWebphone để giữ tương thích về sau.
3. ESM script tag (browser hiện đại)
<script type="module">
import { ZorioWebphone } from 'https://cdn.zorio.vn/webphone-sdk/v1/zorio-webphone.esm.js'
const phone = await ZorioWebphone.connect({
apiBase: 'https://acme.zorio.example',
token: bearerToken,
mount: '#zorio-phone',
})
</script>4. Self-host (môi trường air-gapped)
Nếu ứng dụng chạy trong mạng nội bộ không kết nối CDN ngoài (BĐS, ngân hàng, bệnh viện), tải tarball SDK rồi serve qua nginx/Apache:
/var/www/static/vendor/zorio-webphone.umd.cjs
/var/www/static/vendor/zorio-webphone.d.ts<script src="/static/vendor/zorio-webphone.umd.cjs"></script>CSP — Content Security Policy
Khi self-host hoặc nhúng vào trang có CSP nghiêm ngặt, thêm các directive sau:
connect-src wss://*.zorio.example https://*.zorio.example;
media-src blob:;
script-src 'self' https://cdn.zorio.vn;WebRTC cần blob: cho MediaStream audio element, còn wss:// cho SIP signaling.
5. Pattern cho WordPress / CRM legacy
<!-- Vào theme footer.php hoặc plugin shortcode -->
<div id="zorio-phone"></div>
<script src="https://cdn.zorio.vn/webphone-sdk/v1/zorio-webphone.umd.cjs"></script>
<script>
(function () {
// Lấy bearer token từ session backend của CRM
fetch('/wp-json/my-app/v1/zorio-token', { credentials: 'include' })
.then(r => r.json())
.then(({ token }) => window.ZorioWebphoneSDK.ZorioWebphone.connect({
apiBase: 'https://acme.zorio.example',
token,
mount: '#zorio-phone',
layout: 'docked',
theme: 'auto',
}))
.then((phone) => { window.phone = phone })
.catch(console.error)
})()
</script>6. Tính năng v7 trong bundle UMD
Mọi bundle (UMD / ESM / npm) đều có cùng feature set:
- Auto-reconnect supervisor — tự re-register khi WSS drop / tab background.
- Pagehide cleanup — đóng tab tự
unregistervề Zorio PBX. - Early media — outbound nghe ringback / IVR carrier từ 183 Session Progress.
Diagnostic preflight
Trước khi connect(), bạn có thể chạy preflight để kiểm tra HTTPS / Micro / WSS / STUN / TURN:
const r = await window.ZorioWebphoneSDK.ZorioWebphone.diagnose({
apiBase: 'https://acme.zorio.example',
token,
})
if (!r.micOk) alert('Vui lòng cấp quyền micro')
if (!r.wssOk) alert('Firewall đang chặn WSS 443')7. Yêu cầu môi trường
- Trang phải chạy qua HTTPS (WebRTC mandate, ngoài
localhost). - Browser ≥ Chrome 90 / Edge 90 / Firefox 90 / Safari 14.
- User phải có một gesture (click/tap) trên trang trước khi cuộc gọi đầu tiên đến, để bypass autoplay policy của Safari/iOS — nếu không sẽ nhận event
audio_autoplay_blocked.
Tham khảo thêm: