Ruby 軟體授權整合：啟用授權與保護業務區塊

1. 準備產品與授權

先使用裝置綁定授權與一般匯出功能，確認授權流程正常後再增加功能次數計量。

裝置額度按目前啟用裝置計算，釋放後返還；一般授權離線仍占用，浮動授權租約到期後自動返還。

在控制台「產品」複製產品 ID，點擊同一產品的「簽章公鑰」，將每一組金鑰 ID、公鑰填入初始化程式碼，取代 YOUR_PRODUCT_ID、YOUR_KEY_ID 和 YOUR_PUBLIC_KEY。快速接入也可直接複製已填好的程式碼。無需設定檔；SDK 預設連線至 https://www.licentivo.com。
在「快速整合」建立或選擇產品，在策略中啟用名為 export 的功能，並準備測試授權。

2. 安裝 SDK

在自己的應用程式專案中執行下方安裝命令或加入建置依賴，安裝 SDK 0.11.6。套件管理器負責取得 SDK，無需下載解壓原始碼套件或設定本機原始碼路徑。

Terminal

gem install licentivo-sdk --version 0.11.6

3. 保護一次實際匯出

將 SDK 初始化接到自己軟體的啟動或啟用入口，從啟用視窗讀取客戶授權碼，傳入產品 ID、信任公鑰並保持用戶端存活。將 RunFeature 放在實際業務入口，以自己的功能取代匯出範例函式。

Ruby 3.1+ · main.rb

# frozen_string_literal: true
require 'licentivo'

# BEGIN LICENTIVO PRODUCT
# Copy Product ID and all key ID/public key pairs from Console > Products > Signing public keys.
PRODUCT_ID = 'YOUR_PRODUCT_ID'
TRUSTED_KEYS = {'YOUR_KEY_ID' => 'YOUR_PUBLIC_KEY'}.freeze
# END LICENTIVO PRODUCT

def setting(name, fallback)
  value = ENV[name]
  value.nil? || value.empty? ? fallback : value
end

def export_report(path)
  # Replace this write with your existing export operation.
  File.write(path, "A report generated by the licensed application.\n")
end

begin
  # A GUI supplies the activation input. Later starts use an empty key.
  Licentivo::Client.open_product(
    PRODUCT_ID, TRUSTED_KEYS,
    setting('LICENTIVO_LICENSE_KEY', '')
  ) do |client|
    feature = setting('LICENTIVO_FEATURE', 'export')
    path = setting('LICENTIVO_OUTPUT', 'licensed-report.txt')
    if setting('LICENTIVO_METERED', '0') == '1'
      client.run_metered_feature(feature, 1, setting('LICENTIVO_OPERATION_ID', '')) { export_report(path) }
    else
      client.run_feature(feature) { export_report(path) }
    end
    puts "License OK: #{feature} is available\nExport completed: #{path}"
  end # Real app: keep the owning block/client alive until shutdown.
rescue StandardError => error
  warn error.message
  exit 2
end

4. 在應用程式結束時關閉用戶端

本命令列範例執行一次操作後結束。整合桌面應用程式時，在啟動時建立一個用戶端，在匯出按鈕或命令中呼叫功能回呼，直到應用程式結束才關閉用戶端。

首次啟用後，後續啟動可將 LICENTIVO_LICENSE_KEY 留空，在相同使用者及快取位置還原私有裝置憑證。憑證儲存在使用者應用程式資料目錄，不隨安裝套件散布。關閉用戶端會停止心跳並歸還浮動席位；一般結束不應取消裝置綁定。

只有策略允許、簽章授權仍有效時才能離線使用。授權過期或功能遭拒時持續阻止業務操作；功能次數計量需要連線。

open_with_license 區塊持有用戶端；讓應用程式主迴圈在它的生命週期內執行，每次受保護操作呼叫 run_feature。請勿在業務回呼中關閉用戶端；SDK 處理失敗操作後會繼續拋出 Ruby 例外。

5. 執行並核對結果

在控制台「產品」複製產品 ID，點擊同一產品的「簽章公鑰」，將每一組金鑰 ID、公鑰填入初始化程式碼，取代 YOUR_PRODUCT_ID、YOUR_KEY_ID 和 YOUR_PUBLIC_KEY。快速接入也可直接複製已填好的程式碼。無需設定檔；SDK 預設連線至 https://www.licentivo.com。

使用允許 export 的有效授權執行，確認產生 licensed-report.txt。
清空 LICENTIVO_LICENSE_KEY，以相同使用者再次執行，確認可還原已儲存的裝置憑證。
將 LICENTIVO_FEATURE 改為授權未提供的功能，並將 LICENTIVO_OUTPUT 改為新檔名。程式應提示拒絕，而且不產生新檔案。
僅在策略允許且簽章授權未到期時測試離線重新啟動。背景更新發生錯誤後，也不能略過失敗的功能檢查。

Windows · PowerShell

$env:LICENTIVO_LICENSE_KEY = 'YOUR_LICENSE_KEY'
ruby main.rb

Linux / macOS · Bash

LICENTIVO_LICENSE_KEY=YOUR_LICENSE_KEY ruby main.rb

常見整合問題

檢查產品 ID、每組金鑰 ID 和公鑰、客戶輸入的授權碼。公鑰屬於產品；客戶授權與本機憑證分別管理。開發測試授權碼及廠商管理 API Key 不隨客戶安裝包發送。

功能遭拒、裝置數已滿或授權過期：在控制台核對授權與策略，並向客戶顯示 SDK 錯誤。授權失敗時不能呼叫匯出函式。

一般功能介面只檢查權限；計次介面負責預留與結算已設定的用量。每項實際業務使用獨立且穩定的操作編號；中斷還原前先核對持久化業務結果。

無法載入 licentivo 時，檢查 gem 安裝與程式執行是否使用同一 Ruby 環境。Windows 從原始碼建置時設定 LICENTIVO_CURL_ROOT，並讓 PATH 能找到相符的 libcurl DLL。

SDK 參考: Ruby 3.1+ SDK →