Gói license và quyền tính năng

Gói license hoạt động thế nào

Mỗi ứng dụng có danh sách gói riêng. Ứng dụng mới được tạo sẵn một gói tên Standard: 30 ngày, 1 máy, đặt làm gói mặc định. Bạn có thể sửa gói này hoặc thêm các gói như "Pro", "Lifetime", "Free".

Đừng nhầm gói license với gói dịch vụ Basic hay Premium của workspace. Gói license là thứ bạn bán cho khách, còn gói dịch vụ quyết định hạn mức của chính bạn, xem Gói Basic, Premium và hạn mức.

Khi tạo key, một phần giá trị của gói được chép vào license, phần còn lại được đọc trực tiếp từ gói mỗi lần dùng:

Tạo hoặc sửa một gói

1. Mở ứng dụng, vào Phát hành & bản quyền › Đăng nhập & gói license.
2. Ở mục Gói license, bấm Thêm gói. Muốn sửa gói có sẵn, bấm vào thẻ của gói đó.
3. Điền các nhóm ô bên dưới, rồi bấm Lưu gói.

Thẻ gói tóm tắt thời hạn (hoặc Vĩnh viễn), số máy, số ngày thử, số ngày ân hạn và danh sách quyền. Gói mặc định có nhãn Mặc định.

Thông tin cơ bản

• Tên gói: tối đa 64 ký tự.
• Thời hạn (ngày): để trống là vĩnh viễn, tối đa 10 năm. Thời hạn tính từ lần kích hoạt đầu tiên chứ không phải từ lúc tạo key, nên key nằm trong kho chưa bán không bị mất ngày.
• Số máy: số thiết bị một key được gắn cùng lúc, tối thiểu 1 và không vượt hạn mức thiết bị mỗi key của gói dịch vụ. Máy vượt số này bị từ chối với mã device_limit.
• Gói mặc định cho key mới và tài khoản miễn phí: mỗi ứng dụng chỉ có một gói mặc định, đánh dấu gói khác thì gói cũ tự bỏ dấu.

Gói mặc định được dùng ở ba chỗ: bảng Tạo license key chọn sẵn nó trong ô Gói (ô này chỉ hiện khi ứng dụng có từ hai gói); Seller API tạo key mà không gửi policyId; và người dùng đăng ký không kèm key ở chế độ Tài khoản hoặc Tài khoản + license key nhận license miễn phí theo gói này.

Dùng thử

• Số ngày thử: từ 1 tới 90 ngày. Để trống nếu gói không dùng cho bản thử.
• Hết thử thì về: chọn một gói khác của cùng ứng dụng (thường là gói miễn phí), hoặc Dừng hẳn. Gói không thể trỏ về chính nó.

Chuyển máy

• Lần mỗi 30 ngày: từ 0 tới 100. Để trống là 2 lần.
• Chờ giữa hai lần (giờ): từ 0 tới 720. Để trống là 24 giờ.
• Người bán, Khách, Đại lý: ai được chuyển máy. Không chọn ô nào thì hệ thống hiểu là người bán và khách.

Khách chuyển máy từ phần mềm (transfer() trong SDK) hoặc từ cổng khách hàng. Mỗi lần đều bị tính vào hạn mức và thời gian chờ: vượt thì nhận transfer_limited, còn khi khách không được phép thì nhận transfer_not_allowed. Đại lý chỉ đặt lại thiết bị cho key mình đã bán khi gói có chọn Đại lý. Việc bạn tự gỡ máy trên dashboard vẫn được ghi lại nhưng không bao giờ trừ vào hạn mức của khách.

Thời gian

• Ân hạn sau hạn (ngày): từ 0 tới 30, mặc định 0. License quá hạn vẫn chạy thêm số ngày này và phần mềm nhận state: "grace". Hết ân hạn, license ngừng hoạt động: máy đã gắn key nhận mã license_expired, license chuyển sang trạng thái hết hạn và webhook nhận sự kiện license.expired.
• Báo trước khi hết (ngày): từ 0 tới 60, mặc định 7. Trong khoảng này phần mềm nhận state: "expiring". Mỗi kỳ hạn, hệ thống phát một sự kiện license.expiring và gửi một email cho người mua nếu license có email (kèm link cổng khách hàng khi cổng đang bật). Đặt 0 để tắt. Sau khi Gia hạn, kỳ mới có thông báo riêng.
• Máy im lặng thì trả suất (giờ): để trống là 72 giờ, 0 là không bao giờ, tối đa 8.760 giờ (một năm). Máy không liên lạc với server lâu hơn mức này được đánh dấu không hoạt động và nhả suất cho máy khác. Nếu nó quay lại trong 7 ngày và license còn suất trống, nó tự lấy lại suất mà không tính là một lần chuyển máy; quá 7 ngày, máy bị gỡ hẳn khỏi license.
• Phiên cùng lúc: số nơi một key được chạy cùng lúc. Để trống là không giới hạn. Khi có giới hạn, đăng nhập mới trên cùng một máy thay thế phiên cũ của máy đó; phiên còn sống trên máy khác thì bị tính, vượt mức trả về session_limit.

Thông số chưa có trên biểu mẫu

Mỗi gói còn ba thông số mà engine đọc trực tiếp, nhưng biểu mẫu gói trên dashboard hiện chưa có ô để chỉnh. Gói tạo từ dashboard dùng giá trị mặc định:

Heartbeat của gói khác với công tắc Session lease ngắn hạn ở Bảo vệ Advanced: công tắc quyết định phiên hết hạn nhanh thế nào, còn heartbeat của gói quyết định khi nào máy nhả suất. Chi tiết về token offline có ở License offline.

Dùng thử theo máy

