Mục lục thư viện

Bắt đầu với Java và Kotlin

Bài này đưa một chương trình Java từ con số không tới lần kích hoạt license đầu tiên, rồi tới bản build cho khách: cài SDK, vài dòng mã, chạy thử, xem kết quả trên dashboard, xử lý lỗi và phát hành. Kotlin và các ngôn ngữ JVM khác gọi cùng các hàm, có ghi chú ở cuối.

6 phút đọc

Cần có

JDK 17 trở lên. Lúc chạy, SDK không cần thư viện nào ngoài JDK: Ed25519 và HTTP lấy từ JDK, JSON do SDK tự đọc.
Một ứng dụng trên dashboard. Trang Tích hợp › Kết nối phần mềm của nó có địa chỉ API, App ID, khoá công khai và nút Tạo key thử nghiệm. Địa chỉ API kết thúc bằng /api, không có /v1: https://<trang ClavisAUH của bạn>/api.

1. Cài SDK

Tải clavisauh-1.0.0.jar ở trang Tải về và kiểm SHA-256 như trang đó hướng dẫn. Rồi chọn một trong ba cách: Maven, Gradle, hoặc không dùng công cụ build (bước 3 dùng cách cuối).

# Maven: cài jar vào kho cục bộ một lần
mvn install:install-file -Dfile=clavisauh-1.0.0.jar -DgroupId=clavisauh -DartifactId=clavisauh -Dversion=1.0.0 -Dpackaging=jar

rồi thêm dependency vào pom.xml:

<dependency>
  <groupId>clavisauh</groupId>
  <artifactId>clavisauh</artifactId>
  <version>1.0.0</version>
</dependency>

Với Gradle, đặt jar vào thư mục libs/ và thêm implementation(files("libs/clavisauh-1.0.0.jar")) vào dependencies. Không dùng công cụ build thì chỉ cần đưa jar vào class path: java -cp clavisauh-1.0.0.jar ….

SDK chưa có trên Maven Central; khi có, bài này sẽ ghi thêm cách cài từ đó.

2. Mã tối thiểu

Các khối dưới đây là từng phần của một file; file đầy đủ, kèm import và hàm phụ, ở bước 3.

Tạo client một lần khi phần mềm khởi động. Địa chỉ API, App ID và khoá công khai là ba giá trị ở trang Kết nối phần mềm: mẫu đọc chúng từ biến môi trường, phần mềm của bạn thì ghi thẳng vào mã. Khoá thiết bị nằm trong một file; phiên và token offline gắn với khoá này, còn suất trên license đi theo các định danh đã băm của máy:

ClavisClient client = ClavisClient
        .builder(env("CLAVIS_BASE_URL", ""), env("CLAVIS_APP_ID", ""), List.of(env("CLAVIS_APP_KEY", "")))
        .device(Device.defaultDevice(null))
        // The same key every run: sessions and offline tokens stay with this machine.
        .deviceKey(DeviceKey.loadOrCreate(state.resolve("device.key")))
        .appVersion("1.0.0")
        .build();

Kích hoạt key của khách. Khi không có mạng, token offline lưu lần trước giữ phần mềm chạy tiếp:

Grant grant = null;
try {
    client.init();
    grant = client.activate(env("CLAVIS_LICENSE", ""));
} catch (ClavisException e) {
    // No answer (network_error, timeout...): a token saved last time keeps the software working.
    String token = Files.exists(saved) ? Files.readString(saved) : null;
    if (!e.retryable() || token == null || client.verifyOffline(token).isEmpty()) {
        System.out.println(e.userMessage(lang));
        System.out.println("FAIL " + e.code());
        System.exit(1);
    }
    System.out.println("Offline: using the license saved on this machine");
}

Khoá công khai chỉ dùng để kiểm chữ ký, nhúng vào phần mềm là an toàn. Đừng bao giờ nhúng một khoá bí mật nào.

3. Chạy thử

Ở trang Kết nối phần mềm, bấm Tạo key thử nghiệm. Key TEST hết hạn sau 24 giờ và không tính hạn mức.
Lưu file đầy đủ dưới đây thành K1Key.java cạnh file jar, đặt bốn cài đặt rồi chạy thẳng file nguồn, không cần biên dịch trước:

// K1 · License key only: activate on this machine, keep the session alive, work offline for a while.
//
// Run: CLAVIS_BASE_URL=... CLAVIS_APP_ID=... CLAVIS_APP_KEY=... CLAVIS_LICENSE=...
//      java -cp clavisauh-1.0.0.jar K1Key.java

