Java 통합 가이드

NetFUNNEL Java 에이전트는 Java 기반 Spring Boot 서버에서 NetFUNNEL 서버와 통신하는 전용 클라이언트입니다.

---

1. 최소 요구 사항

• Java 1.7 이상
• Spring Boot 3.x 이상

1.1 외부 의존성

• gson: JSON 직렬화/역직렬화를 사용하기 위한 라이브러리
• jackson-module-kotlin: kotlin 사용을 위해 필요한 라이브러리 (Java 사용시)

---

2. 에이전트 동작 흐름

대기열 제어 지점은 NetFUNNEL 콘솔의 세그먼트 트리거 규칙을 통해 설정할 수 있습니다. 사용자가 접속한 페이지의 URL과 트리거 규칙을 비교하여 일치하는 경우 대기열이 적용됩니다.

대기 전

페이지 로드 → 에이전트 초기화 → 트리거 규칙 매치

대기 중

넷퍼넬 서버 요청 → 넷퍼넬 키 발급 → 대기실 페이지로 이동

대기 후

서비스 페이지 진입 → 넷퍼넬 키 반납

---

3. 에이전트 설치

3.1 라이브러리 추가

에이전트 파일을 다운로드 합니다.

Download

다운로드한 에이전트 파일을 프로젝트의 libs 디렉토리에 복사한 후, 프로젝트의 빌드 설정에 다음과 같이 의존성을 추가합니다.

Kotlin DSL (build.gradle.kts)

build.gradle.kts

implementation(files("libs/netfunnel-agent.jar"))
implementation("com.google.code.gson:gson:2.9.1")
// When using Java
implementation("com.fasterxml.jackson.module:jackson-module-kotlin")

Groovy DSL (build.gradle)

build.gradle

implementation files('libs/netfunnel-java-agent.jar')
implementation 'com.google.code.gson:gson:2.9.1'
// When using Java
implementation 'com.fasterxml.jackson.module:jackson-module-kotlin'

3.2 Interceptor 적용

경고

프로젝트 구조에 맞게 Interceptor와 Filter 중 하나만 선택하여 적용합니다. 두 방식 모두 동일한 NetFUNNEL 대기열 제어 기능을 제공하므로 중복으로 구현할 필요는 없습니다.

3.2.1 Interceptor 생성

서버의 요청을 먼저 수신하는 Interceptor에 아래와 같은 코드를 작성합니다.

Java

DemoInterceptor.java

@Component
public class DemoInterceptor implements HandlerInterceptor {

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        NetFunnelInitialize config = NetFunnelInitialize.Companion.builder()
            .clientId("{CLIENT_ID}")
            .secretKey("*****")
            .build();

        Netfunnel netfunnel = new Netfunnel(config, new NetFunnelServletService(request, response), null, null);
        return netfunnel.run();
    }
}

Kotlin

DemoInterceptor.kt

@Component
class DemoInterceptor : HandlerInterceptor {

    override fun preHandle(request: HttpServletRequest, response: HttpServletResponse, handler: Any): Boolean {
        val initializer = getNetFunnelInitializer()
        val netfunnel = Netfunnel(initializer, NetFunnelServletService(request, response))
        return netfunnel.run()
    }

    private fun getNetFunnelInitializer(): NetFunnelInitializer {
        return NetFunnelInitializer.builder()
            .clientId("{CLIENT_ID}")
            .secretKey("*****")
            .build()
    }
}

3.2.2 Interceptor 등록

생성한 interceptor를 WebMvcConfigurer의 addInterceptors 메서드를 override해서 등록합니다.

Java

WebConfig.java

@Configuration
public class WebConfig implements WebMvcConfigurer {

    private final DemoInterceptor demoInterceptor;

    @Autowired
    public WebConfig(DemoInterceptor demoInterceptor) {
        this.demoInterceptor = demoInterceptor;
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(demoInterceptor)
                .addPathPatterns("/**");
    }
}

Kotlin

WebConfig.kt

@Configuration
class WebConfig(
    private val demoInterceptor: DemoInterceptor
) : WebMvcConfigurer {

    override fun addInterceptors(registry: InterceptorRegistry) {
        registry.addInterceptor(demoInterceptor)
    }
}

3.3 Filter 적용

3.3.1 Filter 생성

서버의 요청을 먼저 수신하는 Filter에 아래와 같은 코드를 작성합니다.

Java

DemoFilter.java

public class DemoFilter implements Filter {

    @Override
    public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain chain)
            throws IOException, ServletException {

        HttpServletRequest request = (HttpServletRequest) servletRequest;
        HttpServletResponse response = (HttpServletResponse) servletResponse;
        NetFunnelInitialize config = NetFunnelInitialize.Companion.builder()
            .clientId("{CLIENT_ID}")
            .secretKey("*****")
            .build();

        Netfunnel netfunnel = new Netfunnel(config, new NetFunnelServletService(request, response), null, null);

        if (!netfunnel.run()) {
            return;
        }
        chain.doFilter(servletRequest, servletResponse);
    }
}

