Bắt đầu với công cụ dòng lệnh

Cần có

• Windows x64 hoặc Linux x64. Chưa có bản macOS và ARM.
• 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. Tải công cụ

Tải ở trang Tải về và kiểm SHA-256:

• Windows: clavis-cli-1.0.0-windows-x64.zip, gồm clavis.exe: một file, chỉ cần DLL có sẵn của Windows.
• Linux: clavis-cli-1.0.0-linux-x64.tar.gz, gồm clavis. Máy chạy cần glibc 2.34 trở lên, libsodium và libcurl của hệ thống (Debian, Ubuntu: apt install libsodium23 libcurl4).

Giải nén, đặt thư mục vào PATH hoặc gọi theo đường dẫn. Thử bằng clavis version, kết quả là {"ok":true,"version":"1.0.0"}.

2. Cài đặt và cách trả lời

Ba cài đặt của ứng dụng đến từ biến môi trường hoặc tuỳ chọn trên dòng lệnh:

Phiên được giữ trong thư mục trạng thái, nên các lệnh sau (heartbeat, variables, logout, offline) chạy ở tiến trình khác vẫn dùng đúng phiên đó. Mã thoát cho biết kết quả mà không cần đọc JSON:

Một câu trả lời thành công, rút gọn (khoá xếp theo thứ tự chữ cái; result chứa đúng những gì SDK trả về):

{"command":"activate","ok":true,"result":{"license":{"status":"active", …},"session":{"id":"ses_…", …}, …}}

Khi lỗi, dòng JSON là {"ok":false,"error":{"code","num","status","retryable","message"}}: code và num theo bảng Mã lỗi, message là câu cho người dùng theo --lang. Ký tự ngoài ASCII được viết dạng \u00e1, nên kết quả giống nhau trên mọi console; bộ đọc JSON nào cũng tự giải. clavis errors liệt kê đủ các mã.

3. K1 bằng bash

Kích hoạt, đọc mã thoát và JSON:

answer=$("$clavis" activate)
if [ $? -ne 0 ]; then
  echo "FAIL activate $(echo "$answer" | field code)"
  exit 1
fi
echo "activated: $(echo "$answer" | field status)"

Giữ phiên ở các lượt chạy sau, đọc một biến, rồi kết thúc phiên:

# A later command, another process: the session was kept in the state folder.
"$clavis" heartbeat > /dev/null || { echo "FAIL heartbeat"; exit 1; }
echo "motd: $("$clavis" variables | field motd)"
"$clavis" logout > /dev/null || { echo "FAIL logout"; exit 1; }

Một key không dùng được trả mã thoát 1 cùng mã lỗi:

# Exit code 1: refused (the key, the license...); 3: try again later; 4: the answer was not trusted.
# A mistyped key, from another state folder: a machine that holds no seat on it.
refused=$("$clavis" activate --key "${CLAVIS_LICENSE%????}ZZZZ" --state-dir "$state-other")
code=$?
rm -rf "$state-other"
echo "refused: $code $(echo "$refused" | field code)"
[ "$code" -eq 1 ] || { echo "FAIL refused"; exit 1; }

Nguyên script bash, kèm hàm phụ field đọc một trường của dòng JSON:

#!/usr/bin/env bash
# K1 with the command line tool from bash: activate, heartbeat, read a variable (motd, empty when the app has no such
# variable), end the session; then a refused key and a run without network. CLAVIS_CLI is the path of clavis; the
# other settings are the CLAVIS_* variables, the state folder defaulting to .clavis. Ends with "OK cli". Each answer
# is one line of JSON, so sed is enough here (jq works too).
set -u
clavis="$CLAVIS_CLI"
state="${CLAVIS_STATE_DIR:-.clavis}"
field() { sed -n "s/.*\"$1\":\"\\([^\"]*\\)\".*/\\1/p" | head -1; }

answer=$("$clavis" activate)
if [ $? -ne 0 ]; then
  echo "FAIL activate $(echo "$answer" | field code)"
  exit 1
fi
echo "activated: $(echo "$answer" | field status)"

