インストールおよび初期化

このガイドでは、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. 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. シンプルな設定でテスト: まず基本構成から開始

---