Kotlin

DemoFilter.kt

@Component
class DemoFilter : Filter {

    override fun doFilter(servletRequest: ServletRequest, servletResponse: ServletResponse, chain: FilterChain) {
        val request = servletRequest as HttpServletRequest
        val response = servletResponse as HttpServletResponse

        val initializer = getNetFunnelInitializer()
        val netfunnel = Netfunnel(initializer, NetFunnelServletService(request, response))

        if (netfunnel.run()) {
            chain.doFilter(servletRequest, servletResponse)
        }
    }

    private fun getNetFunnelInitializer(): NetFunnelInitializer {
        return NetFunnelInitializer.builder()
            .clientId("{CLIENT_ID}")
            .secretKey("*****")
            .build()
    }
}

3.3.2 Filter 등록

생성한 Filter를 빈에 등록합니다.

Java

FilterConfig.java

@Configuration
public class FilterConfig {

    @Bean
    public FilterRegistrationBean<Filter> filterRegistrationBean() {
        FilterRegistrationBean<Filter> registration = new FilterRegistrationBean<>();
        registration.setFilter(new DemoFilter());
        registration.addUrlPatterns("/*");
        registration.setOrder(1);
        return registration;
    }
}

Kotlin

FilterConfig.kt

@Configuration
class FilterConfig(
    private val demoFilter: DemoFilter
) {

    @Bean
    fun filterRegistrationBean(): FilterRegistrationBean<Filter> {
        return FilterRegistrationBean(demoFilter)
    }
}

---

4. Initialize 설정

필드	기본값	필수	설명	에이전트 버전
clientId string	N/A	O	콘솔에서 발급받은 클라이언트 아이디를 입력합니다.	4.0.1 이상
secretKey string	N/A	O	콘솔에서 발급받은 암호화 키를 입력합니다.	4.0.1 이상
serverUrl string	N/A	X	NetFUNNEL 서버의 URL입니다. CNAME을 사용하지 않고, clientId 기반의 URL 조합이 아닌 별도의 URL로 서버에 접근할 때 사용합니다. (기존 방식과의 호환성을 위해 지원됩니다.)	4.0.1 이상
settingUrl string	N/A	X	NetFUNNEL 환경설정 파일의 URL입니다. CNAME을 사용하지 않고, clientId 기반의 URL 조합이 아닌 별도의 URL로 설정 파일을 불러올 때 사용합니다. (기존 방식과의 호환성을 위해 지원됩니다.)	4.0.1 이상
vwrPageUrl string	N/A	X	NetFUNNEL VWR Page의 URL입니다. CNAME을 사용하지 않고, clientId 기반의 URL 조합이 아닌 별도의 URL로 대기실 페이지에 진입해야 할 때 지정합니다.	4.0.1 이상
returnKey boolean	true	X	사용자가 대기열을 통과해 페이지에 진입하면 즉시 다음 사용자가 입장할 수 있습니다. 옵션을 비활성화하면, 사용자가 페이지에 진입한 뒤에도 일정 시간동안 다음 사용자가 대기하게 됩니다. (타임아웃 설정은 콘솔의 세그먼트 설정 > 고급설정에서 가능합니다.)	4.0.1 이상
logLevel Level	Level.OFF	X	ch.qos.logback.classic.Level을 기반으로 로그 레벨을 설정하므로, 해당 의존성 추가가 필요합니다. 사용 가능 레벨: ERROR, WARN, INFO, DEBUG, TRACE, OFF	4.0.1 이상
goodBots array	N/A	X	선의의 봇(검색엔진 등)이 NetFUNNEL 진입 요청에서 제외되도록 설정합니다. 문자열의 배열로 값을 받습니다. 예시: ["Googlebot", "Bingbot"]	4.0.1 이상
userId string	N/A	X	이 값을 입력하면 화이트리스트 및 영구 차단 사용자 구분에 ID가 사용됩니다. 콘솔의 반복 요청 차단 > 사용자 설정 > 접속자 관리에서 설정한 ID가 적용됩니다.	4.0.1 이상
vwrPageDomain string	N/A	X	CNAME 도메인만으로 VWR Page URL을 구성할 때 사용합니다. 예시: https://vwr.example.com	4.0.1 이상
cookieDomain string	N/A	X	발급되는 NetFUNNEL 쿠키의 도메인(Domain) 값을 직접 지정할 수 있습니다.	4.0.1 이상

---

5. 트리거 규칙 설정

info

대기열 제어 지점은 NetFUNNEL 콘솔의 세그먼트 트리거 규칙을 통해 설정할 수 있습니다. 사용자가 접속한 페이지의 URL과 트리거 규칙을 비교하여 일치하는 경우 대기열이 적용됩니다.

트리거 규칙 설정 방법은 트리거 규칙 설정 가이드를 참고하세요.