v3 Integration

OMICallSDK: phiên bản SDK thứ 3 dành cho trình duyệt của OMICall, áp dụng mọi công nghệ mới nhất và hầu hết tính năng hiện có của OMICall SaaS, đem lại hiệu năng và chất lượng cuộc gọi tốt nhất.

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

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ẻ <script>

<body>
    <!-- Your app HTML -->
    <script type="text/javascript" src="https://cdn.omicrm.com/sdk/web/{{version}}/core.min.js"></script>
</body>

Để lấy thông tin {{version}}, xem tại: Web SDK hoặc v3 Changelog

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.

type UIConfig = {
    toggleDial?: 'show' | 'hide'; // default: 'show'
    dialPosition?: 'left' | 'right'; // default: 'right'
}
type Lng = 'vn' | 'en' | 'km'; // default: 'vn'

const lngConfig: Lng = 'vn';
const uiConfig: UIConfig = {
    toggleDial: 'show',
    dialPosition: 'right',
};

const initSuccess: Boolean = await OMICallSDK.init({
    lng: lngConfig,
    ui: uiConfig, // nếu tự custom UI gọi, hãy bỏ qua biến này
});
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

type RegisterStatus = {
   status: boolean;
   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: RegisterStatus = await OMICallSDK.register({
    sipRealm,
    sipUser,
    sipPassword,
});

// Để ngắt kết nối tới tổng đài
OMICallSDK.unregister();

Để lấy thông tin số nội bộ:

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

Để gọi nhanh một số sđt, sử dụng function: OMICallSDK.makeCall(phoneNumber);
Để mở/ đóng cửa sổ nhập số gọi ra của UI mặc định: OMICallUI.toggleDial();

Sự kiện & Dữ liệu

/*
  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;
    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
    ringingDuration: CallDuration;
    callingDuration: CallDuration;
    // các function để tương tác với cuộc gọi
    end: () => void;
    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
};

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 Khởi tạo SDK 2. Kết nối 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 Sự kiện & Dữ liệu 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ẻ <video /> ứng với 2 người trong cuộc gọi (nên để 2 thẻ này là children của dialog cuộc gọi tuỳ biến):

<video id="${callData.uid}-local" style="display:none" playsinline autoplay hidden mute />
<video id="${callData.uid}-remote" style="display:none" playsinline autoplay hidden />

6. Dùng các method trong CallData để: - Nhận cuộc gọi: callData.accept(); - Từ chối hoặc kết thúc cuộc gọi: callData.end(); - Bật/ Tắt microphone: callData.mute(cb); - Bật/ Tắt camera: callData.camera(cb); - Bật/ Tắt giữ cuộc gọi: callData.hold(cb); - Gửi tương tác bấm phím: callData.dtmf(tone); - Chuyển tiếp cuộc gọi: callData.transfer(); - Lưu ghi chú hoặc Tag vào OMICall: callData.save({ note:'', tags: ['test'] });