Skip to main content

자주 묻는 질문

Android


설치 및 초기 설정

넷퍼넬 에이전트를 프로젝트에서 인식하지 않아요.

프로젝트에서 (에이전트) .aar 파일이 제대로 인식되지 않았을 경우 발생합니다.

  1. Project 탭에서 libs/ 내 .aar 에이전트 파일에서 우클릭
  2. Copy Path/Reference… → Path From Content Root를 선택
  3. 복사한 경로를 build.gradle에 아래와 같이 등록 및 Sync Now 동기화
Copy Path/Reference… 선택Copy Path/Reference… 선택
Path From Content Root 선택Path From Content Root 선택
gradle sync nowgradle sync now
넷퍼넬 적용 후, 앱을 실행하면 크래시 나요.

외부 라이브러리가 누락되거나, AndroidManifest.xml의 권한이 누락된 경우 발생합니다.

  1. 아래와 같이 Ktor, Kotlinx Serialization 의존성을 주입합니다.
  2. AndroidManifest.xml에 인터넷 접속 권한을 추가합니다.
Kotlin DSL (build.gradle.kts)
dependencies {
    val ktorVersion = "{{ktorVersion}}"
    val serializationVersion = "{{serializationVersion}}"

    // Ktor dependencies
    implementation("io.ktor:ktor-client-core:$ktorVersion")
    implementation("io.ktor:ktor-client-okhttp:$ktorVersion")
    implementation("io.ktor:ktor-client-content-negotiation:$ktorVersion")
    implementation("io.ktor:ktor-serialization-gson:$ktorVersion")

    // Serialization dependency
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:$serializationVersion")
    ...
}
외부 라이브러리에 사용해야 하는 버전을 알고 싶어요.

NetFUNNEL Android 에이전트에서 사용하는 외부 라이브러리의 종류와 호환되는 버전은 다음과 같습니다.

  • Ktor: 네트워크 통신 라이브러리 (2.1.0 이상 3.0.0 미만)
  • Kotlinx Serialization: 직렬화 라이브러리 (버전 무관)
참고

NetFUNNEL Android 에이전트에서 내부적으로 사용하고 있는 라이브러리 버전은 다음과 같습니다. - Ktor: 2.3.11 - Kotlinx Serialization: 1.6.3

Application에서 초기화하는 이유가 궁금해요.

NetFUNNEL Android 에이전트는 앱 실행과 동시에 초기화되어야 안정적으로 동작합니다. Application의 onCreate()에서 한 번만 초기화하는 것이 가장 효율적입니다.

  • 앱 전체에서 한 번만 초기화되며, 재초기화 없이 모든 컴포넌트(Activity 등)에서 사용할 수 있습니다.
  • 특정 Activity에서 크래시가 발생하더라도, 앱 프로세스가 종료되지 않는 한 NetFUNNEL은 계속 유지됩니다.
  • 전역 초기화를 통해 설정 누락, 중복 호출 등의 오류를 방지할 수 있습니다.

설정 옵션 이해

넷퍼넬의 로그를 출력하고 싶어요.
warning

상용 서비스에서는 printLog=false로 설정해 로그 노출을 방지하는 것을 권장합니다.

초기화 함수의 printLog 값을 true로 설정 시, Logcat을 통해 넷퍼넬 로그가 출력됩니다. NetFUNNEL 태그로 출력되며, Logcat에서 package:mine NetFUNNEL으로 필터링하여 확인 가능합니다.

파라미터타입설명기본값
printLogBoolean?넷퍼넬 디버그를 위한 로그 출력 유무false
Kotlin
import com.nf4.Netfunnel

class SampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        Netfunnel.initialize(
            serverUrl = "{{value}}",
            errorUrl = "{{value}}",
            printLog = true
        )
    }
}
모든 에러를 바이패스하고 싶어요.
warning

서비스 안정성을 우선시할 경우 errorBypass=true로 설정할 수 있습니다.

