メインコンテンツまでスキップ
バージョン: 4.6.1

トラブルシューティング & FAQ

NetFUNNEL Androidエージェント統合に関する一般的な問題、解決方法、およびよくある質問です。

目次​

インストール問題​

AARファイルがロードされない​

症状:

  • NetFUNNELクラスに関連するビルドエラー
  • "Cannot resolve symbol"エラー
  • AARファイルが見つからないエラー

解決方法:

  1. AARファイルの場所を確認: .aarファイルがapp/libs/ディレクトリにあることを確認
  2. build.gradle構成を確認: 依存関係が正しく追加されていることを確認
  3. クリーンおよび再ビルド: プロジェクトをクリーンしてから再ビルド
  4. ファイル権限を確認: AARファイルが読み取り可能であることを確認
// build.gradle.ktsで確認
dependencies {
    implementation(files("libs/netfunnel-android-agent-release-{{latest}}.aar"))
}

外部依存関係が解決されない​

症状:

  • KtorまたはKotlinx Serializationが見つからない
  • 外部ライブラリに関するビルドエラー
  • 欠落した依存関係の警告

解決方法:

  1. 必須依存関係を追加: すべての外部依存関係が追加されていることを確認
  2. バージョンを確認: 互換性のあるバージョンを使用
  3. プロジェクト同期: Gradleファイルとプロジェクトを同期
// 必須依存関係を追加
dependencies {
    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")
}

ビルド構成問題​

症状:

  • コンパイルエラー
  • 互換性のないAPIレベルエラー
  • Javaバージョン互換性問題

解決方法:

  1. APIレベルを確認: minSdk >= 22およびtargetSdk >= 22であることを確認
  2. Javaバージョンを確認: Java 1.8以上を使用
  3. ビルド機能を確認: viewBinding = trueを有効化
// 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
    }
}

初期化問題​

エージェントが初期化されない​

症状:

  • LogcatにNetFUNNELログがない
  • 関数を使用できない
  • バイパスモード動作

解決方法:

  1. 初期化の場所を確認: 初期化がApplication.onCreate()にあることを確認
  2. パラメータを確認: すべての必須パラメータが提供されていることを確認
  3. クライアントIDを確認: clientIdが正しく、アクセス可能であることを確認
  4. ロギングを有効化: デバッグのためにprintLog = trueを設定
// 正しい初期化
class SampleApplication : Application() {
    override fun onCreate() {
        Netfunnel.initialize(
            clientId = "{{CLIENT_ID}}",
            printLog = true // デバッグのために有効化
        )
        
        super.onCreate()
    }
}

マニフェスト登録の欠落​

症状:

  • Applicationクラスが呼び出されない
  • 初期化が発生しない
  • アプリ起動時にクラッシュ

解決方法:

  1. Applicationクラスを登録: AndroidManifest.xmlに追加
  2. クラス名を確認: 正しいクラス名が使用されていることを確認
  3. パッケージを確認: パッケージ名が一致していることを確認
<!-- AndroidManifest.xml -->
<application
    android:name=".SampleApplication"
    android:allowBackup="true">
    <!-- Activityたち -->
</application>

バイパスモード (待合室なし)​

症状:

  • ユーザーが待合室なしでアプリに直接アクセス
  • NetFUNNELトラフィック制御なし
  • 関数は動作するが保護機能なし

解決方法:

  1. クライアントIDを確認: clientIdが正しく、アクセス可能であることを確認
  2. セグメント状態を確認: コンソールでセグメントが有効化されていることを確認
  3. 進入許容数を確認: 進入許容数が無制限に設定されていないことを確認
  4. ロギングを有効化: 初期化エラーに関するログを確認

関数呼び出しエラー​

"Netfunnel is not initialized"エラー​

症状:

  • IllegalStateException: Netfunnel is not initialized
  • 関数が例外をスロー
  • NetFUNNEL関数呼び出し時にアプリクラッシュ

解決方法:

  1. 初期化を確認: Netfunnel.initialize()が最初に呼び出されていることを確認
  2. タイミングを確認: 初期化前に関数を呼び出さない
  3. Applicationクラスを確認: Applicationクラスが正しく登録されていることを確認
// 関数呼び出し前に初期化されているか確認
if (Netfunnel.isInitialized()) {
    Netfunnel.nfStart(projectKey, segmentKey, callback, this)
} else {
    Log.e("NetFUNNEL", "エージェントが初期化されていない")
    // エラー処理または初期化
}

コールバックが実行されない​

