Mục lục thư viện

Bắt đầu với Python

Bài này đưa một chương trình Python từ con số không tới lần kích hoạt license đầu tiên, rồi tới lúc đóng gói 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.

6 phút đọc

Cần có

Python 3.9 trở lên. SDK chỉ cần thêm một gói, cryptography, pip tự cài khi cài SDK.
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-0.1.0-py3-none-any.whl ở trang Tải về và kiểm SHA-256 như trang đó hướng dẫn. Nên cài vào môi trường ảo của dự án:

python -m venv .venv
.venv/bin/pip install clavisauh-0.1.0-py3-none-any.whl

Trên Windows, trong PowerShell:

python -m venv .venv
.venv\Scripts\pip install clavisauh-0.1.0-py3-none-any.whl

Lần cài đầu cần mạng để pip lấy cryptography. Nếu file bạn tải có số phiên bản mới hơn, đổi tên file trong lệnh cho khớp. SDK chưa có trên PyPI; khi có, bài này sẽ ghi thêm cách cài từ đó.

Muốn chạy thử trước? Nút Tải dự án mẫu (.zip) ở trang Kết nối phần mềm cho một thư mục có sẵn SDK, năm kịch bản K1 tới K5 và script chạy tự tạo môi trường ảo.

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 chỉ người dùng hiện tại đọc được; 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:

client = ClavisClient(
    os.environ["CLAVIS_BASE_URL"],
    os.environ["CLAVIS_APP_ID"],
    [os.environ["CLAVIS_APP_KEY"]],
    default_device(),
    # The same key every run: sessions and offline tokens stay with this machine.
    device_key=load_or_create_device_key(STATE / "device.key"),
    app_version="1.0.0",
)

Khoá công khai nằm trong một danh sách: lúc xoay khoá ký, bản build tin cả khoá hiện tại lẫn khoá kế tiếp (Khoá ký và xoay vòng khoá).

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:

try:
    client.init()
    grant = client.activate(os.environ["CLAVIS_LICENSE"])
except ClavisError as err:
    # No answer (network_error, timeout...): a token saved last time keeps the software working.
    offline = client.verify_offline(SAVED.read_text()) if err.retryable and SAVED.exists() else None
    if not offline:
        print(err.user_message(LANG))
        print("FAIL", err.code)
        sys.exit(1)
    print("Offline: using the license saved on this machine")
    grant = None

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 k1_key.py (dự án mẫu có sẵn file này), đặt bốn cài đặt rồi chạy bằng Python của môi trường ảo:

"""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=... python k1_key.py
"""

import os
import sys
from pathlib import Path

from clavisauh import ClavisClient, ClavisError, default_device, load_or_create_device_key

# Messages in Vietnamese need a UTF-8 console (the default on Linux and in Windows Terminal).
sys.stdout.reconfigure(encoding="utf-8")
LANG = os.environ.get("CLAVIS_LANG", "en")
STATE = Path(os.environ.get("CLAVIS_STATE_DIR", ".clavis"))
SAVED = STATE / "offline.token"

client = ClavisClient(
    os.environ["CLAVIS_BASE_URL"],
    os.environ["CLAVIS_APP_ID"],
    [os.environ["CLAVIS_APP_KEY"]],
    default_device(),
    # The same key every run: sessions and offline tokens stay with this machine.
    device_key=load_or_create_device_key(STATE / "device.key"),
    app_version="1.0.0",
)

try:
    client.init()
    grant = client.activate(os.environ["CLAVIS_LICENSE"])
except ClavisError as err:
    # No answer (network_error, timeout...): a token saved last time keeps the software working.
    offline = client.verify_offline(SAVED.read_text()) if err.retryable and SAVED.exists() else None
    if not offline:
        print(err.user_message(LANG))
        print("FAIL", err.code)
        sys.exit(1)
    print("Offline: using the license saved on this machine")
    grant = None

if grant:
    print("License", grant["license"]["status"], "until", grant["license"]["expiresAt"] or "forever")
    # Every few minutes while the software runs; sessions end after an hour without one.
    client.heartbeat()
    if client.offline_token:
        SAVED.write_text(client.offline_token)
    client.logout()
print("OK k1", grant["license"]["status"] if grant else "offline")

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>"
.venv/bin/python k1_key.py

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>"
.venv\Scripts\python k1_key.py

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 python/0.1.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 ClavisError có ba thứ bạn cần:

err.code: mã trong bảng Mã lỗi, ví dụ invalid_credentials hay device_limit.
err.user_message("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.
err.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.

Câu trả lời không mang đúng chữ ký của ứng dụng bị từ chối bằng ClavisVerificationError (cũng là một ClavisError), với 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.offline_token:
    SAVED.write_text(client.offline_token)

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ì tạo client với debug=True: 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 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.
Phần mềm gửi kèm Python và cryptography. Nếu bạn đóng gói thành một file chạy (PyInstaller, Nuitka…), hãy chạy thử bản đóng gói tới OK k1 active trên một máy sạch trước khi phát hành.
Câu tiếng Việt cần console UTF-8. Mẫu gọi sys.stdout.reconfigure(encoding="utf-8"); phần mềm có giao diện đồ hoạ thì không cần.
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

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.

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.

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.

Dùng thư viện C qua ctypes thay cho SDK được không? Được. Thư viện C (clavis.dll, libclavis.so, ở trang Tải về) không cần cài gói Python nào, hợp với nơi không cài được cryptography, và có cùng các lượt gọi chính. SDK Python thì trả dữ liệu dạng dict của Python và có thêm hàm tải file cập nhật kèm kiểm SHA-256.