초기화 함수의 errorBypass 값을 true로 설정해, 모든 에러를 바이패스할 수 있습니다. 서버 오류, 파라미터 오류, 응답 지연 등으로 넷퍼넬 제어가 실패해도 서비스 진입을 차단하지 않습니다. errorBypass=false인 경우에는 오류 발생 시 진입이 차단되며, onError 콜백이 호출됩니다.

파라미터타입설명기본값
errorBypassBoolean?넷퍼넬 서버 에러나 네트워크 에러 발생 시 바이패스 유무false
Kotlin
import com.nf4.Netfunnel

class SampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        Netfunnel.initialize(
            serverUrl = "{{value}}",
            errorUrl = "{{value}}",
            errorBypass = true
        )
    }
}
대기실에서 타임아웃이 발생하더라도 재시도하고 싶어요.
info

설정한 networkTimeout과 retryCount 초과 시 onNetworkError 발생합니다.

초기화 함수의 networkTimeout, retryCount 설정을 통해 네트워크 요청에 대한 횟수를 통제할 수 있습니다. retryCount 설정값만큼 재시도하며, 각 시도마다 networkTimeout 시간 내 응답을 기다립니다.

파라미터타입설명기본값
networkTimeoutLong?넷퍼넬 서버의 응답을 기다리는 최대 시간 (ms)3,000
retryCountInt?넷퍼넬 요청 실패 시 재시도 횟수0
Kotlin
import com.nf4.Netfunnel

class SampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        Netfunnel.initialize(
            serverUrl = "{{value}}",
            errorUrl = "{{value}}",
            networkTimeout = 3000,
            retryCount = 0
        )
    }
}
초기화 함수의 userId가 무엇인지 궁금해요.
info

다음과 같이 콘솔의 반복 요청 차단에서 화이트리스트와 블랙리스트 ID를 설정할 수 있습니다. BotManager Basic에 대한 자세한 설명은 넷퍼넬 콘솔 가이드에서 확인 가능합니다.

초기화 함수의 userId는 넷퍼넬 서버에서 사용자를 구분하기 위한 식별자입니다.

파라미터타입설명기본값
userIdString?화이트리스트, 블랙리스트 등록 여부를 확인하기 위해 end-user를 식별하는 고유 식별자N/A
Kotlin
import com.nf4.Netfunnel

class SampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        Netfunnel.initialize(
            serverUrl = "{{value}}",
            errorUrl = "{{value}}",
            userId = "{{value}}"
        )
    }
}
커스텀 대기실을 사용하고 싶어요.
warning

자체 커스텀 대기실 사용 시, 기본 대기 외 기능 사용에 제한이 있습니다. 넷퍼넬 콘솔에서 만든 HTML 파일을 기반으로 에이전트 내부에서 자동으로 WebView를 띄우고 화면을 업데이트하는 형태를 사용하는 것을 권장합니다. (useNetfunnelTemplate=true 설정 권장)

info

본 항목은 Kotlin, XML을 기준으로 작성합니다.

초기화 함수의 useNetfunnelTemplate 값을 false로 설정하고, onContinue 콜백의 파라미터를 통해 커스텀 대기창을 사용할 수 있습니다.

  1. 초기화 함수의 useNetfunnelTemaplte=false 설정
  2. 사용자가 직접 커스텀 대기실 생성
  3. onContinue 콜백을 통해 화면 정보를 직접 업데이트

대기 관련 설정

대기실이 보이지 않아요.
warning

진입 허용 수가 0이면, 어떤 사용자도 진입할 수 없습니다.

넷퍼넬 콘솔의 [세그먼트 설정 → 기본 설정 → 진입 허용 수] 항목을 0으로 설정하여 대기실을 노출시킵니다.

대기실 진입(200) 후, 대기 없이 진입해요.
info

진입 패스에 대한 자세한 설명은 넷퍼넬 콘솔가이드에서 확인 가능합니다.

