CI/CD 整合

Framedash CLI 可以與任何 CI/CD 系統整合。本指南涵蓋 Jenkins 及 TeamCity 的即用範例。

前置需求

1. 在 CI 環境中安裝 CLI：

npm install -g @framedash/cli

2. 效能閘門範例使用 jq 和 bc 進行 JSON 解析和閾值檢查。請確保它們已安裝在 CI 代理程式上。
3. 在 Framedash 儀表板的 設定 > API 金鑰 中建立 API 金鑰。
4. 從專案設定頁面記錄 專案 ID。

環境變數

在 CI 系統的密鑰管理中設定以下變數：

變數	必要	說明
FRAMEDASH_API_KEY	是	API 金鑰（上傳：fd_admin_*，唯讀：fd_*）
FRAMEDASH_PROJECT_ID	是	目標專案 UUID
FRAMEDASH_BASE_URL	否	自訂 API 主機 URL（預設：https://app.framedash.dev）

---

Jenkins

憑證設定

將 API 金鑰儲存為 Jenkins 憑證（Secret text）：

1. 前往 Manage Jenkins > Credentials > System > Global credentials
2. 新增 ID 為 framedash-api-key 的 Secret text 憑證
3. 新增 ID 為 framedash-project-id 的 Secret text 憑證

宣告式管線

建置後遙測確認

確認自動測試執行後遊戲建置是否正在傳送遙測資料：

pipeline {
    agent any

    environment {
        FRAMEDASH_API_KEY = credentials('framedash-api-key')
        FRAMEDASH_PROJECT_ID = credentials('framedash-project-id')
    }

    stages {
        stage('Build') {
            steps {
                sh 'your-game-build-command'
            }
        }

        stage('Automated Test') {
            steps {
                sh 'your-automated-test-command'
            }
        }

        stage('Verify Telemetry') {
            steps {
                sh '''
                    framedash auth
                    framedash status --format json > status.json
                    echo "Project status:"
                    framedash status --format table
                '''
            }
        }
    }
}

效能迴歸閘門

當效能指標低於閾值時使建置失敗：

pipeline {
    agent any

    environment {
        FRAMEDASH_API_KEY = credentials('framedash-api-key')
        FRAMEDASH_PROJECT_ID = credentials('framedash-project-id')
    }

    stages {
        stage('Build & Test') {
            steps {
                sh 'your-game-build-and-test-command'
            }
        }

        stage('Performance Gate') {
            steps {
                sh '''
                    RESULT=$(framedash query \
                        "SELECT avg(fps) as avg_fps, \
                                avg(frame_time_ms) as avg_frame_time \
                         FROM events \
                         WHERE event_name = 'performance_sample' \
                           AND timestamp > now() - INTERVAL 1 HOUR" \
                        --format json)

                    AVG_FPS=$(echo "$RESULT" | jq -r '.data[0].avg_fps // 0')

                    echo "Average FPS: $AVG_FPS"

                    if [ "$(echo "$AVG_FPS < 30" | bc -l)" -eq 1 ]; then
                        echo "FAILED: FPS below 30 threshold ($AVG_FPS)"
                        exit 1
                    fi

                    echo "PASSED: FPS meets threshold"
                '''
            }
        }
    }

    post {
        failure {
            echo 'Performance regression detected. Check the Framedash dashboard for details.'
        }
    }
}

地圖擷取上傳

在關卡建置後自動上傳地圖影像：

pipeline {
    agent any

    environment {
        FRAMEDASH_API_KEY = credentials('framedash-api-key')
        FRAMEDASH_PROJECT_ID = credentials('framedash-project-id')
    }

    stages {
        stage('Build Level') {
            steps {
                sh 'your-level-build-command'
            }
        }

        stage('Capture Maps') {
            steps {
                sh 'your-map-capture-command --output-dir ./map_captures'
            }
        }

        stage('Upload Maps') {
            steps {
                sh '''
                    framedash map-capture \
                        --input-dir ./map_captures \
                        --upload
                '''
            }
        }
    }
}

內容註冊表同步

將遊戲資料與內容註冊表同步：

pipeline {
    agent any

    environment {
        FRAMEDASH_API_KEY = credentials('framedash-api-key')
        FRAMEDASH_PROJECT_ID = credentials('framedash-project-id')
    }

    stages {
        stage('Sync Content') {
            steps {
                sh '''
                    framedash content import ./game-content.json
                    echo "Content registry updated"
                    framedash content list --format table
                '''
            }
        }
    }
}

共用程式庫

對於擁有多個遊戲專案的組織，可以建立 Jenkins 共用程式庫：

