Mục lục thư viện

Bắt đầu với Go

Bài này đưa một chương trình Go 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.

6 phút đọc

Cần có

Go 1.23 trở lên. SDK chỉ dùng thư viện chuẩn của Go, không kéo theo module nào khá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-go-1.0.0.zip ở trang Tải về, kiểm SHA-256 như trang đó hướng dẫn, rồi giải nén trong thư mục dự án (unzip clavisauh-go-1.0.0.zip, hoặc Expand-Archive clavisauh-go-1.0.0.zip . trong PowerShell): zip chứa một thư mục clavisauh-go-1.0.0 là SDK. Chương trình mới cần tạo module trước (go mod init; không cần go mod tidy), rồi trỏ tới thư mục đó:

go mod init myapp
go mod edit -require=clavisauh@v0.0.0 -replace=clavisauh=./clavisauh-go-1.0.0

go.mod khi đó có hai dòng:

require clavisauh v0.0.0

replace clavisauh => ./clavisauh-go-1.0.0

Rồi import "clavisauh" trong mã. SDK chưa có trên module proxy; 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 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. DefaultDevice("") mô tả máy bằng các định danh đã băm; tham số là tên máy hiện trên dashboard, để trống thì dùng tên máy (host name):

	deviceKey, err := clavisauh.LoadOrCreateDeviceKey(filepath.Join(state, "device.key"))
	if err != nil {
		fail(err)
	}
	client, err := clavisauh.New(clavisauh.Options{
		BaseURL:       os.Getenv("CLAVIS_BASE_URL"),
		AppID:         os.Getenv("CLAVIS_APP_ID"),
		AppPublicKeys: []string{os.Getenv("CLAVIS_APP_KEY")},
		Device:        clavisauh.DefaultDevice(""),
		// The same key every run: sessions and offline tokens stay with this machine.
		DeviceKey:  deviceKey,
		AppVersion: "1.0.0",
	})
	if err != nil {
		fail(err)
	}

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:

	var grant *clavisauh.Grant
	if _, err = client.Init(); err == nil {
		grant, err = client.Activate(os.Getenv("CLAVIS_LICENSE"))
	}
	if err != nil {
		// No answer (network_error, timeout...): a token saved last time keeps the software working.
		var e *clavisauh.Error
		token, _ := os.ReadFile(saved)
		if !errors.As(err, &e) || !e.Retryable() || len(token) == 0 || client.VerifyOffline(string(token)) == nil {
			fail(err)
		}
		fmt.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 main.go trong dự án của bạn (dự án mẫu, mỗi kịch bản một thư mục, có file này ở k1_key/main.go và chạy bằng go run ./k1_key), đặt bốn cài đặt rồi chạy:

// 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=... go run .
// (saved as main.go in your module; the starter project keeps it in k1_key/ and runs go run ./k1_key)
package main

import (
	"errors"
	"fmt"
	"os"
	"path/filepath"
	"time"

	"clavisauh"
)

func env(name, fallback string) string {
	if v := os.Getenv(name); v != "" {
		return v
	}
	return fallback
}

var (
	lang  = env("CLAVIS_LANG", "en")
	state = env("CLAVIS_STATE_DIR", ".clavis")
	saved = filepath.Join(state, "offline.token")
)

// fail prints the sentence for the user and the code, and stops.
func fail(err error) {
	var e *clavisauh.Error
	if !errors.As(err, &e) {
		e = &clavisauh.Error{Code: "unknown_error", Message: err.Error()}
	}
	fmt.Println(e.UserMessage(lang))
	fmt.Println("FAIL", e.Code)
	os.Exit(1)
}

func main() {
	deviceKey, err := clavisauh.LoadOrCreateDeviceKey(filepath.Join(state, "device.key"))
	if err != nil {
		fail(err)
	}
	client, err := clavisauh.New(clavisauh.Options{
		BaseURL:       os.Getenv("CLAVIS_BASE_URL"),
		AppID:         os.Getenv("CLAVIS_APP_ID"),
		AppPublicKeys: []string{os.Getenv("CLAVIS_APP_KEY")},
		Device:        clavisauh.DefaultDevice(""),
		// The same key every run: sessions and offline tokens stay with this machine.
		DeviceKey:  deviceKey,
		AppVersion: "1.0.0",
	})
	if err != nil {
		fail(err)
	}

	var grant *clavisauh.Grant
	if _, err = client.Init(); err == nil {
		grant, err = client.Activate(os.Getenv("CLAVIS_LICENSE"))
	}
	if err != nil {
		// No answer (network_error, timeout...): a token saved last time keeps the software working.
		var e *clavisauh.Error
		token, _ := os.ReadFile(saved)
		if !errors.As(err, &e) || !e.Retryable() || len(token) == 0 || client.VerifyOffline(string(token)) == nil {
			fail(err)
		}
		fmt.Println("Offline: using the license saved on this machine")
	}

	if grant == nil {
		fmt.Println("OK k1 offline")
		return
	}
	until := "forever"
	if grant.License.ExpiresAt != nil {
		until = grant.License.ExpiresAt.Format(time.RFC3339)
	}
	fmt.Println("License", grant.License.Status, "until", until)
	// Every few minutes while the software runs; sessions end after an hour without one.
	if _, err := client.Heartbeat(); err != nil {
		fail(err)
	}
	if client.OfflineToken != "" {
		if err := os.WriteFile(saved, []byte(client.OfflineToken), 0o600); err != nil {
			fail(err)
		}
	}
	_ = client.Logout()
	fmt.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>"
go run .

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>"
go run .

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 Go; 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 go/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 trả về một *clavisauh.Error, lấy ra bằng errors.As. Nó 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.
	if _, err := client.Heartbeat(); err != nil {
		fail(err)
	}

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

	if client.OfflineToken != "" {
		if err := os.WriteFile(saved, []byte(client.OfflineToken), 0o600); err != nil {
			fail(err)
		}
	}

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 Debug: clavisauh.DebugStderr trong Options: 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) trong os.UserConfigDir(), thêm tên phần mềm của bạn. Đừ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.
go build cho một file chạy duy nhất. Build chéo được: GOOS=windows GOARCH=amd64 go build ra file .exe từ Linux, cách CI của ClavisAUH build và chạy mẫu Go trên Windows.
Chạy thử bản build 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.

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.

Client có dùng chung giữa các goroutine được không? Không nên: client không an toàn khi nhiều goroutine gọi cùng lúc, vì mỗi lượt gọi đổi trạng thái phiên của nó. Giữ một client cho một goroutine, hoặc tự khoá bằng sync.Mutex khi gọi từ nhiều nơi.

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.