FastComments Java SDK

Maven

將 Repsy 儲存庫新增到您專案的 POM：

<repositories>
    <repository>
        <id>repsy</id>
        <name>FastComments Maven Repository on Repsy</name>
        <url>https://repo.repsy.io/mvn/winrid/fastcomments</url>
    </repository>
</repositories>

接著新增您需要的相依項目：

<dependencies>
    <!-- API 用戶端 -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>client</artifactId>
        <version>2.0.0</version>
    </dependency>
    
    <!-- 核心函式庫（包含 SSO） -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>core</artifactId>
        <version>2.0.0</version>
    </dependency>
    
    <!-- PubSub 函式庫（用於即時事件） -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>pubsub</artifactId>
        <version>2.0.0</version>
    </dependency>
</dependencies>

Gradle

將 Repsy 儲存庫新增到您的 build.gradle 檔案：

repositories {
    mavenCentral()
    maven {
        url "https://repo.repsy.io/mvn/winrid/fastcomments"
    }
}

dependencies {
    // API 用戶端
    implementation "com.fastcomments:client:2.0.0"
    
    // 核心函式庫（包含 SSO）
    implementation "com.fastcomments:core:2.0.0"
    
    // PubSub 函式庫（用於即時事件）
    implementation "com.fastcomments:pubsub:2.0.0"
}

函式庫內容

此函式庫包含三個模組。已產生的 API 用戶端、包含手寫工具以便更容易使用 API 的核心 Java 函式庫，以及作為訂閱變更串流之用的 pubsub 模組。

• API Client Library Docs
• Core Library Docs, Including SSO Examples
• PubSub Library Docs

公開 API 與受保護 API

對於 API 用戶端，有三個類別，DefaultApi、PublicApi 與 ModerationApi。DefaultApi 包含需要您 API 金鑰的方法，而 PublicApi 包含可以直接從瀏覽器／行動裝置等在未驗證情況下呼叫的方法。

ModerationApi 提供管理員儀表板的功能。它包含評論管理的方法（列出、計數、搜尋、日誌與匯出）、審核操作（移除／還原、檢舉、設定審查／垃圾郵件／核准狀態、投票，以及重新開啟／關閉討論串）、封鎖（封鎖評論、撤銷封鎖、預封鎖摘要、封鎖狀態與偏好設定，以及被封鎖使用者計數），以及徽章與信任（授予／移除徽章、手動徽章、取得／設定信任因子，以及使用者內部資料）。每個 ModerationApi 方法都接受一個 sso 參數，以便在代表已透過 SSO 驗證的管理員的情況下執行呼叫。

使用已驗證的 API（DefaultApi）

重要： 您必須在 ApiClient 上設定您的 API 金鑰，才能進行已驗證的請求。如果未設定，請求將會以 401 錯誤失敗。

import com.fastcomments.invoker.ApiClient;
import com.fastcomments.invoker.ApiException;
import com.fastcomments.api.DefaultApi;
import com.fastcomments.model.*;

public class Example {
    public static void main(String[] args) {
        // 建立並設定 API client
        ApiClient apiClient = new ApiClient();

        // 必要：設定您的 API 金鑰（可從您的 FastComments 控制台取得）
        apiClient.setApiKey("YOUR_API_KEY_HERE");

        // 使用已設定的 client 建立 API 實例
        DefaultApi api = new DefaultApi(apiClient);

        // 現在您可以進行已驗證的 API 呼叫
        try {
            // 範例：新增 SSO 使用者
            CreateAPISSOUserData userData = new CreateAPISSOUserData();
            userData.setId("user-123");
            userData.setEmail("user@example.com");
            userData.setDisplayName("John Doe");

            AddSSOUserAPIResponse response = api.addSSOUser("YOUR_TENANT_ID", userData)
                .execute();
            System.out.println("User created: " + response);

        } catch (ApiException e) {
            System.err.println("Error: " + e.getResponseBody());
            // 常見錯誤：
            // - 401：API key 遺失或無效
            // - 400：請求驗證失敗
        }
    }
}

使用公開 API（PublicApi）

公開端點不需要驗證：

import com.fastcomments.api.PublicApi;
import com.fastcomments.invoker.ApiException;

PublicApi publicApi = new PublicApi();

try {
    var response = publicApi.getCommentsPublic("YOUR_TENANT_ID", "page-url-id")
        .execute();
    System.out.println(response);
} catch (ApiException e) {
    e.printStackTrace();
}

使用審核 API（ModerationApi）

ModerationApi 驅動版主儀表板。每個方法接受一個 sso 參數，用以識別代表哪位透過 SSO 驗證的版主發出請求：

import com.fastcomments.api.ModerationApi;
import com.fastcomments.invoker.ApiException;
import com.fastcomments.model.*;

ModerationApi moderationApi = new ModerationApi();

try {
    // 列出等待審核的留言
    ModerationAPIGetCommentsResponse response = moderationApi.getApiComments()
        .sso("YOUR_SSO_TOKEN")
        .execute();
    System.out.println(response);
} catch (ApiException e) {
    e.printStackTrace();
}

常見問題

1. 401 "missing-api-key" error：請確認在建立 DefaultApi 實例之前有呼叫 apiClient.setApiKey("YOUR_KEY")。
2. Wrong API class：伺服器端已驗證的請求請使用 DefaultApi，用戶端/公開請求請使用 PublicApi。
3. Null API key：若 API key 為 null，SDK 會悄悄跳過驗證，導致 401 錯誤。

廣播 ID

你會看到在某些 API 呼叫中要傳入一個 broadcastId。當你收到事件時，你會拿回這個 ID，所以如果你打算在客戶端樂觀地套用變更（你很可能會這樣做，因為它提供了最佳體驗），就知道要忽略該事件。這裡傳入一個 UUID。該 ID 應該夠唯一，不會在同一個瀏覽器工作階段中出現兩次。