import clavisauh.ClavisClient;
import clavisauh.ClavisException;
import clavisauh.Device;
import clavisauh.DeviceKey;
import clavisauh.Grant;
import java.io.FileDescriptor;
import java.io.FileOutputStream;
import java.io.PrintStream;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;

public class K1Key {
    static String env(String name, String fallback) {
        String value = System.getenv(name);
        return value == null || value.isEmpty() ? fallback : value;
    }

    public static void main(String[] args) throws Exception {
        // Messages in Vietnamese need a UTF-8 console (the default on Linux and in Windows Terminal).
        System.setOut(new PrintStream(new FileOutputStream(FileDescriptor.out), true, StandardCharsets.UTF_8));
        String lang = env("CLAVIS_LANG", "en");
        Path state = Path.of(env("CLAVIS_STATE_DIR", ".clavis"));
        Path saved = state.resolve("offline.token");

        ClavisClient client = ClavisClient
                .builder(env("CLAVIS_BASE_URL", ""), env("CLAVIS_APP_ID", ""), List.of(env("CLAVIS_APP_KEY", "")))
                .device(Device.defaultDevice(null))
                // The same key every run: sessions and offline tokens stay with this machine.
                .deviceKey(DeviceKey.loadOrCreate(state.resolve("device.key")))
                .appVersion("1.0.0")
                .build();

        Grant grant = null;
        try {
            client.init();
            grant = client.activate(env("CLAVIS_LICENSE", ""));
        } catch (ClavisException e) {
            // No answer (network_error, timeout...): a token saved last time keeps the software working.
            String token = Files.exists(saved) ? Files.readString(saved) : null;
            if (!e.retryable() || token == null || client.verifyOffline(token).isEmpty()) {
                System.out.println(e.userMessage(lang));
                System.out.println("FAIL " + e.code());
                System.exit(1);
            }
            System.out.println("Offline: using the license saved on this machine");
        }

        if (grant == null) {
            System.out.println("OK k1 offline");
            return;
        }
        Object until = grant.license().expiresAt() != null ? grant.license().expiresAt() : "forever";
        System.out.println("License " + grant.license().status() + " until " + until);
        // Every few minutes while the software runs; sessions end after an hour without one.
        client.heartbeat();
        if (client.offlineToken() != null) Files.writeString(saved, client.offlineToken());
        client.logout();
        System.out.println("OK k1 " + grant.license().status());
    }
}

export CLAVIS_BASE_URL="<địa chỉ API>"
export CLAVIS_APP_ID="<App ID>"
export CLAVIS_APP_KEY="<khoá công khai>"
export CLAVIS_LICENSE="<key thử nghiệm>"
java -cp clavisauh-1.0.0.jar K1Key.java

Trên Windows, trong PowerShell:

$env:CLAVIS_BASE_URL = "<địa chỉ API>"
$env:CLAVIS_APP_ID = "<App ID>"
$env:CLAVIS_APP_KEY = "<khoá công khai>"
$env:CLAVIS_LICENSE = "<key thử nghiệm>"
java -cp clavisauh-1.0.0.jar K1Key.java

Dự án mẫu (nút Tải dự án mẫu (.zip) ở trang Kết nối phần mềm trên dashboard, sau khi chọn Java; không có ở trang Tải về) chạy kịch bản này bằng ./run.sh <key> hoặc .\run.cmd <key>.

Mẫu in License active until <ngày>, rồi OK k1 active ở dòng cuối. Chạy lại trên cùng máy vẫn thành công và không tốn thêm suất: server nhận ra máy qua các định danh đã băm (Thiết bị, HWID và chuyển máy). Khoá thiết bị, dùng để ký yêu cầu, nằm trong thư mục .clavis dưới thư mục bạn chạy lệnh (hoặc trong CLAVIS_STATE_DIR). Container tạo mới cho mỗi lần chạy thì lần nào cũng giống một máy mới, xem Câu hỏi thường gặp.

4. Thấy trên dashboard

Tích hợp › Kết nối phần mềm: bước 4 chuyển sang Đã kết nối, kèm java/1.0.0 và hệ điều hành của máy.
Phát hành & bản quyền › License: key chuyển từ Chưa dùng sang Đang dùng.
Người dùng cuối › Thiết bị & phiên: máy vừa chạy, cùng phiên nó vừa mở.

5. Xử lý lỗi

Mọi lần bị từ chối là một ClavisException có ba thứ bạn cần:

