설치 및 초기화

이 가이드는 NetFUNNEL Android 에이전트를 애플리케이션에 통합하기 위한 필수 설정 단계를 다룹니다.

---

사전 요구사항

시스템 요구사항

구성 요소	버전	참고
Android API Level	22+ (Lollipop 5.1)	활성 Android 기기의 99%를 커버합니다
Java	1.8+	Gradle 빌드 시스템에 필요합니다
Kotlin	1.9.0+	Kotlin 기반 Android 개발의 경우

외부 의존성

라이브러리	버전	목적
Ktor	2.1.0+ (< 3.0.0)	API 통신을 위한 HTTP 네트워킹
Kotlinx Serialization	모든 버전	JSON 데이터 변환

버전 호환성

• Ktor 3.0.0+: 지원되지 않음
• Android API Level 21 이하: 지원되지 않음
• Java 7 이하: 지원되지 않음

의존성 관리

의존성은 설치 중 자동으로 구성됩니다. 수동 설정이 필요하지 않습니다.

---

1단계: SDK 다운로드

1.1 NetFUNNEL 콘솔에서 다운로드

1. NetFUNNEL 콘솔에 로그인합니다
2. 에이전트 → 모바일 에이전트 → Android로 이동합니다
3. "Traffic Control Installation File" 버튼을 클릭합니다
4. ZIP 파일을 다운로드합니다: netfunnel-android-agent-{{version}}.zip

1.2 파일 압축 해제

1. ZIP 파일을 압축 해제하여 다음을 얻습니다:
   • netfunnel-android-agent-debug-{{version}}.aar (개발용)
   • netfunnel-android-agent-release-{{version}}.aar (프로덕션용)

빌드 유형

• 개발: debug AAR 사용
• 프로덕션: release AAR 사용

---

2단계: 의존성 추가

2.1 AAR 파일 배치

1. app/libs/ 디렉토리를 생성합니다 (존재하지 않는 경우)
2. 두 AAR 파일을 app/libs/에 복사합니다:
   • netfunnel-android-agent-debug-{{version}}.aar
   • netfunnel-android-agent-release-{{version}}.aar

프로젝트 구조:

your-project/
├── app/
│   ├── libs/
│   │   ├── netfunnel-android-agent-debug-{{version}}.aar
│   │   └── netfunnel-android-agent-release-{{version}}.aar
│   └── build.gradle
└── build.gradle

2.2 build.gradle 구성

app/build.gradle을 편집합니다 (프로젝트 레벨이 아닌):

1. dependencies { } 블록에 의존성 추가
2. {{version}}을 실제 버전 번호로 교체
3. 빌드 유형에 따라 debug 또는 release AAR 선택

Kotlin DSL (build.gradle.kts)

dependencies {
    // NetFUNNEL Android 에이전트
    implementation(files("libs/netfunnel-android-agent-debug-{{version}}.aar"))
    
    // 외부 의존성
    val ktorVersion = "2.3.12"
    val serializationVersion = "1.6.3"
    
    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")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:$serializationVersion")
}

Groovy DSL (build.gradle)

ext {
    ktorVersion = "2.3.12"
    serializationVersion = "1.6.3"
}

dependencies {
    // NetFUNNEL Android 에이전트
    implementation files("libs/netfunnel-android-agent-debug-{{version}}.aar")
    
    // 외부 의존성
    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"
    implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:$serializationVersion"
}

2.3 Android 설정 구성

app/build.gradle의 android { } 블록을 업데이트합니다 (프로젝트 레벨이 아닌):

• minSdk: 22+ (사전 요구사항과 일치)
• compileOptions: Java 1.8+ 호환성
• kotlinOptions: jvmTarget 1.8+
• buildFeatures: viewBinding 활성화

Kotlin DSL (build.gradle.kts)

android {
    compileSdk = 34
    defaultConfig {
        minSdk = 22
        targetSdk = 34
    }
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
    kotlinOptions {
        jvmTarget = "1.8"
    }
    buildFeatures {
        viewBinding = true
    }
}

Groovy DSL (build.gradle)

android {
    compileSdk 34
    defaultConfig {
        minSdk 22
        targetSdk 34
    }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    kotlinOptions {
        jvmTarget = '1.8'
    }
    buildFeatures {
        viewBinding true
    }
}

2.4 인터넷 권한 추가

