# v3 Integration ## Giới thiệu \- Sử dụng Webpack và TailwindCSS để tối ưu kích thước tập tin SDK cần nhúng\ \- Áp dụng Vanilla JS để xử lý hiển thị lẫn tính năng, đem lại hiệu năng tốt nhất\ \- Tự động giữ kết nối với tổng đài mỗi khi trạng thái kết nối mạng thay đổi\ \- Tính điểm chất lượng tín hiệu của cuộc gọi realtime ## Tích hợp ### Example {% file src="" %} Bên trên là code mẫu luồng tích hợp và sử dụng SDK với UI mặc định. ### Nhúng script * **Cách 1**: thông qua CDN, khai báo thẻ \ ``` Để lấy thông tin {{version}}, xem tại: [](https://api.omicall.com/sdk/web-sdk "mention") hoặc [v3-changelog](https://api.omicall.com/sdk/web-sdk/v3-changelog "mention") * **Cách 2**: Thông qua `npm` : comming soon... ### Khởi tạo Sau khi script `core.min.js` được load xong, sẽ có thêm biến global `window.OMICallSDK` **`OMICallSDK`**: biến `global` chính của call SDK, quản lý kết nối tới tổng đài và xử lý các sự kiện của cuộc gọi. **`OMICallUI`**: biến `global` khi sử dụng UI mặc định của SDK, có một số method để chủ động tương tác với UI mặc định. Dưới đây là mô tả các tuỳ chọn để khởi tạo SDK: ```groovy type UIConfigs = { /* * toggleDial: trạng thái hiển thị nút mở giao diện nhập số gọi ra * default: 'show' */ toggleDial?: 'show' | 'hide'; /* * dialPosition: vị trí hiển thị nút mở giao diện nhập số gọi ra * default: 'right' */ dialPosition?: 'left' | 'right'; /* * theme: màu sắc của giao diện SDK */ theme?: { white: '#ffffff'; black: '#000000'; primary: '#1e3150'; info: '#00b1ff'; success: '#56cc6e'; warning: '#fea220'; error: '#ff5955'; pink: '#e82a8f'; purple: '#a540b8'; blue: '#57bfdb'; }; /* * cấu hình tự động hiển thị cuộc gọi mới ở chế độ thu gọn * áp dụng cả cuộc gọi ra lẫn gọi vào * default: false */ minimizeNewCall?: boolean; }; ``` ```typescript type CtaButtonOnClick = (callData: CallData) => void; type CtaButton = { action: string; label: string; /* * get icon `code` from: * https://cdn.omicrm.com/common/icon/fluent-systems-filled/index.json */ icon: string; /* * override callback chung cho riêng button này */ onClick?: CtaButtonOnClick; }; type CallTab = { id: string; label: string; /* * Các cách để xử lý hiển thị nội dung tuỳ biến: * * #1: set trực tiếp HTML/CSS cần thiết * tabNode.innerHTML = '

your HTML/CSS