# A later command, another process: the session was kept in the state folder.
"$clavis" heartbeat > /dev/null || { echo "FAIL heartbeat"; exit 1; }
echo "motd: $("$clavis" variables | field motd)"
"$clavis" logout > /dev/null || { echo "FAIL logout"; exit 1; }

# Exit code 1: refused (the key, the license...); 3: try again later; 4: the answer was not trusted.
# A mistyped key, from another state folder: a machine that holds no seat on it.
refused=$("$clavis" activate --key "${CLAVIS_LICENSE%????}ZZZZ" --state-dir "$state-other")
code=$?
rm -rf "$state-other"
echo "refused: $code $(echo "$refused" | field code)"
[ "$code" -eq 1 ] || { echo "FAIL refused"; exit 1; }

# No network: the offline token saved by activate answers on this machine (exit 0). Without one, as on a plan with
# no offline time, the answer is offline_unavailable (exit 1): going online helps, waiting does not.
offline=$("$clavis" offline --base-url "http://127.0.0.1:9")
code=$?
echo "offline: $code $(echo "$offline" | sed -n 's/.*"ok":\(true\|false\).*/\1/p')"
[ "$code" -le 1 ] || { echo "FAIL offline"; exit 1; }
echo "OK cli"

4. K1 bằng PowerShell

Cùng các bước, với ConvertFrom-Json đọc câu trả lời (nguyên script ở bước 5):

$answer = & $clavis activate | ConvertFrom-Json
if ($LASTEXITCODE -ne 0) {
    Write-Output $answer.error.message
    Write-Output "FAIL activate $($answer.error.code)"
    exit 1
}
Write-Output "activated: $($answer.result.license.status)"

# A later command, another process: the session was kept in the state folder.
$beat = & $clavis heartbeat | ConvertFrom-Json
if ($LASTEXITCODE -ne 0) { Write-Output "FAIL heartbeat $($beat.error.code)"; exit 1 }
$variables = & $clavis variables | ConvertFrom-Json
Write-Output "motd: $($variables.result.motd)"
& $clavis logout | Out-Null
if ($LASTEXITCODE -ne 0) { Write-Output "FAIL logout"; exit 1 }

# Exit code 1: refused (the key, the license...); 3: try again later; 4: the answer was not trusted.
# A mistyped key, from another state folder: a machine that holds no seat on it.
$key = $env:CLAVIS_LICENSE
$refused = & $clavis activate --key "$($key.Substring(0, $key.Length - 4))ZZZZ" --state-dir "$state-other" |
    ConvertFrom-Json
$code = $LASTEXITCODE
Remove-Item -Recurse -Force "$state-other" -ErrorAction SilentlyContinue
Write-Output "refused: $code $($refused.error.code)"
if ($code -ne 1) { Write-Output "FAIL refused"; exit 1 }

5. Chạy thử

1. Ở trang Kết nối phần mềm, bấm Tạo key thử nghiệm.
2. Lưu file đầy đủ dưới đây thành k1.ps1 (hoặc k1.sh cho bash, ở mục trên), đặt cài đặt cùng đường dẫn tới công cụ trong CLAVIS_CLI, rồi chạy:

# K1 with the command line tool from PowerShell: activate, heartbeat, read a variable (motd, empty when the app has no
# such variable), end the session; then a refused key and a run without network. CLAVIS_CLI is the path of clavis.exe;
# the other settings are the CLAVIS_* variables, the state folder defaulting to .clavis. Ends with "OK cli".
$clavis = $env:CLAVIS_CLI
$state = if ($env:CLAVIS_STATE_DIR) { $env:CLAVIS_STATE_DIR } else { ".clavis" }

$answer = & $clavis activate | ConvertFrom-Json
if ($LASTEXITCODE -ne 0) {
    Write-Output $answer.error.message
    Write-Output "FAIL activate $($answer.error.code)"
    exit 1
}
Write-Output "activated: $($answer.result.license.status)"