app/src/main/AndroidManifest.xml에 인터넷 권한 추가:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.INTERNET" />
    
    <application>
        <!-- Activity들 -->
    </application>
</manifest>

2.5 ProGuard/R8 구성 (릴리스 빌드)

릴리스 버전을 빌드할 때 코드 축소, 난독화 및 최적화로 인해 NetFUNNEL Android 에이전트에서 오류가 발생할 수 있습니다. 이를 방지하려면 NetFUNNEL을 난독화에서 제외하세요.

proguard-rules.pro에 ProGuard 규칙 추가:

# NetFUNNEL Android Agent - Protect main packages and classes
-keep class com.nf4.** { *; }

# NetFUNNEL Android Agent - Keep reflection-related classes and members
-keepclassmembers class com.nf4.** { *; }

위치: app/proguard-rules.pro

릴리스 빌드 요구사항

이 구성은 릴리스 빌드에 필수입니다. 이 규칙 없이는 난독화로 인해 NetFUNNEL 기능이 중단됩니다.

2.6 설정 확인

1. 프로젝트 동기화: File → Sync Project with Gradle Files
2. 프로젝트 빌드: Build → Assemble Project

---

3단계: 에이전트 초기화

3.1 NetFUNNEL 콘솔에서 초기화 코드 가져오기

1. NetFUNNEL 콘솔에 로그인합니다
2. 에이전트 → 모바일 에이전트 → Android로 이동합니다
3. 실제 클라이언트 ID가 포함된 초기화 코드를 복사합니다

3.2 Application 클래스에서 초기화

중요: 먼저 초기화해야 함

Application.onCreate()에서 super.onCreate() 이전에 초기화합니다. 이 단계를 누락하면 = 우회 모드(보호 없음)입니다.

Application 클래스에 초기화 코드 추가:

• 위치: app/src/main/java/your-package-name/YourAppApplication.kt (Kotlin) 또는 YourAppApplication.java (Java)

Application 클래스가 없는 경우 생성:

1. Application 클래스 생성:

   • Android Studio에서 app/src/main/java/your-package-name/를 우클릭합니다
   • New → Kotlin Class/File 또는 Java Class를 선택합니다
   • YourAppNameApplication으로 이름을 지정합니다 (실제 앱 이름으로 교체)
   • Application 클래스를 확장하도록 만듭니다

2. AndroidManifest.xml에 등록:

   • app/src/main/AndroidManifest.xml을 엽니다
   • <application> 태그에 android:name=".YourAppNameApplication" 추가

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application
        android:name=".YourAppNameApplication"
        android:allowBackup="true">
        <!-- Activity들 -->
    </application>
</manifest>

실제 코드 사용

예제 클라이언트 ID를 콘솔의 실제 클라이언트 ID로 교체하세요.

Kotlin

import com.nf4.Netfunnel

class YourAppNameApplication : Application() {
    override fun onCreate() {
        Netfunnel.initialize(
            clientId = "{{CLIENT_ID}}"
        )
        
        super.onCreate()
    }
}

Java

import com.nf4.Netfunnel;

public class YourAppNameApplication extends Application {
    @Override
    public void onCreate() {
        Netfunnel.INSTANCE.initialize(
            "{{CLIENT_ID}}"
        );
        
        super.onCreate();
    }
}

고급: 예외 처리

프로덕션 앱의 경우 try-catch 오류 처리를 추가하고 printLog: false로 설정합니다:

Kotlin

import com.nf4.Netfunnel
import android.util.Log

class YourAppNameApplication : Application() {
    override fun onCreate() {
        try {
            Netfunnel.initialize(
                clientId = "{{CLIENT_ID}}"
            )
        } catch (e: Exception) {
            Log.e("NetFUNNEL", "Initialization failed", e)
            // 오류 처리: 오류 화면 표시 또는 앱 종료
        }
        
        super.onCreate()
    }
}

Java

import com.nf4.Netfunnel;
import android.util.Log;

public class YourAppNameApplication extends Application {
    @Override
    public void onCreate() {
        try {
            Netfunnel.INSTANCE.initialize(
                "{{CLIENT_ID}}"
            );
        } catch (Exception e) {
            Log.e("NetFUNNEL", "Initialization failed", e);
            // 오류 처리: 오류 화면 표시 또는 앱 종료
        }
        
        super.onCreate();
    }
}

필수 매개변수

