Tổng quan luồng hoạt động

Luồng cấu hình ban đầu sau khi khởi tạo dự án

luồng khởi tạo dự án

Sau khi khởi tạo Application trên Dashboard của Communi thành công, bạn sẽ tạo được API key dùng để tương tác với các API services của Communi. Có 2 tác vụ cần thực hiện sau khi khởi tạo xong Application và API key:

Đồng bộ danh sách người dùng từ hệ thống phía bạn sang hệ thống quản lý người dùng của Communi: các thông tin cơ bản như avatar, displayname... để người dùng đó có thể chat thông qua Communi Chat SDK ngay trên ứng dụng của bạn.

Tham khảo hướng dẫn: Tạo người dùng mới

Code mẫu thực hiện tạo 1 người dùng mới

const fetch = require('node-fetch');

const app_id = 'your_app_id';
const api_key = 'your_api_key';

const url = `https://${app_id}.api.piscale.com/user/v1.0/user`;

const options = {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'X-Api-Key': api_key
  },
  body: JSON.stringify({
    alias: 'your user alias',
    avatar_url: 'your user avatar',
    display_name: 'your user display name',
    user_id: 'your user id'
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

Đăng kí thông tin Firebase Cloud Messaging với hệ thống Notification của Communi, để người dùng Chat SDK có thể nhận được Firebase Notification khi sử dụng ứng dụng. Các thông tin cần đăng kí gồm có: Server key và Sender ID của FCM

Tham khảo hướng dẫn: Đăng kí thông tin Firebase Cloud Messaging

Code mẫu thực hiện cài đặt notification cho ứng dụng của bạn

const fetch = require('node-fetch');

const app_id = 'your_app_id';
const api_key = 'your_api_key';
const your_firebase_project_number = 'your_firebase_project_number';

const url = `https://${app_id}.api.piscale.com/notification/v1.0/application/${your_firebase_project_number}'`;

const options = {
  method: 'PATCH',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'X-Api-Key': api_key
  },
  body: JSON.stringify({
    gcm_key: 'your_gcm_key',
    gcm_sender_id: 'your_sender_id'
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

Luồng người dùng đăng nhập sử dụng ứng dụng

luồng đăng nhập

Khi nguời dùng đăng nhập trên ứng dụng của bạn, SDK được tích hợp sẽ gọi đến backend api của bạn để backend của bạn gọi tới backend của Communi tạo token tương ứng cho người dùng của bạn.

Gợi ý: bạn nên tạo 1 api mới để thực hiện tác vụ này. API này sẽ được Communi SDK sử dụng để thực hiện lấy JWT token tương ứng cho người dùng của bạn.

Code mẫu Server API của bạn gọi tới Communi backend tạo JWT token

import express from 'express';
import cors from 'cors';
import rateLimit from 'express-rate-limit';
import helmet from 'helmet';
import bcrypt from 'bcrypt';

const app = express();
const fetch = require('node-fetch');

const app_id = 'your_app_id';
const api_key = 'your_api_key';

// Enable CORS
app.use(cors());

// Rate limiting
const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100 // limit each IP to 100 requests per windowMs
});
app.use(limiter);

// Set security headers
app.use(helmet());

// Enable JSON use
app.use(express.json());

app.post('/user/v1.0/auth/fetch-token/:your_user_id', async (req, res) => {
    const { your_user_id } = req.params;
    // kiểm tra tính hợp lệ user
    // ...
  
    // nếu người dùng này hợp lệ thì gọi tới backend của Communi tạo JWT token
    const url = `https://${app_id}.api.piscale.com/user/v1.0/user/${your_user_id}/token'`;
  
    const options = {
      method: 'POST',
      headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'X-Api-Key': api_key
      }
    };
    
    try {
      const fetchResponse = await fetch(url, options);
      if (!fetchResponse.ok) {
        throw new Error(`HTTP error! status: ${fetchResponse.status}`);
      }
      const data = await fetchResponse.json();
      // trả về JWT token cho Communi SDK
      res.json({ data: data });
    } catch (error) {
      // log lại lỗi để quản lý và kiểm tra khi cần
      console.error('There was a problem fetching the data:', error);
      // trả về lỗi
      res.status(500).json({ error: 'Internal Server Error' });
    }
  });

// Start the server
app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

Khi đó, backend của bạn sẽ cần gọi sang Backend quản lý người dùng của Communi, để tạo ra JWT token tương ứng cho người dùng đó, token này được SDK sử dụng để tương tác với các dịch vụ backend của Communi.
& 4. Trả về JWT token cho SDK client để tương tác với các backend của Communi
Sau khi nhận được JWT token ở lần đăng nhập đầu tiên trên thiết bị bất kì, SDK client sẽ tự động gọi đến Backend Notification của Communi để đăng kí FCM device token cho thiết bị.
Sử dụng JWT token để tương tác với các API backend chat của Communi

Luồng refresh JWT token

luồng refresh token

JWT token sẽ khả dụng trong 1 khoảng thời gian ngắn, vì vậy khi token này hết hạn, sẽ cần có luồng để làm mới token và tiếp tục sử dụng

1 & 2. Khi token JWT hết hạn, các API backend chat của Communi sẽ trả về mã lỗi 401. Lúc này SDK sẽ kích hoạt luồng refresh token

Ứng dụng gọi đến Backend quản lý người dùng của bạn để lấy token mới
Backend quản lý người dùng của bạn sẽ gọi đến backend quản lý người dùng của Communi để tạo mới JWT token cho người dùng

5 & 6. Trả về JWT token cho ứng dụng để tiếp tục sử dụng

Luồng người dùng đăng xuất khỏi ứng dụng

luồng đăng xuất

Người dùng đăng xuất khỏi ứng dụng
Ứng dụng sẽ gọi đến Backend Notification của Communi để hủy đăng kí thông tin FCM, để ngừng nhận các thông báo về chat từ Communi
Backend quản lý người dùng cửa bạn sẽ cần gọi đến backend quản lý người dùng của Communi để xóa JWT token của người dùng đó

Luồng tạo/xóa người dùng

luồng tạo người dùng

Khi có người dùng đăng kí/hủy đăng kí bên phía ứng dụng của bạn, bạn sẽ cần phải tạo/xóa (đồng bộ) người dùng tương ứng đó sang phía hệ thống quản lý người dùng của Communi. Để người dùng mới có thể sử dụng được tính năng chat trên ứng dụng của bạn.

Chuẩn bị

Ngoài các API được tích hợp sẵn trong SDK, PiScale hỗ trợ việc tương tác hệ thống chat bằng việc gọi API từ phía máy chủ của bạn.

URL cơ sở

Định dạng:

Base URL

https://{app_id}.api.piscale.com

Xác thực

Mọi yêu cầu gọi đến API phải được xác thực bởi máy chủ PiScale. Bạn phải truyền Api-Key vào header của yêu cầu HTTP cho việc xác thực. Vui lòng liên hệ admin để được cấp Api-Key.

HTTP Request Header API Key

X-Api-Key: {your_application_api_key}

note

Api-Key là dữ liệu rất quan trọng, nếu bị lộ trong quá trình trao đổi dữ liệu, bạn sẽ đối mặt với việc mất dữ liệu.

Ngoài ra, nếu kiến trúc hệ thống của bạn là multi-tenant và bạn muốn chỉ định tenant-id, bạn phải truyền X-Tenant-Id (Tenant ID bên hệ thống của bạn) vào header.

HTTP Request Header Tenant ID

X-Tenant-ID: {tenant_id}

Tổng quan luồng hoạt động

Luồng cấu hình ban đầu sau khi khởi tạo dự án​

Luồng người dùng đăng nhập sử dụng ứng dụng​

Luồng refresh JWT token​

Luồng người dùng đăng xuất khỏi ứng dụng​

Luồng tạo/xóa người dùng​

Chuẩn bị​

URL cơ sở​

Xác thực​