Biến ứng dụng

Biến dùng để làm gì

Một vài cách dùng phổ biến:

• Thông báo hiển thị khi mở phần mềm, ví dụ lịch bảo trì hay khuyến mãi.
• Cấu hình có thể đổi sau khi phát hành: địa chỉ máy chủ của riêng bạn (https://files.example.com), số lần thử lại, ngưỡng cảnh báo.
• Hạn mức riêng cho một khách, ví dụ max_projects lớn hơn cho một license doanh nghiệp.
• Dữ liệu có giá trị mà bạn chỉ muốn trao cho phiên hợp lệ, thay vì nhúng sẵn trong file chạy.

Biến thuộc riêng một ứng dụng. Giá trị luôn là chuỗi; dữ liệu có cấu trúc thì lưu dạng JSON và parse trong phần mềm.

Ba phạm vi

Phiên có tài khoản là phiên tạo bởi register(), login() hoặc redeem(). Phiên tạo bằng activate(key) hoặc trial() không gắn tài khoản nào, nên không bao giờ nhận biến phạm vi Một người dùng.

Thứ tự ưu tiên

Khi cùng một tên có ở nhiều phạm vi, server gộp lại thành một bảng duy nhất và giá trị cụ thể hơn thắng: người dùng, rồi license, rồi toàn cục. Ví dụ với ba biến cùng tên max_projects:

• Máy kích hoạt bằng key của license A, không có tài khoản: nhận 10.
• Tài khoản B đăng nhập, dù đang dùng license nào: nhận 50.
• Mọi phiên còn lại: nhận 3.

Tìm ID license và ID người dùng

• ID license: ở Phát hành & bản quyền › License, bấm ⋯ cuối dòng rồi chọn Sao chép ID, hoặc chọn Xem chi tiết, ID nằm ngay dưới tiêu đề. Phần mềm cũng có ID này trong grant.license.id.
• ID người dùng: bảng Người dùng cuối › Người dùng không hiện ID. Bạn lấy nó từ trường endUserId trong payload webhook user.created, hoặc từ danh sách người dùng của Seller API.

Thêm biến trong dashboard

1. Mở ứng dụng, vào Tích hợp › Biến.
2. Bấm Thêm biến.
3. Điền Tên: từ 1 đến 64 ký tự, bắt đầu bằng chữ cái hoặc dấu gạch dưới, sau đó chỉ gồm chữ cái không dấu, chữ số, _, . và -. Tên phân biệt hoa thường.
4. Điền Giá trị: tối đa 16.384 ký tự, không được để trống trong dashboard.
5. Chọn Phạm vi. Nếu không phải Mọi người dùng, ô ID license hoặc người dùng hiện ra và bắt buộc phải điền.
6. Bật Bí mật nếu giá trị cần được mã hoá (xem phần dưới).
7. Bấm Lưu. Thông báo Đã lưu biến xác nhận thành công.

Bảng liệt kê biến theo phạm vi rồi theo tên, với các cột Tên, Giá trị (biến bí mật hiện Đã ẩn), Phạm vi (kèm 12 ký tự đầu của ID) và Ngày tạo, cột này thực ra hiển thị lần lưu gần nhất.

Sửa và xoá

Bấm vào một dòng để mở hộp sửa. Tên bị khoá; muốn đổi tên, hãy xoá biến cũ và thêm biến mới. Mỗi bộ ba phạm vi, ID và tên chỉ có một biến, nên lưu lại với đúng bộ đó là ghi đè giá trị.

Để xoá, bấm biểu tượng thùng rác (Xoá) cuối dòng. Biến bị xoá ngay, không có hộp xác nhận và không hoàn tác được; thông báo Đã xoá biến hiện lên.

Mọi thành viên workspace đều xem được danh sách biến, nhưng chỉ Quản trị và Chủ sở hữu mới thêm, sửa, xoá được. Mỗi lần lưu hoặc xoá được ghi vào nhật ký kiểm toán với tên, phạm vi và cờ bí mật, không kèm giá trị.

Biến bí mật

Khi bật Bí mật, giá trị được mã hoá AES-256-GCM trước khi lưu và gắn với đúng ứng dụng, phạm vi, ID và tên của nó: bản mã chép sang dòng khác sẽ không giải mã được. Sau khi lưu:

• Dashboard chỉ hiện Đã ẩn, Seller API trả value: null. Không có cách nào đọc lại giá trị.
• Mở hộp sửa, ô Giá trị để trống. Muốn lưu bất kỳ thay đổi nào, bạn phải nhập lại toàn bộ giá trị. Tắt Bí mật khi nhập lại thì biến trở về dạng thường.

Chỉ phiên hợp lệ mới nhận biến

Server trao biến ở đúng hai chỗ: trong câu trả lời có chữ ký của một lần đăng nhập thành công (activate, trial, register, login, redeem), và qua lời gọi variables(). Lời gọi variables() đòi một phiên đang sống và kiểm tra giống heartbeat:

Server áp dụng quy tắc này cho mọi ứng dụng, bạn không cần bật gì. Đây là một phần của Kiểm soát phía server trong Bảo vệ Standard. Xem Hai chế độ bảo vệ.

Vài hệ quả cần biết:

• Biến không nằm trong token offline. Khi phần mềm chạy offline, nó không nhận được biến mới.
• Trong lúc bảo trì, phiên đang mở vẫn đọc biến bình thường; chỉ lượt đăng nhập mới bị chặn. Khi ứng dụng bị tạm dừng, mọi yêu cầu kể cả variables() nhận app_paused.

Đọc biến trong phần mềm

Với SDK JavaScript, biến có sẵn trong kết quả đăng nhập, và variables() lấy lại bản mới nhất mà không cần đăng nhập lại:

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

const grant = await clavis.activate(key);
const notice = grant.variables["notice"]; // undefined nếu không có
const limits = JSON.parse(grant.variables["limits"] ?? "{}");

// Sau này, khi cần giá trị mới nhất
try {
  const variables = await clavis.variables();
  applyConfig(variables);
} catch (err) {
  if (err instanceof ClavisError && err.code === "session_expired") {
    await signInAgain();
  } else {
    throw err;
  }
}

• variables là một object tên sang chuỗi, đã gộp theo thứ tự ưu tiên. Tên không có thì trả undefined, nên luôn chuẩn bị giá trị mặc định.
• variables() trả về { variables }, không phải object biến trực tiếp.
• Heartbeat không trả biến. Thay đổi trên dashboard đến phần mềm ở lần đăng nhập kế tiếp hoặc lần gọi variables() kế tiếp; server không tự đẩy xuống.
• Câu trả lời được ký như mọi câu trả lời khác, nên SDK từ chối giá trị bị sửa trên đường truyền.
• Đừng ghi giá trị bí mật ra đĩa hay vào log của phần mềm.

Quản lý biến qua Seller API

Để tự động hoá, ví dụ đặt hạn mức riêng cho một license ngay khi khách thanh toán, dùng Seller API với khoá có quyền variables:read hoặc variables:write:

• GET /apps/{appId}/variables: liệt kê biến, giá trị bí mật trả null.
• PUT /apps/{appId}/variables: tạo hoặc ghi đè theo bộ phạm vi, ID và tên.
• DELETE /variables/{id}: xoá một biến.

{ "key": "max_projects", "value": "10", "scope": "license", "scopeRef": "lic_…", "isSecret": false }

Quy tắc về tên, độ dài và scopeRef giống hệt dashboard. Chi tiết trong tham chiếu Seller API.

Liên quan

• Khái niệm cốt lõi
• SDK JavaScript
• Người dùng cuối
• Hai chế độ bảo vệ