매개변수	유형	필수	설명
clientId	String	예	NetFUNNEL 클라이언트 ID

우회 모드

clientId 누락 = 우회 모드(대기실 보호 없음)

더 많은 구성 옵션

networkTimeout, retryCount, printLog 등 추가 초기화 매개변수에 대한 자세한 내용은 설정 옵션 참조를 참조하세요.

---

4단계: 빌드 및 설치 확인

SDK 설정 및 초기화를 완료했으므로 프로젝트를 빌드하고 NetFUNNEL이 올바르게 작동하는지 확인하겠습니다.

4.1 프로젝트 빌드

동기화 및 빌드

1. Gradle 파일과 프로젝트 동기화

   • File → Sync Project with Gradle Files로 이동
   • 또는 나타나는 경우 Sync Now 알림을 클릭
   • 동기화가 성공적으로 완료될 때까지 대기

2. 정리 및 재빌드

   • Build → Clean Project로 이동
   • 정리 완료 후 Build → Assemble Project로 이동
   • 오류가 있는지 Build 탭을 모니터링합니다

빌드 성공 확인

1. 빌드 출력 확인

   • Build 탭에 컴파일 오류가 없는지 확인
   • 성공적인 의존성 해결 메시지 확인
   • NetFUNNEL AAR 파일이 올바르게 포함되었는지 확인

2. 의존성 확인

   • Project 탭에서 External Libraries 확장
   • NetFUNNEL 관련 라이브러리가 나열되어 있는지 확인
   • Ktor 및 Kotlinx Serialization 의존성이 있는지 확인

4.2 NetFUNNEL 초기화 테스트

디버그 로깅 활성화

NetFUNNEL이 올바르게 초기화되는지 확인하려면 Application 클래스에서 일시적으로 디버그 로깅을 활성화합니다:

디버그 로깅 비활성화

성능 및 보안을 위해 프로덕션 빌드에서는 printLog = false로 설정하는 것을 기억하세요.

Kotlin

class YourAppNameApplication : Application() {
    override fun onCreate() {
        Netfunnel.initialize(
            clientId = "{{CLIENT_ID}}",
            printLog = true  // 디버그 로깅 활성화
        )
        
        super.onCreate()
    }
}

Java

public class YourAppNameApplication extends Application {
    @Override
    public void onCreate() {
        Netfunnel.INSTANCE.initialize(
            "{{CLIENT_ID}}"
        );
        
        super.onCreate();
    }
}

Logcat 출력 모니터링

1. Logcat 열기

   • View → Tool Windows → Logcat로 이동
   • 또는 하단 패널의 Logcat 탭을 클릭

2. NetFUNNEL 로그 필터링

   • Logcat 필터 필드에 package:mine NetFUNNEL을 입력하여 앱 패키지 및 NetFUNNEL 로그로 필터링
   • 이렇게 하면 NetFUNNEL 관련 로그 메시지만 표시됩니다

3. 앱 실행

   • 기기 또는 에뮬레이터에서 앱을 실행합니다
   • Logcat에서 초기화 성공 메시지를 확인합니다:

   YYYY-MM-DD HH:MM:SS.mmm  PID-TID  NetFUNNEL               com.your.package.name  D  [NF4] Initialization successful. NetFUNNEL Version: {{version}}

---

문제 해결

설치 또는 초기화 중 문제가 발생하면 다음을 포함한 일반적인 문제에 대한 상세한 해결 방법을 위해 포괄적인 문제 해결 & FAQ 가이드를 참조하세요:

• 설치 문제: AAR 파일 로딩, 의존성 해결, 빌드 구성
• 초기화 문제: 에이전트 초기화 안 됨, manifest 등록, 우회 모드
• 함수 호출 오류: 초기화 오류, 콜백 문제, 컨텍스트 문제
• 네트워크 및 연결 문제: 타임아웃 오류, 연결 문제, 서버 통신
• 빌드 및 환경 문제: ProGuard/R8 구성, Android 버전 호환성

일반적인 문제에 대한 즉각적인 도움:

1. 디버그 로깅 활성화: 초기화에서 printLog = true 설정
2. Logcat 확인: package:mine NetFUNNEL로 필터링하여 상세 로그 확인
3. 구성 확인: 모든 설정이 NetFUNNEL 콘솔과 일치하는지 다시 확인
4. 간단한 설정으로 테스트: 먼저 기본 구성으로 시작

---