開始整合
整合導覽：從零到第一次驗證
用最小步驟建立可重現的開發環境，完成首次註冊、後續驗證與錯誤紀錄。
你在開始前需要取得什麼
SDK 不從公開網站下載。授權管理員會透過受控方式提供 SDK Wheel 與該產品專用的公開部署參數。這些參數不是 Server Secret，但仍應由你的應用程式團隊管理版本與變更。
由管理員提供的正式版本，不要從不明來源取得。
Client 唯一需要連線的公開 HTTPS 入口。
識別產品與本機儲存區，兩者不可隨意變更。
驗證 Gateway 回應簽章的公開信任根。
建立乾淨環境
每個產品使用獨立虛擬環境，避免其他專案的依賴版本影響 SDK。正式建置環境應固定 Python 與依賴版本。
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install .\vendor\keygen_device_sdk.whl用 `.env.example` 建立第一次設定
Admin 交付的完整範例 ZIP 會包含 `.env.example`。先複製成 `.env`，與範例 `.py` 放在同一資料夾，再修改公開部署值。範例會用 Python 標準函式庫自行載入，不需要安裝 python-dotenv，也不要執行 source .env。
Copy-Item .\.env.example .\.env
notepad .\.env
python .\tpm_client_quickstart.pyKEYGEN_GATEWAY_URL="https://license.example.com"
KEYGEN_PRODUCT_ID="YOUR-PRODUCT-UUID"
KEYGEN_PRODUCT_NAMESPACE="com.example.your-product"
KEYGEN_GATEWAY_PUBLIC_KEY="PASTE-ED25519-PUBLIC-KEY"
KEYGEN_GATEWAY_KEY_ID="gateway-v1"
KEYGEN_FEATURE_CODE="HDL_EXPORT"env("ABC", "123")
先讀取 ABC；不存在或空白時回傳字串 123。省略第二個引數代表必填。需要數字時再使用 int 或 float 轉型。
設定優先序
OS／IDE／Service Manager Environment 優先，其次是 `.env`，最後才是程式預設值。讀取設定不會修改 License Server。
建立 ClientConfig
把管理員提供的公開部署參數集中在一個只讀設定模組。不要在不同畫面或功能中重複建立不同的 Client。
from keygen_device_sdk import ClientConfig, DeviceLicenseClient
client = DeviceLicenseClient(
ClientConfig(
gateway_base_url="https://license.example.com",
product_id="YOUR-PRODUCT-UUID",
product_namespace="com.example.your-product",
gateway_signing_public_key_b64="YOUR-GATEWAY-PUBLIC-KEY",
gateway_signing_key_id="gateway-v1",
connection_log_enabled=True,
)
)第一次與之後的啟動流程
- 檢查 requires_license_key
只有本機尚未完成註冊時才向使用者要求 License Key。
- 安全輸入 License Key
使用 getpass 或遮罩輸入框；不要保存到檔案或 Log。
- 呼叫 ensure_registered()
首次執行完成註冊；已有健康本機身分時執行線上驗證。
- 呼叫 require_valid()
把失敗轉成清楚、可處理的錯誤，而不是繼續執行。
正式整合前的最低測試矩陣
- 有效 License 首次註冊成功
- 第二次啟動使用 TPM Challenge，不要求保存 License Key
- 錯誤 License Key 被拒絕
- License 過期或撤銷時高價值功能停止
- 網路中斷時依產品規則處理
- Gateway Public Key 不符時拒絕回應
- connection.log 不包含 License Key 或 Token