Bản thử chỉ có ở chế độ đăng nhập License key. Khi ít nhất một gói có Số ngày thử, init() trả về app.trial: true và phần mềm có thể gọi trial():

• Gói dùng cho bản thử là gói mặc định nếu nó có số ngày thử, nếu không là gói có số ngày thử được tạo sớm nhất. Chỉ để một gói có số ngày thử sẽ dễ kiểm soát hơn.
• Mỗi máy được thử một lần cho mỗi ứng dụng, nhận diện theo thiết bị chứ không theo IP. Gọi trial() lại trên cùng máy trả về đúng bản thử đang chạy.
• Bản thử nhận số máy, quyền tính năng và luật của gói thử; độ dài bản thử cố định từ lúc bắt đầu.
• Hết thử: không có gói dự phòng thì nhận trial_expired. Có gói dự phòng thì license chuyển sang gói đó (số máy, quyền và thời hạn của gói dự phòng, tính từ lúc chuyển) và câu trả lời có trial.fallback: true.
• Kích hoạt một key thật trên máy đó sẽ chốt bản thử; sau đó trial() trả về trial_used.
• IP đang có điểm rủi ro cao trong Protect 24/7 không thể bắt đầu bản thử (trial_denied).

const { app } = await clavis.init();
if (app.trial) {
  const grant = await clavis.trial();
  if (grant.trial?.fallback) {
    // Hết thử: phần mềm đang chạy theo gói dự phòng
  }
}

Quyền tính năng (entitlement)

Quyền tính năng là các cờ như export_pdf hay batch_mode mà gói cấp cho license. Server gửi danh sách này trong câu trả lời có chữ ký, nên bạn chỉ cần một bản build và để gói quyết định ai được dùng tính năng nào.

Khai báo quyền trên ứng dụng

1. Vào Phát hành & bản quyền › Đăng nhập & gói license, tìm thẻ Quyền tính năng (entitlement).
2. Nhập Tên hiển thị (ví dụ "Xuất PDF") và key (ví dụ export_pdf), rồi bấm nút +.
3. Key phải bắt đầu bằng chữ thường, chỉ gồm chữ thường, số và dấu gạch dưới, dài ít nhất 2 ký tự; ô nhập nhận tối đa 40 ký tự. Bỏ trống key thì dashboard tự tạo từ tên hiển thị.

Mỗi ứng dụng khai báo tối đa 64 quyền (mỗi gói cũng cấp tối đa 64 quyền); key trùng bị từ chối.

Gắn quyền vào gói

Mở gói, tick các quyền cần cấp trong nhóm Quyền tính năng rồi bấm Lưu gói. Chỉ quyền đã khai báo mới hiện ở đây; nếu chưa có quyền nào, biểu mẫu nhắc bạn khai báo trước. Quyền đã gắn hiện trên thẻ gói và trong chi tiết từng license ở Phát hành & bản quyền › License (dòng Quyền tính năng).

Xoá quyền

Bấm biểu tượng thùng rác (Xoá quyền) rồi xác nhận Xoá. Quyền biến mất khỏi ứng dụng và khỏi mọi gói cùng lúc; phần mềm đang chạy không còn nhận quyền đó từ lần đăng nhập hoặc heartbeat kế tiếp. Key là hợp đồng giữa dashboard và code của bạn, nên đổi tên một quyền nghĩa là xoá quyền cũ, tạo key mới và phát hành bản build đọc key mới.

Đọc quyền trong phần mềm

SDK JavaScript giữ danh sách quyền từ câu trả lời đã xác minh gần nhất. clavis.has("export_pdf") trả về true hoặc false, còn clavis.entitlements trả về mảng các key. Danh sách đến cùng kết quả của activate(), login(), register(), redeem() và trial() (trường grant.entitlements), và mỗi lần heartbeat() lại làm mới nó, nên khi bạn thêm quyền vào gói, máy đang chạy nhận quyền mới ở nhịp kế tiếp.

import { ClavisClient } from "@clavisauh/sdk";

const clavis = new ClavisClient({ baseUrl, appId: "app_…", appPublicKey, device });

const grant = await clavis.activate(licenseKey);
console.log(grant.entitlements); // ví dụ: ["export_pdf"]

if (clavis.has("export_pdf")) showExportMenu();

// Cảnh báo người dùng trước khi phần mềm dừng
if (grant.license.state === "expiring") showRenewBanner(grant.license.expiresAt);
if (grant.license.state === "grace") showGraceWarning();

setInterval(async () => {
  await clavis.heartbeat();
  toggleExportMenu(clavis.has("export_pdf"));
}, 30 * 60_000);

Một số trường hợp cần lưu ý:

• Trước lần đăng nhập đầu tiên, has() luôn trả về false và entitlements là mảng rỗng.
• Token offline không chứa danh sách quyền. Nếu phần mềm khởi động không có mạng và chỉ dựa vào verifyOffline(), has() trả về false, vì vậy hãy quyết định rõ tính năng nào được dùng khi offline.
• License không gắn gói nào nhận danh sách quyền rỗng.

Giới hạn và lưu ý

• Sửa Thời hạn (ngày) hay Số máy của gói không đổi key đã tạo. Với key đã bán, dùng thao tác Gia hạn ở trang License hoặc Seller API.
• Bảng Tạo license key cho phép chọn Thời hạn và Số thiết bị mỗi key khác với gói, chỉ cho riêng lô key đó.
• Hiện không có thao tác xoá gói. Gói không dùng nữa thì đổi tên cho rõ và bỏ dấu mặc định.
• Đại lý chỉ bán được những gói bạn cấp cho họ, xem Đại lý và tín dụng.

Liên quan

• Tạo và quản lý license
• Chế độ đăng nhập và dùng thử
• Thiết bị, HWID và chuyển máy
• SDK JavaScript