'; * * #2: với React 18+, dùng thư viện react-dom/client * createRoot(tabNode).render(); * * #3: các framework khác tương tự ReactJS */ render: ( callData: CallData, tabNode: HTMLDivElement, tabDetail: { id: string; label: string; }, ) => void; }; ``` ```typescript type SdkInitConfigs = { /* * lng: ngôn ngữ hiển thị trên UI * default: 'vi' */ lng?: 'vi' | 'en' | 'km'; /* * ui: cấu hình giao diện mặc định của SDK */ ui?: UIConfigs; /* * control ringtone volume * default: 1 */ ringtoneVolume?: number /* 0 -> 1 */; /* * control phone number masking */ phoneMasked?: { enable: boolean; /* * length: độ dài cho phép hiển thị số */ len: number; /* * character: *, #, x, ✨, ... */ char: string; /* * ltr: left-to-right */ ltr: boolean; }; /* * show list of CTA buttons, under remote contact info of calling dialog */ ctaButtons?: { unknown?: CtaButton[]; // show when `remoteContact` is null exists?: CtaButton[]; // show when `remoteContact` is not null base?: CtaButton[]; // always show these buttons onClick?: CtaButtonOnClick; // callback chung cho tất cả cta button }; /** * thay thế UI "Thông tin cuộc gọi" bằng UI dạng tabs * vẫn giữ lại giao diện cũ dưới dạng tab cuối cùng */ callTabs?: CallTab[]; /** * your main app's root body element * use for app need to passing a custom tab component into call dialog * use this option if your component required `HOCs` or `Context Provider` */ rootBody?: HTMLElement; /** * custom search remote contact function */ searchRemoteContact?: (callData: CallData) => Promise; /** * check the permission to make a call is allowed or not */ validateCallOut?: ( remoteNumber: string, options: MethodMakeCallOptions, ) => Promise<{ status: boolean; reason?: string }>; /** * list of custom icons using in default UI * will be loaded and caching */ icons: string[]; sounds?: Record< | 'ringtone' /* sound when have incoming call */ | 'ringing' /* sound when outgoing call don't have "early-media" */ | 'accepted' | 'ended', { src: string; volume: number /* 0 -> 1 */; } >; /** * control searching recent call from OMICall or not */ searchRecentCall?: boolean; }; ```

const SdkInitConfigs: Partial<SdkInitConfigs> = {
    /* tuỳ chỉnh cấu hình */
};
const initSuccess: Boolean = await OMICallSDK.init(SdkInitConfigs);
if (!initSuccess) {
    // nếu khởi tạo SDK có lỗi, không thực hiện register tổng đài
    return;
}

### Kết nối ```typescript type SdkRegisterConfigs = { /** * `isGuest`: skip all authentication and internal APIs * still allow to connect and make call with switchboard */ isGuest?: boolean; sipRealm: string; sipUser: string; sipPassword: string; }; type SdkRegisterResult = { status: boolean; message?: string; error?: string; }; /* Thông tin số nội bộ */ const sipRealm = 'demo01'; // domain tổng đài const sipUser = '100'; // số nội bộ const sipPassword = 'ABC123!@#'; // mật khẩu của số nội bộ // Để kết nối tới tổng đài const registerStatus: SdkRegisterResult = await OMICallSDK.register({ sipRealm, sipUser, sipPassword, } as SdkRegisterConfigs); // Để ngắt kết nối tới tổng đài OMICallSDK.unregister(); ``` Để lấy thông tin số nội bộ: * **Cách 1**: dùng API public tại [#danh-sach-so-noi-bo](https://api.omicall.com/omicall-api/call-center#danh-sach-so-noi-bo "mention") * **Cách 2**: truy cập màn hình **Cấu hình ▸ Tổng đài ▸ Số nội bộ** trong website OMICall ### Methods 1. Để gọi nhanh một số sđt, sử dụng function:
```typescript type SipNumber = { number: string; }; type RemoteContact = { name: string; avatar?: string; // URL | Base64 gender?: 'male' | 'female' | 'other'; }; type MakeCallOptions = { isVideo?: boolean; sipNumber?: SipNumber; remoteContact?: RemoteContact; /* userData: custom data, will be attach to call history */ userData?: string; }; const remoteNumber: string = ''; /* phone number or Zalo User ID */ const options: MakeCallOptions | null = null; OMICallSDK.makeCall(remoteNumber, options); ``` 2. Để mở/ đóng cửa sổ nhập số gọi ra của UI mặc định: `OMICallUI.toggleDial();` 3. Để thực hiện tạo phiên gọi tới số điện thoại cho các phiên đăng nhập (ví dụ thao tác click-2-call từ web để gọi ra nhanh cho 1 SĐT bằng máy bàn):
```javascript const remoteNumber = ''; // Số điện thoại cần gọi, bắt buộc const sipNumber = ''; // Số hotline muốn dùng để gọi ra, không bắt buộc OMICallSDK.remoteCall(remoteNumber, sipNumber); ``` ### Sự kiện & Dữ liệu ```typescript /* Một eventName có thể đăng ký bởi nhiều callback function, vậy nên khi huỷ đăng ký, cần truyền đúng eventCallback đã đăng ký trước đó */ OMICallSDK.on(eventName, eventCallback); OMICallSDK.off(eventName, eventCallback); type EventName = // event trạng thái kết nối tổng đài, callback data: `type RegisterData` 'register' // các events của cuộc gọi, callback data: `type CallData` | 'connecting' // khi cuộc gọi ra bắt đầu kết nối | 'ringing' // khi cuộc gọi bắt đầu đổ chuông | 'on_ringing' // mỗi giây, khi đang đổ chuông | 'accepted' // khi cuộc gọi được bắt máy | 'on_calling' // mỗi giây, khi đang trong cuộc gọi đã bắt máy | 'set_sip_number' // khi có được số hotline đang dùng để gọi ra | 'ended' // khi cuộc gọi kết thúc ; type RegisterData = { status: 'connecting' | 'connected' | 'disconnect'; name: string; // đa ngôn ngữ của trạng thái kết nối }; type CallData = { uid: string; // UUID tự sinh uuid?: string; // UUID từ tổng đài state: 'connecting' | 'ringing' | 'accepted' | 'ended'; // trạng thái hiện tại direction: 'outbound' | 'inbound'; isVideo: boolean; isOutbound: boolean; isInternal: boolean; isHangup?: boolean; // khi người dùng chủ động từ chối cuộc gọi sipNumber?: SipNumber; remoteContact?: RemoteContact; remoteNumber: string; displayNumber: string; // áp dụng theo phân quyền ẩn sđt streams: Record<'local' | 'remote', MediaStream>; players: Record<'local' | 'remote', HTMLVideoElement>; startTs: number; // thời gian bắt đầu cuộc gọi, Timestamp startAt: string; // thời gian bắt đầu cuộc gọi, format: HH:mm:ss held: boolean; // trạng thái giữ cuộc gọi audio: boolean; // trạng thái bật/ tắt microphone video: boolean; // trạng thái bật/ tắt camera ua: string; // window.navigator.userAgent devices: { audio: boolean; video: boolean; }; // trạng thái khả dụng của thiết bị microphone/ camera rtcpStat: any; // thống kê chất lượng kết nối của cuộc gọi rejectCode?: string; // mã lỗi từ tổng đài blockedProvider?: string; // nhà mạng của SĐT từ chối cuộc gọi ringingDuration: CallDuration; callingDuration: CallDuration; userData?: string; // internal data isEnded?: boolean; // trạng thái cuộc gọi đã kết thúc // các function để tương tác với cuộc gọi end: () => void; // hành động chung để kết thúc cuộc gọi decline: () => void; // hoàn toàn kết thúc cuộc gọi tới, không tiếp tục phân bổ cuộc gọi accept: () => void; mute: (cb?: () => boolean) => void; // bật/ tắt microphone, `cb` trả về trạng thái mới camera: (cb?: () => boolean) => void; // bật/ tắt camera, `cb` trả về trạng thái mới hold: (cb?: () => boolean) => void; // bật/ tắt giữ cuộc gọi, `cb` trả về trạng thái mới dtmf: (tone: string) => void; // gửi tương tác bấm phím, mỗi `tone` là 1 ký tự [0-9*#] transfer: (target: string) => void; // target: số nội bộ, nhóm nội bộ, nhóm bên ngoài, tương tác bấm phím save: ( info: { note?: string; tags?: string[]; }, onSave: () => void, onFinish: () => boolean ) => void; // gọi function này, khi bạn muốn lưu note hoặc tags vào OMICall /** * cho phép chủ động trigger việc phóng to/ thu nhỏ UI của call dialog * @param getCustomPosition: cho phép tuỳ biến vị trí tiếp theo sẽ hiển thị, sau khi cập nhật kích thước UI */ minimize: (getCustomPosition?: (data: { width: number; height: number }) => { x: number; y: number }) => void; }; type SipNumber = { // thông tin luôn có number: string; /* Các data khác chỉ có khi gọi bằng UI mặc định Cấu trúc riêng của OMICall, có thể thay đổi trong tương lai Không khuyến khích dử sụng */ }; type RemoteContact = { name: string; avatar?: string; // URL | Base64 gender?: 'male' | 'female' | 'other'; }; type CallDuration = { value: number; // 0 text: string; // '00:00' }; ``` ### Giao diện tuỳ biến Khi sử dụng SDK cho giao diện tuỳ biến, hãy đảm bảo thực hiện đủ các nghiệp vụ bên dưới:\ 1\. Sau khi đã đảm bảo SDK đã được tải, hãy [#khoi-tao](#khoi-tao "mention") SDK \ 2\. [#ket-noi](#ket-noi "mention") tới tổng đài\ 3\. Đăng ký các sự kiện kết nối và trạng thái của cuộc gọi theo [#su-kien-and-du-lieu](#su-kien-and-du-lieu "mention")\ 4\. Cache lại giá trị `Object` `CallData` trong event callback phía dưới:\ \- Event `connecting` cho cuộc gọi ra\ \- Event `ringing` cho cuộc gọi đến\ 5\. Render 2 thẻ `