Chế độ đăng nhập và dùng thử

Ba chế độ đăng nhập

Chế độ đăng nhập quyết định server nhận những lời gọi nào từ phần mềm của bạn. App mới tạo luôn ở chế độ License key.

• License key: người dùng dán key, phần mềm gọi activate(key). Đây cũng là chế độ duy nhất có dùng thử gắn với máy qua trial().
• Tài khoản: người dùng đăng ký bằng tên đăng nhập (3 đến 64 ký tự: chữ không dấu, số, _, ., -) và mật khẩu (8 đến 128 ký tự), email là tuỳ chọn. Nếu kèm key, tài khoản gắn với license của key đó. Không có key, tài khoản bắt đầu trên gói mặc định của app.
• Tài khoản + license key: như chế độ Tài khoản, thêm lời gọi redeem(key) để tài khoản đang đăng nhập nâng cấp lên license trả phí mà vẫn giữ tên, mật khẩu và máy hiện tại.

Đổi chế độ trong dashboard

1. Mở app, vào Phát hành & bản quyền › Đăng nhập & gói license.
2. Ở mục Chế độ đăng nhập, bấm vào thẻ của chế độ bạn muốn. Thẻ đang dùng được tô sáng, mỗi thẻ ghi sẵn các lời gọi mà nó nhận.
3. Dashboard lưu ngay và báo "Đã lưu". Server áp dụng chế độ mới gần như ngay lập tức, chậm nhất khoảng 30 giây.

Đổi chế độ không xoá license, tài khoản hay phiên nào. Nó chỉ quyết định server nhận lời gọi đăng nhập nào kể từ lúc đó.

Gọi sai chế độ: mode_not_allowed

Nếu phần mềm gửi một lời gọi mà chế độ hiện tại không nhận, ví dụ activate khi app đang ở chế độ Tài khoản, server trả HTTP 403 với mã mode_not_allowed và thông điệp nêu chế độ đang dùng. Kiểm tra này chạy trước các kiểm tra đăng nhập khác như bảo trì, phiên bản, key hay mật khẩu. Cách tránh: gọi init() khi khởi động và dựng form theo app.loginMode thay vì viết cứng trong bản build.

Dùng thử gắn với máy

Dùng thử cho người dùng chạy phần mềm không cần key trong số ngày bạn đặt. Mỗi máy chỉ được thử một lần cho mỗi app. Máy được nhận diện bằng fingerprint mà SDK gửi lên, không phải bằng IP, nên đổi mạng hay dùng VPN không mở thêm lượt thử.

Bật dùng thử

1. Vào Phát hành & bản quyền › Đăng nhập & gói license, chọn chế độ License key. Dùng thử chỉ có ở chế độ này.
2. Ở mục Gói license, bấm vào gói dùng cho bản thử, hoặc bấm Thêm gói.
3. Trong phần Dùng thử, nhập Số ngày thử (từ 1 đến 90).
4. Ở ô Hết thử thì về, chọn một gói khác của app làm gói dự phòng, hoặc Dừng hẳn.
5. Bấm Lưu gói. Thẻ gói hiện thêm "thử N ngày".

Số máy và quyền tính năng của bản thử lấy theo gói đó. Nếu nhiều gói cùng có số ngày thử, server dùng gói mặc định trước, sau đó tới gói tạo sớm nhất.

Cách bản thử hoạt động

• init() trả app.trial = true khi app ở chế độ License key và có ít nhất một gói có số ngày thử. Chỉ hiện nút "Dùng thử" khi giá trị này là true.
• Lần gọi trial() đầu tiên trên một máy tạo một license nội bộ cho máy đó. Người dùng không thấy key của nó. Trong Phát hành & bản quyền › License, nó hiện với tiền tố TRIAL- và ghi chú "Trial".
• Gọi lại trial() trên cùng máy khi còn hạn sẽ tiếp tục đúng bản thử cũ, không mở bản mới. Hai lần gọi đầu tiên chạy song song cũng chỉ tạo một bản thử: lần đến sau nhận trial_used, gọi lại trial() sẽ tiếp tục bản thử vừa tạo.
• Kết quả có thêm trial.endsAt (lúc hết thử) và trial.fallback (máy đã về gói dự phòng hay chưa).
• Nếu IP đang gọi có điểm rủi ro từ 70 trở lên trong Protect 24/7, máy không mở được bản thử mới (trial_denied).
• Khi người dùng kích hoạt một key thật bằng activate() trên máy đang thử, bản thử được đánh dấu đã chuyển đổi và vẫn giữ lại để đối chiếu. Từ đó trial() trên máy này trả trial_used.

Khi hết hạn dùng thử

Sau ngày kết thúc, lần gọi trial() tiếp theo trên máy đó xử lý theo ô Hết thử thì về:

• Dừng hẳn: server trả trial_expired. Phần mềm nên mời người dùng mua key.
• Một gói dự phòng: license thử chuyển sang gói đó và chạy tiếp với số máy, thời hạn (tính từ lúc chuyển, trống là vĩnh viễn) và quyền tính năng của gói dự phòng. Kết quả có trial.fallback = true. Cách làm phổ biến là một gói "Free" vĩnh viễn với ít quyền tính năng hơn.

Phiên đang mở sẽ nhận license_expired khi license thử hết hạn (sau số ngày ân hạn của gói, nếu có). Gặp mã này trên máy đang thử, hãy gọi lại trial() để máy chuyển sang gói dự phòng.