症状:

  • nfStartが呼び出されたがコールバックが実行されない
  • 応答を受信しない
  • コールバックを待ってアプリが停止

解決方法:

  1. ネットワークを確認: NetFUNNELサーバーへのネットワークリクエストを確認
  2. ロギングを有効化: デバッグのためにprintLog = trueを設定
  3. セグメント状態を確認: セグメントがBlock状態でないことを確認
  4. コールバック実装を確認: コールバックが正しく実装されていることを確認
// デバッグのためにロギングを有効化
Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    printLog = true // ロギングを有効化
)

// LogcatでNetFUNNELメッセージログを確認

Activityコンテキスト問題​

症状:

  • IllegalArgumentException: Activity cannot be null
  • コンテキスト関連エラー
  • 関数呼び出し時にアプリクラッシュ

解決方法:

  1. Activityコンテキストを確認: 有効なActivityが渡されていることを確認
  2. タイミングを確認: Activityが破棄された後に関数を呼び出さない
  3. 適切なライフサイクルを使用: 適切なライフサイクルメソッドで関数を呼び出す
// 正しい使用方法
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)
    
    // ここで呼び出しても安全
    Netfunnel.nfStart(projectKey, segmentKey, callback, this)
}

// onDestroy以降は呼び出さない
override fun onDestroy() {
    super.onDestroy()
    // ここではNetFUNNEL関数を呼び出さない
}

ネットワークおよび接続問題​

ネットワークタイムアウトエラー​

症状:

  • ステータスコード1002とともにNetworkErrorが発生
  • リクエストがタイムアウト
  • コールバックを受信しない

解決方法:

  1. タイムアウトを増加: networkTimeoutをより高い値に設定 (最大10000ms)
  2. 再試行を構成: retryCountを増加
  3. ネットワーク回復: useNetworkRecoveryMode = trueを有効化
Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    networkTimeout = 5000, // タイムアウトを増加
    retryCount = 3, // 再試行を増加
    errorBypass = false
)

ネットワーク接続されないエラー​

症状:

  • ステータスコード1001とともにNetworkErrorが発生
  • インターネット接続なし
  • ネットワーク権限問題

解決方法:

  1. 接続を確認: インターネット接続を確認
  2. 権限を確認: INTERNET権限が付与されていることを確認
  3. ファイアウォールを確認: NetFUNNELドメインがブロックされていないことを確認
  4. エラー処理を実装: NetworkErrorを適切に処理
<!-- AndroidManifest.xml -->
<uses-permission android:name="android.permission.INTERNET" />
// ネットワークエラー処理
private val callback = object : NetfunnelCallback() {
    override fun onNetworkError(statusCode: Int, message: String) {
        when (statusCode) {
            1001 -> {
                // ネットワーク接続されない
                showNetworkErrorDialog()
            }
            1002 -> {
                // ネットワークタイムアウト
                showTimeoutDialog()
            }
        }
    }
}

サーバー通信問題​

症状:

  • NetFUNNELサーバーからの応答なし
  • ログにHTTPエラー
  • 認証失敗

解決方法:

  1. クライアント構成を確認: clientIdが正しいことを確認
  2. 認証を確認: 有効なclientIdを確認
  3. ネットワークを確認: NetFUNNELサーバーへのネットワーク接続を確認
  4. ログを確認: 詳細なエラーメッセージを見るためにロギングを有効化

待合室問題​

待合室が表示されない​

症状:

  • 待合室が表示されない
  • ユーザーが直接進行
  • 視覚的フィードバックなし

解決方法:

  1. 進入許容数を確認: テストのために0に設定
  2. セグメント有効化を確認: セグメントが有効化されていることを確認
  3. テンプレート設定を確認: useNetfunnelTemplate = trueを確認
  4. コールバック実装を確認: コールバックが正しく実装されていることを確認
// デバッグのためにロギングを有効化
Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    printLog = true // ロギングを有効化
)

待合室が停止 (終了しない)​

症状:

  • 待合室が表示されるが進入を許可しない
  • 無限待機
  • 進行表示なし

解決方法:

  1. 進入許容数を確認: 進入許容数の値を増加
  2. セグメント状態を確認: セグメントがBlock状態でないことを確認
  3. ネットワークを確認: ネットワーク接続を確認
  4. サーバー状態を確認: NetFUNNELサーバー状態を確認

カスタムテンプレート問題​

症状:

  • カスタム待合室が更新されない
  • onContinueコールバックが呼び出されない
  • UIがキュー状態を反映しない