대기실 진입(200) 이후 대기 없이 바로 서비스에 진입하는 경우, 진입 패스 기능이 활성화되어 있을 수 있습니다. 진입 패스는 사용자가 한 번 대기실에 진입한 이후, 설정된 유예 시간 동안 동일한 세그먼트로 재접속할 경우 대기열을 거치지 않고 바로 서비스로 이동할 수 있도록 허용하는 기능입니다. 이 기능을 사용하지 않으려면, 넷퍼넬 콘솔의 [세그먼트 설정 → 고급 설정 → 진입 패스] 항목을 OFF로 설정합니다.


콜백 사용

콜백 함수에서 UI 업데이트하고 싶어요.

넷퍼넬 콜백 함수는 비동기 스레드에서 동작합니다. 따라서 콜백 내부에서 Toast나 AlertDialog 등 UI 관련 작업을 직접 실행하면 NullPointerException, RuntimeException 예외가 발생할 수 있습니다. UI 업데이트가 필요한 경우, 반드시 메인 스레드를 사용하여 실행해야 합니다. 이를 위해 Activity.runOnUiThread 메서드를 사용합니다.

Kotlin
override fun onSuccess(statusCode: Int, message: String) {
    activity.runOnUiThread {
        Toast.makeText(activity, "성공적으로 진입하였습니다.", Toast.LENGTH_SHORT).show()
    }
    ...
}

예외 상황

언제 바이패스가 되는지 알고 싶어요.

아래 5가지 경우에서는 넷퍼넬 대기실이 실행되지 않거나 열려있던 대기실이 닫히며 바이패스됩니다.

  1. 초기화 함수를 생략한 경우
  2. 초기화 함수의 errorBypass를 true로 설정한 경우
  3. 시작 함수에 잘못된 키를 입력한 경우
  4. 프로젝트가 비활성화된 경우
  5. 세그먼트가 비활성화된 경우
백그라운드 전환 시, 대기실이 통과돼요.
info

아래 내용은 넷퍼넬의 의도된 동작입니다.

Android 절전 모드와 넷퍼넬의 정책

  • Android 시스템은 절전 모드(Doze Mode) 진입 시 네트워크 사용을 제한됩니다.
  • NetFUNNEL Android 에이전트는 서버와의 연결 상태를 지속적으로 확인합니다.
  • 네트워크 연결이 끊긴 것으로 판단되면, 대기를 자동으로 종료하고 대기실(WebView)을 닫습니다.

launchMode 및 앱 진입 방식에 따른 영향

  • singleTask 사용 시: 위젯, 푸시, 런처를 통해 앱 진입 시, 기존 액티비티를 모두 종료(onDestroy) 합니다.
  • singleInstance 사용 시: 새로운 Task로 액티비티가 실행되어 기존 대기실은 다른 Task로 남아 있습니다. 여전히 대기 중이지만, 새로운 Task에 가려 WebView가 보이지 않습니다. (뒤로가기를 통해 확인 가능)
  • 따라서 앱 재진입 시에도 대기 상태를 유지하려면 launchMode 설정을 신중히 고려해야 합니다. singleTop + Intent.FLAG_ACTIVITY_REORDER_TO_FRONT 등의 조합을 사용해 기존 액티비티를 재활용하는 방식이 대기실 유지에 유리합니다.
난독화로 인해 오류가 발생해요.

앱 배포 시 코드 축소, 난독화, 최적화를 하는 경우, NetFUNNEL Android 에이전트를 제외하기 위해 proguard-rules.pro 프로가드 규칙 파일에 아래 코드를 추가합니다.

# 넷퍼넬 에이전트의 주요 패키지 및 클래스 보호
-keep class com.nf4.** { *; }

# 넷퍼넬 에이전트 내부에서 사용하는 리플렉션 관련 클래스 및 멤버 유지
-keepclassmembers class com.nf4.** { *; }
HTTP 통신 시 오류가 발생해요.