e.code(): mã trong bảng Mã lỗi, ví dụ invalid_credentials hay device_limit.
e.userMessage("vi"): câu cho người dùng phần mềm của bạn, tiếng Việt hoặc "en", hiện thẳng được.
e.retryable(): true khi không nhận được câu trả lời (mất mạng, quá chậm, máy chủ bận); để một lúc rồi thử lại có thể thành công.

Khi e.verification() là true, câu trả lời không mang đúng chữ ký của ứng dụng (mã unsigned_response, invalid_response_signature, unknown_key hoặc stale_response). Hãy coi đó như không có câu trả lời; thường là địa chỉ API hoặc khoá công khai trong phần mềm bị sai.

Khi phần mềm đang chạy, gửi heartbeat đều đặn để giữ phiên, khoảng mỗi 5 tới 30 phút: phiên hết sau 60 phút không có heartbeat.

// Every few minutes while the software runs; sessions end after an hour without one.
client.heartbeat();

Lưu token offline mới nhất, để lần sau không có mạng vẫn mở được:

if (client.offlineToken() != null) Files.writeString(saved, client.offlineToken());

Mọi gói đều có token offline, mặc định dùng được 7 ngày; Premium tự chọn thời hạn, còn Chế độ chỉ online thì tắt hẳn. Xem License offline. Cần xem từng lượt gọi khi dò lỗi thì thêm .debug(ClavisClient.DEBUG_STDERR) vào builder: mỗi lượt gọi và kết quả được in ra stderr, key chỉ hiện bốn ký tự đầu và cuối, mật khẩu không bao giờ hiện.

6. Đóng gói và phát hành

Ghi địa chỉ API, App ID và khoá công khai vào mã hoặc vào file cấu hình đi cùng bản build. Máy khách không cần biến môi trường nào.
Đặt thư mục trạng thái (khoá thiết bị, token offline) ở nơi người dùng ghi được, riêng cho từng người dùng: %APPDATA%\TênPhầnMềm trên Windows, ~/Library/Application Support/TênPhầnMềm trên macOS, ~/.config/ten-phan-mem trên Linux. Đừng đặt trong thư mục cài đặt.
Truyền .appVersion(...) đúng phiên bản bạn phát hành: server dùng nó để chặn bản quá cũ và báo có bản mới, xem Bản phát hành có ký và cập nhật.
Đóng jar SDK cùng phần mềm (một jar gộp, hoặc jar SDK đặt cạnh trên class path). jpackage của JDK tạo bộ cài kèm sẵn Java nếu khách không có Java.
Chạy thử bản phát hành tới OK k1 active trên một máy sạch trước khi phát hành.
Trước khi bán, bật Đã phát hành công khai ở Tích hợp › Cài đặt ứng dụng. Mọi key TEST ngừng hoạt động, nên key thử nào lỡ lọt ra ngoài cũng không dùng được nữa.

Với Kotlin

Kotlin dùng cùng jar và cùng các hàm. Gradle Kotlin DSL thêm implementation(files("libs/clavisauh-1.0.0.jar")); mã gọi giống Java, chỉ khác cú pháp, ví dụ ClavisClient.builder(baseUrl, appId, listOf(publicKey)) rồi .device(Device.defaultDevice(null)), .deviceKey(DeviceKey.loadOrCreate(path)), .build(). SDK chưa được thử trên Android.

Câu hỏi thường gặp

Phần mềm có cần mạng mỗi lần mở không? Kích hoạt và heartbeat cần mạng. Khi mất mạng, token đã lưu giữ phần mềm chạy tiếp, mặc định 7 ngày hoặc theo thời hạn chọn trên Premium, được kiểm ngay trên máy mà không cần server.

Dùng một client từ nhiều luồng được không? Không nên: client không an toàn khi nhiều luồng gọi cùng lúc. Giữ một client cho một luồng, hoặc tự khoá khi gọi từ nhiều nơi. Trong ứng dụng Swing hay JavaFX, đừng gọi trên luồng giao diện, vì mỗi lượt gọi chờ mạng.

Giới hạn tính năng theo gói license thế nào? client.has("ten_tinh_nang") cho biết license có quyền tính năng đó không; tạo quyền trong Gói license và quyền tính năng.

Khách cài lại hệ điều hành hay đổi máy thì sao? Cài lại trên cùng máy, server vẫn nhận ra máy nhờ dấu nhận diện phần cứng đã băm. Máy mới chiếm một suất mới; hết suất thì khách nhận device_limit, và bạn Đặt lại thiết bị trong trang License. Xem Thiết bị, HWID và chuyển máy.