解決方法:

  1. テンプレートを無効化: useNetfunnelTemplate = falseを設定
  2. onContinueを実装: onContinueコールバックを処理
  3. コールバック実装を確認: 正しいコールバック設定を確認
// 基本構成
Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    errorBypass = false
)

// onContinueコールバック実装
private val callback = object : NetfunnelCallback() {
    override fun onContinue(statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
        // カスタム待合室UIを更新
        updateCustomWaitingRoom(aheadWait, behindWait, waitTime, progressRate)
    }
}

キー管理問題​

キーが返却されない​

症状:

  • 次のユーザーが無限に待機
  • キューが進行しない
  • キー管理に関するサーバーエラー

解決方法:

  1. 常にnfStopを呼び出し: nfStop/nfStopSectionが呼び出されていることを確認
  2. エラー処理: エラーシナリオでもキーを返却
  3. タイミングを確認: 開始が完了する前に停止を呼び出さない
  4. キー一致を確認: 開始/停止関数に同じキーを使用
// 常にキーを返却
private val callback = object : NetfunnelCallback() {
    override fun onSuccess(statusCode: Int, message: String) {
        try {
            performAction()
        } finally {
            // 常にキーを返却
            Netfunnel.nfStop(projectKey, segmentKey, completeCallback)
        }
    }
    
    override fun onError(statusCode: Int, message: String) {
        // エラーが発生してもキーを返却
        Netfunnel.nfStop(projectKey, segmentKey, completeCallback)
    }
}

キー不一致エラー​

症状:

  • 不正なキーに関するサーバーエラー
  • キーが見つからないエラー
  • 関数呼び出し失敗

解決方法:

  1. キー一貫性: 開始/停止関数に同じキーを使用
  2. キースコープ: 他の作業でキーを再利用しない
  3. タイミング: 開始が完了する前に停止を呼び出さない
  4. コンソールを確認: キーがコンソールと正確に一致していることを確認
// 一貫したキー使用
val projectKey = "service_1"
val segmentKey = "segKey_123"

// 開始
Netfunnel.nfStart(projectKey, segmentKey, callback, this)

// 停止 (同じキーを使用する必要がある)
Netfunnel.nfStop(projectKey, segmentKey, completeCallback)

設定問題​

不正なプロジェクト/セグメントキー​

症状:

  • 関数が呼び出されたが効果なし
  • 不正なセグメント動作
  • サーバーエラー

解決方法:

  1. コンソールを確認: NetFUNNELコンソールでキーを再度確認
  2. 正確にコピー: コンソールに表示されているとおりにキーを正確にコピー
  3. 環境: 正しい環境を使用 (プロダクション vs ステージング)
  4. セグメントタイプを確認: 正しいセグメントタイプを使用 (基本コントロール vs 区間コントロール)

パラメータ有効性検証エラー​

症状:

  • 初期化失敗
  • IllegalArgumentExceptionエラー
  • 不正なパラメータ警告

解決方法:

  1. パラメータ範囲を確認: 値が許可された範囲内にあることを確認
  2. 必須パラメータを確認: すべての必須パラメータが提供されていることを確認
  3. パラメータタイプを確認: 正しいデータタイプが使用されていることを確認
// 有効なパラメータ範囲
Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}", // 必須
    networkTimeout = 5000, // 100-10000である必要がある
    retryCount = 3, // 0-10である必要がある
    printLog = true, // Boolean
    errorBypass = false // Boolean
)

ビルドおよび環境問題​

ProGuard/R8問題​

症状:

  • デバッグでは動作するがリリースでは動作しない
  • クラスが見つからないエラー
  • メソッドが見つからないエラー
  • リリースビルドでNetFUNNEL関数が動作しない

解決方法:

  1. ProGuardルールを追加: NetFUNNELクラスをProGuardルールに追加
  2. R8構成を確認: R8がNetFUNNELクラスを難読化しないように確認
  3. リリースビルドをテスト: リリースビルド構成でテスト

必須ProGuardルール:

app/proguard-rules.proファイルに次のルールを追加してください:

# NetFUNNEL Android Agent - 主要パッケージおよびクラスを保護
-keep class com.nf4.** { *; }

# NetFUNNEL Android Agent - リフレクション関連クラスおよびメンバーを保持
-keepclassmembers class com.nf4.** { *; }

必須な理由:

  • リリースビルドはコード縮小、難読化、および最適化を使用
  • NetFUNNEL Android Agentはリフレクションおよび動的クラスローディングを使用
  • これらのルールなしではNetFUNNELクラスが難読化され、機能が中断される
  • この構成はプロダクションリリースに必須です