vars/framedashReport.groovy

def call(Map config = [:]) {
    def queryDays = config.get('days', 7)

    withCredentials([
        string(credentialsId: config.apiKeyCredentialId ?: 'framedash-api-key', variable: 'FRAMEDASH_API_KEY'),
        string(credentialsId: config.projectIdCredentialId ?: 'framedash-project-id', variable: 'FRAMEDASH_PROJECT_ID')
    ]) {
        sh """
            echo "Framedash dashboard (${queryDays}-day summary):"
            framedash dashboard --days ${queryDays} --format table
        """
    }
}

在 Jenkinsfile 中使用：

@Library('your-shared-lib') _

pipeline {
    agent any
    stages {
        stage('Framedash Report') {
            steps {
                framedashReport(days: 7)
            }
        }
    }
}

---

TeamCity

參數設定

在建置組態中新增 Configuration Parameters：

1. 前往 Build Configuration > Parameters
2. 新增參數 env.FRAMEDASH_API_KEY（類型：Password，spec：password display='hidden'）
3. 新增參數 env.FRAMEDASH_PROJECT_ID（類型：Text）

或在 專案 層級定義以在建置組態間共用。

建置步驟

建置後遙測確認

新增一個 Command Line 建置步驟：

步驟名稱： Verify Framedash Telemetry

#!/bin/bash
set -euo pipefail

echo "Verifying Framedash authentication..."
framedash auth

echo "Project status:"
framedash status --format table

效能迴歸閘門

新增一個 Command Line 建置步驟：

步驟名稱： Framedash Performance Gate

#!/bin/bash
set -euo pipefail

echo "Querying performance metrics..."
RESULT=$(framedash query \
    "SELECT avg(fps) as avg_fps, \
            avg(frame_time_ms) as avg_frame_time \
     FROM events \
     WHERE event_name = 'performance_sample' \
       AND timestamp > now() - INTERVAL 1 HOUR" \
    --format json)

AVG_FPS=$(echo "$RESULT" | jq -r '.data[0].avg_fps // 0')

echo "Average FPS: $AVG_FPS"

if [ "$(echo "$AVG_FPS < 30" | bc -l)" -eq 1 ]; then
    echo "##teamcity[buildProblem description='FPS below threshold: $AVG_FPS']"
    exit 1
fi

echo "##teamcity[buildStatisticValue key='framedash.avgFps' value='$AVG_FPS']"
echo "Performance gate passed"

提示

TeamCity 的服務訊息可用於報告自訂統計資料和建置問題。buildStatisticValue 訊息使 FPS 可在 TeamCity 統計圖表中追蹤。

地圖擷取上傳

新增一個 Command Line 建置步驟：

步驟名稱： Upload Map Captures

#!/bin/bash
set -euo pipefail

echo "Validating map captures..."
framedash map-capture --input-dir ./map_captures --dry-run

echo "Uploading map captures..."
framedash map-capture --input-dir ./map_captures --upload

漏斗分析報告

新增一個追蹤轉換漏斗的 Command Line 建置步驟：

#!/bin/bash
set -euo pipefail

echo "Funnel analysis (7-day window):"
framedash funnel \
    --steps "tutorial_start,tutorial_complete,first_purchase" \
    --days 7 \
    --format table

建置組態範本（Kotlin DSL）

使用 Kotlin DSL 的 TeamCity 專案：

import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.buildSteps.script

object FramedashPerformanceGate : BuildType({
    name = "Framedash Performance Gate"

    params {
        password("env.FRAMEDASH_API_KEY", "", display = ParameterDisplay.HIDDEN)
        text("env.FRAMEDASH_PROJECT_ID", "")
        text("framedash.minFps", "30", label = "Minimum FPS Threshold")
    }

    steps {
        script {
            name = "Install Framedash CLI"
            scriptContent = "npm install -g @framedash/cli"
        }
        script {
            name = "Performance Gate"
            scriptContent = """
                #!/bin/bash
                set -euo pipefail

                MIN_FPS=%framedash.minFps%

                RESULT=${'$'}(framedash query \
                    "SELECT avg(fps) as avg_fps FROM events \
                     WHERE event_name = 'performance_sample' \
                       AND timestamp > now() - INTERVAL 1 HOUR" \
                    --format json)

                AVG_FPS=${'$'}(echo "${'$'}RESULT" | jq -r '.data[0].avg_fps // 0')

                echo "Average FPS: ${'$'}AVG_FPS (threshold: ${'$'}MIN_FPS)"

                if [ "${'$'}(echo "${'$'}AVG_FPS < ${'$'}MIN_FPS" | bc -l)" -eq 1 ]; then
                    echo "##teamcity[buildProblem description='FPS below threshold']"
                    exit 1
                fi

                echo "##teamcity[buildStatisticValue key='framedash.avgFps' value='${'$'}AVG_FPS']"
            """.trimIndent()
        }
    }
})

