FastComments 자바 SDK

Maven

프로젝트의 POM에 Repsy 저장소를 추가하세요:

<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 Client -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>client</artifactId>
        <version>1.3.2</version>
    </dependency>
    
    <!-- Core Library (includes SSO) -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>core</artifactId>
        <version>1.3.2</version>
    </dependency>
    
    <!-- PubSub Library (for live events) -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>pubsub</artifactId>
        <version>1.3.2</version>
    </dependency>
</dependencies>

Gradle

build.gradle 파일에 Repsy 저장소를 추가하세요:

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

dependencies {
    // API Client
    implementation "com.fastcomments:client:1.3.2"
    
    // Core Library (includes SSO)
    implementation "com.fastcomments:core:1.3.2"
    
    // PubSub Library (for live events)
    implementation "com.fastcomments:pubsub:1.3.2"
}

라이브러리 구성

이 라이브러리에는 세 개의 모듈이 포함되어 있습니다. 생성된 API 클라이언트, API 작업을 더 쉽게 해주는 수작업으로 작성된 유틸리티를 포함하는 코어 Java 라이브러리, 그리고 변경 피드를 구독하기 위한 라이브러리인 pubsub 모듈입니다.

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

공개 vs 보호된 API

API 클라이언트에는 DefaultApi와 PublicApi의 두 클래스가 있습니다. DefaultApi는 API 키가 필요한 메서드를 포함하고, PublicApi는 브라우저/모바일 기기 등에서 인증 없이 직접 호출할 수 있는 API 호출을 포함합니다.

인증된 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 클라이언트를 생성하고 구성합니다
        ApiClient apiClient = new ApiClient();

        // REQUIRED: Set your API key (get this from your FastComments dashboard)
        apiClient.setApiKey("YOUR_API_KEY_HERE");

        // 구성된 클라이언트로 API 인스턴스를 생성합니다
        DefaultApi api = new DefaultApi(apiClient);

        // 이제 인증된 API 호출을 할 수 있습니다
        try {
            // Example: Add an SSO user
            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());
            // Common errors:
            // - 401: API key is missing or invalid
            // - 400: Request validation failed
        }
    }
}

공개 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();
}

자주 발생하는 문제

1. 401 "missing-api-key" 오류: apiClient.setApiKey("YOUR_KEY")를 DefaultApi 인스턴스를 생성하기 전에 호출했는지 확인하세요.
2. 잘못된 API 클래스: 서버 측 인증 요청에는 DefaultApi를, 클라이언트 측/공개 요청에는 PublicApi를 사용하세요.
3. API 키가 null인 경우: SDK는 API 키가 null이면 인증을 조용히 건너뛰어 401 오류가 발생합니다.

브로드캐스트 ID

일부 API 호출에서 broadcastId를 전달해야 한다는 것을 보게 됩니다. 이벤트를 수신하면 이 ID가 반환되므로, 클라이언트에서 낙관적으로 변경을 적용하려는 경우 이벤트를 무시해야 하는지 알 수 있습니다 (더 나은 사용자 경험을 제공하므로 아마 그렇게 하게 될 것입니다). 여기에 UUID를 전달하세요. 이 ID는 브라우저 세션 내에서 두 번 발생하지 않을 만큼 충분히 고유해야 합니다.