NetFUNNEL Android 에이전트는 기본적으로 HTTPS 통신을 권장하며, HTTP 통신을 사용할 경우 Android 보안 정책에 따라 오류가 발생합니다.

  1. res/xml/network_security_config.xml 파일 생성
  2. AndroidManifest.xml 설정 확인
network_security_config.xml
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">{{value}}</domain>
    </domain-config>
</network-security-config>

참고 자료

콜백에서 주는 상태 코드가 궁금해요. ( TODO: 최신화 필요 )

NetFUNNEL의 콜백 함수에서는 아래와 같은 상태 코드(statusCode)가 전달됩니다. 각 상태는 대기실 처리 결과를 나타냅니다.

이 섹션은 상세한 테이블 데이터가 필요하여 별도 구현이 필요합니다.

에이전트 버전을 변경하려고 해요. (에이전트 마이그레이션)
warning

콜백 함수 구조, 초기화 파라미터, 함수 명칭 등을 반드시 최선 버전에 맞춰 수정해야 합니다. 각 버전에서 변경된 사항은 위 표를 참고해 반드시 점검하세요.

NetFUNNEL Android 에이전트는 v4.2.0 이후부터 구조가 크게 개편되었습니다. 기존과 동일한 기능을 사용하더라도, 초기화 방식·콜백 함수·외부 라이브러리·파라미터 등 주요 항목이 변경되었기 때문에, 마이그레이션 시 아래 내용을 반드시 확인하세요.

이 섹션은 상세한 마이그레이션 테이블이 필요하여 별도 구현이 필요합니다.


iOS


설치 및 초기 설정

델리게이트에서 앱 크래시가 발생해요

델리게이트에서 크래시가 발생하는 경우, UI 관련 로직이 메인 스레드에서 실행되었는지 확인해 보세요.

xcframework가 사용하고 싶어요

콘솔에서 다운로드한 NetFUNNEL iOS 에이전트 파일의 압축을 풀면, release 폴더와 debug 폴더 각각에 netfunnel_ios.xcframework가 포함되어 있습니다.

Application에서 초기화하는 이유가 궁금해요.

NetFUNNEL iOS 에이전트는 앱 실행과 동시에 초기화되어야 안정적으로 동작합니다. AppDelegate의 application(_:didFinishLaunchingWithOptions:)에서 한 번만 초기화하는 것이 가장 효율적입니다.

  • 앱 전체에서 한 번만 초기화되며, 재초기화 없이 모든 화면(ViewController 등)에서 사용할 수 있습니다.
  • 특정 ViewController에서 크래시가 발생하더라도, 앱 프로세스가 종료되지 않는 한 NetFUNNEL은 계속 유지됩니다.
  • 전역 초기화를 통해 설정 누락이나 중복 호출과 같은 오류를 방지할 수 있습니다.

설정 옵션 이해

넷퍼넬의 로그를 출력하고 싶어요.
warning

초기화 함수의 printLog 값을 true로 설정하면, Xcode 콘솔에서 NetFUNNEL 관련 로그가 출력됩니다. 해당 로그는 NetFUNNEL 태그로 출력되며, Xcode의 콘솔 필터에서 NetFUNNEL 키워드로 검색하여 확인할 수 있습니다.

파라미터타입설명기본값
printLogBoolean?넷퍼넬 디버그를 위한 로그 출력 유무false
Swift
import Netfunnel_iOS

Netfunnel.shared.initialize(
    serverUrl: "{{value}}",
    errorUrl: "{{value}}",
    delegate: self,
    printLog: true,
)
모든 에러를 바이패스하고 싶어요.
warning

서비스 안정성을 우선시할 경우 errorBypass=true로 설정할 수 있습니다.

초기화 함수의 errorBypass 값을 true로 설정해, 모든 에러를 바이패스할 수 있습니다. 서버 오류, 파라미터 오류, 응답 지연 등으로 넷퍼넬 제어가 실패해도 서비스 진입을 차단하지 않습니다. errorBypass=false인 경우에는 오류 발생 시 진입이 차단되며, nfError 콜백이 호출됩니다.