元執行器

建立可重複使用的元執行器。儲存為專案 .teamcity/pluginData/metaRunners/ 目錄下的 Framedash_Performance_Gate.xml：

<?xml version="1.0" encoding="UTF-8"?>
<meta-runner name="Framedash Performance Gate">
  <description>Check game performance metrics via Framedash CLI</description>
  <settings>
    <parameters>
      <param name="framedash.minFps" value="30"
             spec="text description='Minimum acceptable FPS' label='Min FPS'" />
      <param name="framedash.queryDays" value="7"
             spec="text description='Number of days to query' label='Query Days'" />
    </parameters>
    <build-runners>
      <runner name="Framedash Performance Gate" type="simpleRunner">
        <parameters>
          <param name="script.content"><![CDATA[
#!/bin/bash
set -euo pipefail

framedash auth

MIN_FPS=%framedash.minFps%

RESULT=$(framedash query \
    "SELECT avg(fps) as avg_fps FROM events \
     WHERE event_name = 'performance_sample' \
       AND timestamp > now() - INTERVAL %framedash.queryDays% DAY" \
    --format json)

AVG_FPS=$(echo "$RESULT" | jq -r '.data[0].avg_fps // 0')

echo "Average FPS: $AVG_FPS (threshold: $MIN_FPS)"

if [ "$(echo "$AVG_FPS < $MIN_FPS" | bc -l)" -eq 1 ]; then
    echo "##teamcity[buildProblem description='FPS below threshold: $AVG_FPS < $MIN_FPS']"
    exit 1
fi

echo "##teamcity[buildStatisticValue key='framedash.avgFps' value='$AVG_FPS']"
echo "Performance gate passed"
]]></param>
          <param name="teamcity.step.mode" value="default" />
          <param name="use.custom.script" value="true" />
        </parameters>
      </runner>
    </build-runners>
  </settings>
</meta-runner>

---

常用模式

基於 SQL 的品質閘門

使用 framedash query 和 SQL 檔案進行可重複的檢查：

-- checks/fps-threshold.sql
SELECT
    avg(fps) as avg_fps,
    min(fps) as min_fps,
    quantile(0.05)(fps) as p5_fps
FROM events
WHERE event_name = 'performance_sample'
  AND timestamp > now() - INTERVAL 1 DAY

framedash query --file checks/fps-threshold.sql --format json

輸出格式的活用

CI 解析使用 --format json 搭配 jq：

# 擷取單一值
framedash dashboard --days 1 --format json | jq '.data.kpis.totalEvents'

# 確認專案狀態
framedash status --format json | jq '.data.project.name'

建置日誌的可讀性使用 --format table：

framedash dashboard --days 7 --format table
framedash retention --days 30 --format table

夜間效能報告

排程夜間建置以產生效能摘要：

#!/bin/bash
set -euo pipefail

echo "=== Framedash Nightly Report ==="
echo ""
echo "--- Project Status ---"
framedash status --format table
echo ""
echo "--- 7-Day Dashboard ---"
framedash dashboard --days 7 --format table
echo ""
echo "--- Player Retention ---"
framedash retention --days 30 --format table
echo ""
echo "--- Alert Rules ---"
framedash alerts list --format table

---

疑難排解

驗證錯誤

Error: Unauthorized (401)

• 確認 FRAMEDASH_API_KEY 已設定且有效
• 執行 framedash auth 測試金鑰
• 地圖上傳需要管理員金鑰（fd_admin_*）

請求限制

Error: Too Many Requests (429)

• CLI 會顯示 X-RateLimit-Reset 中的重設時間
• 在管線指令碼中加入退避重試
• 如需更高限制請考慮升級方案

網路 / 代理

如果 CI 環境使用代理伺服器：

export HTTPS_PROXY=http://proxy.example.com:8080
framedash auth

找不到 CLI

確保 CLI 已安裝在 CI 代理程式的 PATH 中：

# 確認安裝
which framedash || npm install -g @framedash/cli

# 不進行全域安裝使用 npx
npx @framedash/cli auth

下一步

• CLI 參考 — 指令完整文件
• API 參考 — REST API 的詳細說明
• CI 效能分析 — 自動效能分析設定