Bảo trì và phiên bản tối thiểu

Sau khi qua kiểm tra chế độ, mọi lời gọi activate, trial, register và login đều đi qua một cổng chung theo thứ tự: chế độ bảo trì, phiên bản tối thiểu, bản build bị chặn, rồi bản build lạ. Hai cài đặt đầu nằm ở Phát hành & bản quyền › Bản phát hành.

Chế độ bảo trì

1. Vào Phát hành & bản quyền › Bản phát hành.
2. Bật công tắc Chế độ bảo trì.
3. Nhập Lời nhắn khi bảo trì (tối đa 300 ký tự). Lời nhắn được lưu khi bạn rời ô nhập.

Trong lúc bảo trì, init() trả app.maintenance = { message } (chuỗi rỗng nếu bạn chưa nhập lời nhắn) để phần mềm hiện lời nhắn thay cho form đăng nhập. Bốn lời gọi đăng nhập bị từ chối với HTTP 503, mã maintenance, thông điệp là lời nhắn của bạn (để trống thì là một câu mặc định bằng tiếng Anh). Phiên đã mở không bị cắt: heartbeat, đọc biến và redeem vẫn chạy bình thường. Bảo trì chỉ chặn lượt đăng nhập mới.

Phiên bản tối thiểu

1. Ở thẻ Phiên bản tối thiểu trên cùng trang, nhập phiên bản dạng semver (ví dụ 1.4.0) vào ô của kênh stable rồi bấm Đặt. Xoá trống rồi bấm Đặt để bỏ giới hạn.
2. Trong SDK, truyền appVersion (nên kèm buildHash) khi tạo ClavisClient.

Khi đăng nhập, server so appVersion mà SDK gửi với phiên bản tối thiểu của kênh stable. Bản thấp hơn bị từ chối với HTTP 426, mã update_required. Nếu SDK không gửi appVersion thì bước này bị bỏ qua, nên hãy luôn khai báo nó. init() cũng báo trước bằng app.update.required = true kèm minVersion, để bạn hiện màn hình cập nhật trước khi người dùng nhập gì.

Hai kiểm tra còn lại của cổng:

• Phiên bản hoặc file build thuộc một bản phát hành ở trạng thái Đã chặn bị từ chối với build_blocked.
• Khi Kiểm tra toàn vẹn build được bật ở Bảo vệ Advanced và đặt ở Chặn, một buildHash không khớp file nào trong các bản phát hành của app bị từ chối với unknown_build. Kiểm tra này chỉ chạy khi SDK gửi buildHash và app đã có ít nhất một bản ở trạng thái Đã phát hành.

Mã nguồn mẫu

Các ví dụ dùng SDK JavaScript. Khởi tạo một lần, đọc cấu hình bằng init() rồi dựng màn hình phù hợp:

import { ClavisClient, ClavisError, hashComponent } from "@clavisauh/sdk";

// Băm từng linh kiện trước khi gửi; fingerprint là băm của cả bộ
const parts = { cpu: hashComponent(cpuId), board: hashComponent(boardSerial), disk: hashComponent(diskSerial) };

const clavis = new ClavisClient({
  baseUrl: "https://api.example.com",
  appId: "app_…",
  appPublicKey: "<khoá công khai của app>",
  device: { fingerprint: hashComponent(Object.values(parts).join("|")), components: parts, platform: "windows" },
  appVersion: "1.4.0",
});

const { app } = await clavis.init();
if (app.maintenance) showMaintenance(app.maintenance.message);
else if (app.update?.required) showUpdate(app.update.minVersion);
else showSignIn(app.loginMode, app.trial);

Chế độ License key

if (key) {
  await clavis.activate(key);
} else if (app.trial) {
  const grant = await clavis.trial();
  showTrialBanner(grant.trial?.endsAt, grant.trial?.fallback);
}

Chế độ Tài khoản

// Không key: tài khoản chạy trên gói mặc định
await clavis.register(null, "minh.tran", password, "minh@example.com");
// Có key: tài khoản gắn với license của key đó
await clavis.register(key, "lan.pham", password);

// Những lần sau
await clavis.login("minh.tran", password);

Chế độ Tài khoản + license key

await clavis.login("minh.tran", password);
await clavis.redeem(key); // nâng cấp trong phiên, giữ tên, mật khẩu và máy
if (clavis.has("pro")) unlockPro();

Sau redeem, phiên cũ bị đóng và SDK tự nhận phiên mới trong kết quả. License miễn phí tự tạo lúc đăng ký bị thu hồi vì không còn việc gì để làm. Một license chỉ gắn được với một tài khoản.

Xử lý lỗi

try {
  await clavis.login(username, password);
} catch (e) {
  if (!(e instanceof ClavisError)) throw e;
  if (e.code === "maintenance") showMaintenance(e.message);
  else if (e.code === "update_required") showUpdate();
  else if (e.code === "mode_not_allowed") await clavis.init(); // chế độ vừa đổi, đọc lại
  else showError(e.message);
}

Mã lỗi thường gặp

Hạn mức người dùng cuối theo gói dịch vụ xem tại Gói Basic, Premium và hạn mức.

Liên quan

• Gói license và quyền tính năng
• Người dùng cuối
• Bản phát hành có ký và cập nhật
• SDK JavaScript