파라미터타입설명기본값
errorBypassNSNumber? (Bool)넷퍼넬 서버 에러나 네트워크 에러 발생 시 바이패스 유무false
Swift
import Netfunnel_iOS

Netfunnel.shared.initialize(
    serverUrl: "{{value}}",
    errorUrl: "{{value}}",
    delegate: self,
    errorBypass: true
)
대기실에서 타임아웃이 발생하더라도 재시도하고 싶어요.
info

설정한 networkTimeout과 retryCount 초과 시 nfNetworkError 발생합니다.

초기화 함수의 networkTimeout, retryCount 설정을 통해 네트워크 요청에 대한 횟수를 통제할 수 있습니다. retryCount 설정값만큼 재시도하며, 각 시도마다 networkTimeout 시간 내 응답을 기다립니다.

파라미터타입설명기본값
networkTimeoutNSNumber? (Long)넷퍼넬 서버의 응답을 기다리는 최대 시간 (ms)3,000
retryCountNSNumber? (Int)넷퍼넬 요청 실패 시 재시도 횟수0
Swift
import Netfunnel_iOS

Netfunnel.shared.initialize(
    serverUrl: "{{value}}",
    errorUrl: "{{value}}",
    delegate: self,
    networkTimeout: 3000,
    retryCount: 0
)
초기화 함수의 userId가 무엇인지 궁금해요.
info

다음과 같이 콘솔의 반복 요청 차단에서 화이트리스트와 블랙리스트 ID를 설정할 수 있습니다. BotManager Basic에 대한 자세한 설명은 넷퍼넬 콘솔 가이드에서 확인 가능합니다.

초기화 함수의 userId는 넷퍼넬 서버에서 사용자를 구분하기 위한 식별자입니다.

파라미터타입설명기본값
userIdString?화이트리스트, 블랙리스트 등록 여부를 확인하기 위해 end-user를 식별하는 고유 식별자N/A
Swift
import Netfunnel_iOS

Netfunnel.shared.initialize(
    serverUrl: "{{value}}",
    errorUrl: "{{value}}",
    delegate: self,
    userId: "{{value}}"
)
커스텀 대기실을 사용하고 싶어요.
warning

자체 커스텀 대기실 사용 시, 기본 대기 외 기능 사용에 제한이 있습니다. 넷퍼넬 콘솔에서 만든 HTML 파일을 기반으로 에이전트 내부에서 자동으로 WebView를 띄우고 화면을 업데이트하는 형태를 사용하는 것을 권장합니다. (useNetfunnelTemplate=true 설정 권장)

info

본 항목은 SwiftUI를 기준으로 작성합니다.

초기화 함수의 useNetfunnelTemplate값을 false로 설정하고, nfContinue콜백의 파라미터를 통해 커스텀 대기창을 사용할 수 있습니다.

  1. 초기화 함수의 useNetfunnelTemaplte=false 설정
  2. 사용자가 직접 커스텀 대기실 생성
  3. nfContinue 콜백을 통해 화면 정보를 직접 업데이트

대기 관련 설정

대기실이 보이지 않아요.
warning

진입 허용 수가 0이면, 어떤 사용자도 진입할 수 없습니다.

넷퍼넬 콘솔의 [세그먼트 설정 → 기본 설정 → 진입 허용 수] 항목을 0으로 설정하여 대기실을 노출시킵니다.

대기실 진입(200) 후, 대기 없이 진입해요.
info

진입 패스에 대한 자세한 설명은 넷퍼넬 넷퍼넬 콘솔 가이드에서 확인 가능합니다.