テスト:

  1. リリースAPK/Bundleをビルド
  2. デバイスにインストール
  3. NetFUNNEL機能をテスト
  4. クラスローディングエラーに関するLogcatを確認

Androidバージョン互換性​

症状:

  • 以前のAndroidバージョンでアプリクラッシュ
  • APIレベル互換性エラー
  • 機能を使用できないエラー

解決方法:

  1. minSdkを確認: minSdk >= 22であることを確認
  2. targetSdkを確認: targetSdk >= 22であることを確認
  3. デバイスでテスト: 異なるAndroidバージョンの実際のデバイスでテスト
  4. API使用を確認: 互換性のあるAPI使用を確認

開発 vs プロダクション​

症状:

  • 開発では動作するがプロダクションでは動作しない
  • 環境間で異なる動作
  • 構成の違い

解決方法:

  1. 環境構成: 各環境に対する正しい構成を使用
  2. コンソール設定: dev/prod用の別々のセグメント設定
  3. ビルド構成: 正しいビルド構成を確認
  4. テスト: 開発およびプロダクションビルドの両方をテスト

FAQ​

同じアプリで基本コントロールと区間コントロールの両方を使用できますか?​

回答: はい、同じアプリケーションで両方の方法を使用できます:

// ログインのための基本コントロール
fun handleLogin() {
    Netfunnel.nfStart("login_project", "login_segment", loginCallback, this)
}

// チェックアウトのための区間コントロール
fun startCheckout() {
    Netfunnel.nfStartSection("checkout_project", "checkout_segment", checkoutCallback, this)
}

NetworkErrorをどのように処理すべきですか?​

回答: ユーザーに通知し、再試行するか元のロジックを進行してください:

private val callback = object : NetfunnelCallback() {
    override fun onNetworkError(statusCode: Int, message: String) {
            when (statusCode) {
            1001 -> {
                // ネットワーク接続されない
                showNetworkErrorDialog()
            }
            1002 -> {
                // ネットワークタイムアウト - 再試行
                retryWithDelay()
            }
        }
    }
}

private fun retryWithDelay() {
    Handler(Looper.getMainLooper()).postDelayed({
        Netfunnel.nfStart(projectKey, segmentKey, callback, this)
    }, 2000)
}

キー返却を忘れた場合はどうなりますか?​

回答: キーはサーバータイムアウトによって自動返却される可能性がありますが、これはボトルネックを引き起こす可能性があります。常に明示的に返却してください:

// 良い: 常にキーを返却
private val callback = object : NetfunnelCallback() {
    override fun onSuccess(statusCode: Int, message: String) {
        performAction()
            .onSuccess {
                Netfunnel.nfStop(projectKey, segmentKey, completeCallback)
            }
            .onFailure {
                Netfunnel.nfStop(projectKey, segmentKey, completeCallback) // エラーが発生しても
            }
    }
}

NetFUNNELを複数回初期化できますか?​

回答: いいえ、NetFUNNELはApplicationクラスで一度だけ初期化する必要があります。複数回初期化すると予期しない動作が発生する可能性があります。

NetFUNNEL統合をどのようにデバッグしますか?​

回答: ロギングを有効化し、ログを確認してください:

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    printLog = true // ロギングを有効化
)

その後、LogcatでNetFUNNELログメッセージを確認してください。

基本コントロールと区間コントロールの違いは何ですか?​

回答:

  • 基本コントロール: 進入速度を制限 (ユーザーがどれだけ速く進入できるか)
  • 区間コントロール: 固定された同時ユーザー数を維持 (同時にアクティブにできるユーザー数)

シンプルな進入制限には基本コントロールを、特定の同時性レベル維持には区間コントロールを使用してください。

FragmentでNetFUNNELを使用できますか?​

回答: はい、ただしActivityコンテキストを渡す必要があります:

class MyFragment : Fragment() {
    fun startNetFUNNEL() {
        activity?.let { activity ->
            Netfunnel.nfStart(projectKey, segmentKey, callback, activity)
        }
    }
}

ヘルプを受ける​

まだ問題が発生する場合:

  1. ログを確認: printLog = trueを有効化し、Logcatを確認
  2. 構成を確認: NetFUNNELコンソールのすべての設定を再度確認
  3. シンプルな設定でテスト: 基本構成から開始し、段階的に複雑さを追加
  4. サポートチームに問い合わせ: 具体的なエラー詳細とともにNetFUNNELサポートチームに問い合わせ

関連ドキュメント​