# A later command, another process: the session was kept in the state folder.
$beat = & $clavis heartbeat | ConvertFrom-Json
if ($LASTEXITCODE -ne 0) { Write-Output "FAIL heartbeat $($beat.error.code)"; exit 1 }
$variables = & $clavis variables | ConvertFrom-Json
Write-Output "motd: $($variables.result.motd)"
& $clavis logout | Out-Null
if ($LASTEXITCODE -ne 0) { Write-Output "FAIL logout"; exit 1 }

# Exit code 1: refused (the key, the license...); 3: try again later; 4: the answer was not trusted.
# A mistyped key, from another state folder: a machine that holds no seat on it.
$key = $env:CLAVIS_LICENSE
$refused = & $clavis activate --key "$($key.Substring(0, $key.Length - 4))ZZZZ" --state-dir "$state-other" |
    ConvertFrom-Json
$code = $LASTEXITCODE
Remove-Item -Recurse -Force "$state-other" -ErrorAction SilentlyContinue
Write-Output "refused: $code $($refused.error.code)"
if ($code -ne 1) { Write-Output "FAIL refused"; exit 1 }

# No network: the offline token saved by activate answers on this machine (exit 0). Without one, as on a plan with
# no offline time, the answer is offline_unavailable (exit 1): going online helps, waiting does not.
$offline = & $clavis offline --base-url "http://127.0.0.1:9" | ConvertFrom-Json
$code = $LASTEXITCODE
Write-Output "offline: $code $($offline.ok)"
if ($code -gt 1) { Write-Output "FAIL offline"; exit 1 }
Write-Output "OK cli"

$env:CLAVIS_CLI = "C:\duong-dan\clavis-cli-1.0.0-windows-x64\clavis.exe"
$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>"
powershell -NoProfile -ExecutionPolicy Bypass -File .\k1.ps1

Script in activated: active, motd: …, refused: 1 invalid_credentials (key gõ sai: mã thoát 1 và một mã chung cho mọi key không dùng được), offline: …, rồi OK cli ở dòng cuối; bước nào trả khác đi thì script dừng với FAIL …. Dòng motd: in biến tên motd của ứng dụng, để trống cho tới khi bạn tạo biến đó (Biến ứng dụng). Dòng offline: là 0 True khi máy này có token offline dùng được, và 1 False khi không có (offline_unavailable, ví dụ khi Chế độ chỉ online đang bật). -ExecutionPolicy Bypass cho phép chạy file script này dù Windows đang chặn script PowerShell (mặc định trên máy cá nhân). Trên Linux, chạy bash k1.sh với cùng các biến (export ...).

6. 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 cli/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ở.

7. Trong bộ cài và phát hành

• Bộ cài (Inno Setup, NSIS, WiX…) chạy clavis activate với key khách nhập, rồi đọc mã thoát: 0 thì cài tiếp, 1 thì hiện error.message cho khách, 3 thì mời thử lại khi có mạng.
• Đặt --state-dir ở nơi người dùng ghi được, riêng cho từng người dùng (ví dụ %APPDATA%\TênPhầnMềm), và dùng đúng thư mục đó cho mọi lệnh sau: phiên và token offline nằm ở đó, gắn với khoá thiết bị trong thư mục.
• Mật khẩu (kịch bản tài khoản) nên truyền qua CLAVIS_PASSWORD thay vì --password: dòng lệnh của một tiến trình người dùng khác trên máy có thể nhìn thấy.
• Truyền --app-version đú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.
• 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.

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

Không có mạng thì sao? clavis offline trả lời ngay trên máy: token offline lưu lần kích hoạt hay heartbeat gần nhất còn dùng được thì ok là true (mã thoát 0). Không có token dùng được thì trả offline_unavailable với mã thoát 1: cần lên mạng, chờ thì không giúp gì. Mọi gói đều có token, 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.

Ngôn ngữ của tôi gọi được hàm C? Khi đó thư viện C gọn hơn: không phải chạy tiến trình mới cho mỗi lượt.

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.

Liên quan

• Tải về
• Mã lỗi
• Bắt đầu với thư viện C
• Hệ thống hoạt động thế nào