대기실 진입(200) 이후 대기 없이 바로 서비스에 진입하는 경우, 진입 패스 기능이 활성화되어 있을 수 있습니다. 진입 패스는 사용자가 한 번 대기실에 진입한 이후, 설정된 유예 시간 동안 동일한 세그먼트로 재접속할 경우 대기열을 거치지 않고 바로 서비스로 이동할 수 있도록 허용하는 기능입니다. 이 기능을 사용하지 않으려면, 넷퍼넬 콘솔의 [**세그먼트 설정 → 고급 설정 → 진입 패스**] 항목을 OFF로 설정합니다.


예외 상황

에이전트가 빌드되지 않아요 (Invalid privacy manifest 오류)

NetFUNNEL iOS 에이전트는 버전 4.2.5부터 Apple의 정책 변경에 따라 privacyInfo 파일이 수정되었습니다. 해당 오류가 발생하는 경우, 에이전트 버전이 최신인지 확인해 주세요.

에이전트가 빌드되지 않아요 (No code signature fouund 오류)

NetFUNNEL iOS 에이전트는 기본적으로 코드 서명이 포함된 상태로 제공됩니다. 이 에러가 발생하는 경우에는 다음 사항을 확인해 주세요.

  • 전달받은 .xcframework 파일에 코드 서명이 포함되어 있는지
  • 빌드 과정에서 코드 서명이 누락되지 않았는지
  • 프로젝트의 [Build Settings > Code Signing] 관련 설정이 올바른지

필요 시, 서명 관련 설정이나 빌드 옵션을 다시 점검해주시기 바랍니다.


JavaScript


설치 및 초기 설정

에이전트가 초기화되지 않아요.

NetFUNNEL JavaScript 에이전트는 HTML의 head 영역에서 초기화하는 방식을 권장드립니다. JavaScript 내에서 초기화를 진행할 경우 환경 변수나 실행 시점 등 여러 요소에 따라 예기치 못한 동작이 발생할 수 있습니다. 보다 안정적인 연동을 위해 HTML에서 초기화를 진행해주시기 바랍니다.

공통 자바스크립트 파일에서 에이전트를 초기화하고 싶어요.

에이전트를 적용해야 하는 HTML에 공통적으로 삽입되는 자바스크립트가 있다면 해당 자바스크립트에서 스크립트가 실행되도록 할 수 있습니다.

index.html
<html>
  <head>
    ...
    <script src="./netfunnel.js" defer></script>
    ...
  </head>
</html>

예외 상황

넷퍼넬 함수에서 에러가 발생해요.

에이전트 함수는 Agent 스크립트가 정상적으로 다운로드된 이후에 실행되어야 합니다. 관련 함수들이 정의되기 전에 호출될 경우, nfStop 등의 함수가 정의되지 않았다는 오류가 발생할 수 있기 때문입니다.

JavaScript
// 페이지 로드 시 호출
window.addEventListener("load", function () {
  nfStop(function () {
    console.log("메인 페이지 로드 완료 및 대기실 처리 종료");
  });
});

타입스크립트

넷퍼넬 함수에서 타입 에러가 발생해요.

넷퍼넬에서 제공하는 시작 함수, 종료 함수는 window 객체에 할당됩니다. 따라서 타입스크립트의 경우 window 객체에 넷퍼넬 관련된 타입을 추가해야 합니다. 루트 또는 src에 global.d.ts 파일을 생성하거나 글로벌 타입을 선언하는 파일에 아래 코드를 추가해주세요.

global.d.ts
interface Window {
  Netfunnel: {
    devtoolsAddListener: (callback: (isOpen: boolean) => void) => void;
    devtoolsLaunch: () => void;
  };
  nfStart: (options: { projectKey: string; segmentKey: string }, callback?: (response: any) => void) => void;
  nfStartSection: (options: { projectKey: string; segmentKey: string }, callback?: (response: any) => void) => void;
  nfStop: (options: { projectKey: string; segmentKey: string }, callback?: (response: any) => void) => void;
  nfStopSection: (options: { projectKey: string; segmentKey: string }, callback?: (response: any) => void) => void;
  getNetfunnelVersion: () => string;
}