iOSエージェントトラブルシューティング
NetFUNNEL 4 iOSエージェントの一般的な問題を解決するための包括的なガイドです。
迅速な診断
一般的な問題チェックリスト
特定の解決方法を確認する前に、次の一般的な問題を確認してください:
- フレームワークがプロジェクトに正しく追加されている
- AppDelegateで初期化が呼び出されている
- デリゲートメソッドが正しく実装されている
- プロジェクト/セグメントキーがコンソールと正確に一致している
- テストのために進入許容数が0に設定されている
- コンソールでセグメントが有効化されている
- ネットワーク接続が利用可能である
インストール問題
フレームワークが見つからない
エラー: No such module 'Netfunnel_iOS'
症状:
- importエラーでビルド失敗
- Xcodeに赤いエラーインジケーターが表示される
- モジュールが認識されない
解決方法:
-
フレームワーク登録を確認:
- プロジェクト → General → Frameworks, Libraries, and Embedded Contentに移動
- リストに
netfunnel_ios.xcframeworkが表示されることを確認 - フレームワークの横に疑問符(?)があるか確認
-
フレームワークパスを修正:
フレームワークを右クリック → Source Control → netfunnel_ios.xcframeworkを追加 -
クリーンアップおよび再ビルド:
- Product → Clean Build Folder (⌘+Shift+K)
- Product → Build (⌘+B)
-
フレームワークの場所を確認:
- フレームワークが
Frameworksフォルダにあることを確認 - ファイルパスが正しいことを確認
- フレームワークが
ビルドエラー
エラー: フレームワーク関連のエラーでビルド失敗
症状:
- コンパイルエラー
- リンカーエラー
- アーキテクチャ不一致エラー
解決方法:
-
iOSデプロイターゲットを確認:
- ターゲットがiOS 12.0以上であることを確認
- プロジェクト → Build Settings → iOS Deployment Target
-
アーキテクチャ互換性を確認:
- フレームワークはarm64、armv7をサポートしている
- Build Settings → Architecturesを確認
-
ビルドフォルダをクリーンアップ:
Product → Clean Build Folder -
フレームワークの整合性を確認:
- コンソールからフレームワークを再ダウンロード
- ファイルサイズおよびチェックサムを確認
プライバシーマニフェストの問題
エラー: Invalid privacy manifest
症状:
- プライバシーマニフェストエラーでビルド失敗
- App Store拒否
解決方法:
-
最新バージョンに更新:
- コンソールから最新のフレームワークをダウンロード
- バージョン4.3.2-onpremには更新されたプライバシーマニフェストが含まれている
-
フレームワークバージョンを確認:
let version = Netfunnel.shared.getVersion()
print("NetFUNNEL Version: \(version)")
初期化問題
エージェントが初期化されない
エラー: エージェントがトラフィック制御をバイパスする
症状:
- 待合室が表示されない
- ユーザーがキューをバイパスする
- NetFUNNELログがない
解決方法:
-
初期化順序を確認:
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
// メソッドの開始部分で初期化
Netfunnel.initialize(...)
return true
} -
必須パラメータを確認:
clientIdが空でないことdelegateがプロトコルを実装していること
-
デバッグロギングを有効化:
Netfunnel.initialize(
clientId: "{{CLIENT_ID}}",
delegate: self,
printLog: true // ロギングを有効化
) -
ネットワーク接続を確認:
- ネットワーク接続が利用可能であることを確認
- ブラウザまたはcurlでテスト
無効なクライアントID
エラー: 初期化失敗
症状:
nfNetworkErrorコールバック- 初期化失敗
- エージェントがバイパスモードで実行される
解決方法:
-
クライアントID形式を確認:
// ✅ 正しい形式
clientId: "{{CLIENT_ID}}"
// ❌ 無効な形式
clientId: "" // 空のクライアントID
clientId: nil // クライアントIDの欠落 -
コンソールでクライアントIDを確認:
- NetFUNNELコンソールのクライアントIDと一致することを確認
- クライアントIDが正しくコピーされていることを確認
-
ネットワーク権限を確認:
NSAppTransportSecurityがHTTPSを許可していることを確認- Info.plistでインターネット権限を確認
ランタイム問題
デリゲートコールバックでアプリがクラッシュ
エラー: デリゲートメソッドが呼び出されたときにアプリがクラッシュ
症状:
- 待合室中にアプリがクラッシュ
nfSuccess、nfErrorなどでクラッシュ- スレッド関連のクラッシュ
解決方法:
-
UI更新にメインキューを使用:
func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
DispatchQueue.main.async {
// ここでUI更新
self.updateUI()
}
} -
すべての必須メソッドを実装:
class ViewController: UIViewController, NetfunnelDelegate {
// 必須メソッド
func nfSuccess(...) { }
func nfError(...) { }
func nfNetworkError(...) { }
} -
弱い参照を使用:
func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
DispatchQueue.main.async { [weak self] in
self?.handleSuccess()
}
}
待合室が表示されない
エラー: トラフィック制御にもかかわらず待合室が表示されない
症状:
- ユーザーが即座に進入する
- キュー体験がない
- トラフィック制御が動作しない
解決方法:
-
進入許容数設定を確認:
- テストのために
0に設定 - コンソール → セグメント → 進入許容数
- テストのために
-
セグメントの有効化を確認:
- コンソール → セグメント → セグメントの有効化: ✅ 有効化されている
- 進入ステータス:
待機
-
プロジェクト/セグメントキーを確認:
// キーがコンソールと正確に一致することを確認
Netfunnel.shared.nfStart(projectKey: "exact_project_key", segmentKey: "exact_segment_key") -
デバッグロギングを有効化:
Netfunnel.initialize(
clientId: "{{CLIENT_ID}}",
delegate: self,
printLog: true
)
キーが返却されない
エラー: サーバーにキーが返却されない
症状:
- ユーザーがキューに閉じ込められる
nfCompleteコールバックがない- サーバーにキーが返却されていないと表示される
解決方法:
-
停止関数が呼び出されているか確認:
// 基本コントロール
override func viewWillDisappear(_ animated: Bool) {
super.viewWillDisappear(animated)
Netfunnel.shared.nfStop(projectKey: "project", segmentKey: "segment")
}
// 区間コントロール
func completeSection() {
Netfunnel.shared.nfStopSection(projectKey: "project", segmentKey: "segment")
} -
ネットワーク接続を確認:
- サーバーに到達できることを確認
- ネットワークタイムアウトを確認
-
ネットワークリクエストを監視:
- Xcode Network Inspectorを使用
nfStop/nfStopSectionリクエストを探す
構成問題
無効な制御タイプ
エラー: 制御タイプに対する予期しない動作
症状:
- 基本コントロールが区間コントロールのように動作する
- 区間コントロールが基本コントロールのように動作する
- 無効な待合室動作
解決方法:
-
セグメント構成を確認:
- コンソール → セグメント → 制御タイプ
- 実装と一致することを確認
-
関数呼び出しを確認:
// 基本コントロール
Netfunnel.shared.nfStart(projectKey: "project", segmentKey: "segment")
Netfunnel.shared.nfStop(projectKey: "project", segmentKey: "segment")
// 区間コントロール
Netfunnel.shared.nfStartSection(projectKey: "project", segmentKey: "segment")
Netfunnel.shared.nfStopSection(projectKey: "project", segmentKey: "segment")
ネットワークタイムアウトの問題
エラー: 頻繁なネットワークタイムアウト
症状:
nfNetworkErrorコールバック- ユーザーが遅延を経験する
- サーバータイムアウト
解決方法:
-
ネットワークタイムアウトを増加:
Netfunnel.initialize(
clientId: "{{CLIENT_ID}}",
delegate: self,
networkTimeout: 5000 // デフォルト値3000から増加
) -
ネットワーク回復を有効化:
Netfunnel.initialize(
clientId: "{{CLIENT_ID}}",
delegate: self,
useNetworkRecoveryMode: true
) -
サーバーパフォーマンスを確認:
- サーバー応答時間を監視
- サーバーログでエラーを確認
パフォーマンス問題
遅いアプリパフォーマンス
エラー: NetFUNNELによりアプリが遅くなる
症状:
- UI遅延
- 遅い応答時間
- メモリ問題
解決方法:
-
デバッグロギングを無効化:
Netfunnel.initialize(
clientId: "{{CLIENT_ID}}",
delegate: self,
printLog: false // プロダクション用に無効化
) -
デリゲートメソッドを最適化:
func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
DispatchQueue.main.async { [weak self] in
// 軽量作業のみ
self?.handleSuccess()
}
} -
再試行回数を減少:
Netfunnel.initialize(
clientId: "{{CLIENT_ID}}",
delegate: self,
retryCount: 1 // デフォルト値から減少
)
メモリ問題
エラー: メモリリークまたは高いメモリ使用量
症状:
- メモリ警告
- アプリクラッシュ
- 高いメモリ使用量
解決方法:
-
弱い参照を使用:
func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
DispatchQueue.main.async { [weak self] in
self?.handleSuccess()
}
} -
適切なクリーンアップ:
override func viewWillDisappear(_ animated: Bool) {
super.viewWillDisappear(animated)
// リソースクリーンアップ
Netfunnel.shared.nfStop(projectKey: "project", segmentKey: "segment")
}
デバッグ技術
デバッグロギングの有効化
Netfunnel.initialize(
clientId: "{{CLIENT_ID}}",
delegate: self,
printLog: true // デバッグロギングを有効化
)
ログ出力に含まれるもの:
- ネットワークリクエストおよび応答
- デリゲートメソッド呼び出し
- エラー条件
- キー管理イベント
ネットワークリクエストの監視
-
Xcode Network Inspector:
- Debug → Attach to Process
- Networkタブにすべてのリクエストを表示
-
Charles Proxy:
- HTTPSリクエストを監視
- リクエスト/応答の詳細を表示
-
コンソールログ:
// NetFUNNELメッセージを探す
NSLog(@"NetFUNNEL: %@", message);
さまざまなシナリオのテスト
-
待合室テスト:
- 進入許容数を0に設定
- 待合室が表示されることを確認
-
進入テスト:
- 進入許容数を1に設定
- 即座に進入することを確認
-
キー返却テスト:
- ネットワークリクエストを監視
nfCompleteコールバックを確認
一般的なエラーコード
成功コード
| コード | 意味 | アクション |
|---|---|---|
| 200 | キューを正常に通過した | 正常なフローを進行 |
| 300 | エラー/期限切れによるバイパス | 正常なフローを進行 |
| 303 | ホワイトリストバイパス | 正常なフローを進行 |
エラーコード
| コード | 意味 | アクション |
|---|---|---|
| 500 | システムエラー | 正常なフローを進行 |
| 1001 | ネットワーク接続が切断された | ネットワーク回復を有効化 |
| 1002 | ネットワークタイムアウト/サーバーダウン | サーバーステータスを確認 |
ブロックコード
| コード | 意味 | アクション |
|---|---|---|
| 301 | セグメントがブロックされた | セグメントの有効化を確認 |
| 302 | ユーザーがブラックリストにある | ユーザーステータスを確認 |
閉じるコード
| コード | 意味 | アクション |
|---|---|---|
| 495-499 | ユーザーが待合室を閉じた | ユーザーキャンセルを処理 |
FAQ
Q: エージェントがビルドされない (無効なプライバシーマニフェスト)
A: バージョン4.3.2-onpremから、Appleポリシー変更によりエージェントのprivacyInfoが更新されました。最新のエージェントバージョンを使用していることを確認してください。
Q: デリゲートコールバックでアプリがクラッシュする
A: デリゲートコールバック内部でUIを操作する場合、DispatchQueue.main.asyncを使用してコードがメインスレッドで実行されるようにしてください。
Q: デバッグログを見たいです
A: initialize関数でprintLog: trueを設定してログを有効化してください。デバッグ中のみ使用し、プロダクションビルドではfalseに設定してください。
Q: 待合室が表示されません
A: 進入許容数が0の場合、待合室が表示され、ユーザーは進入できません。コンソール → セグメント設定 → 基本設定 → 進入許容数を0に設定して待合室が表示されるように強制してください。
Q: デリゲートコールバックでUIを更新したいです
A: NetFUNNELコールバックは非同期です。これらのコールバック内部でUI要素を直接呼び出すと、アプリが予期しない動作をしたりクラッシュしたりする可能性があります。UI更新のために常にメインキューにディスパッチしてください。
Q: エージェントバージョンを確認する方法
A: getVersion()を使用してNetFUNNEL iOSエージェントのバージョンを取得します。
ヘルプを受ける
サポートチームに問い合わせる前に
- このトラブルシューティングガイドを確認
- デバッグロギングを有効化 (
printLog: true) - 構成がコンソールと一致することを確認
- 最小構成でテスト
- ネットワーク接続を確認
提供する情報
サポートチームに問い合わせる際は、以下を含めてください:
- エージェントバージョン (
getVersion()) - iOSバージョンおよびデバイスタイプ
- Xcodeバージョン
- エラーメッセージおよびログ
- 使用された構成
- 問題を再現するステップ
サポートリソース
- ドキュメント: このトラブルシューティングガイド
- コンソールログ:
printLog: trueを有効化 - ネットワーク監視: Xcode Network Inspectorを使用
- コミュニティ: NetFUNNEL開発者コミュニティ