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

初期化オプションリファレンス

NetFUNNEL iOSエージェントのすべての設定オプションおよびパラメータの完全なリファレンスです。

完全な初期化例​

以下は、利用可能なすべての設定オプションを示す完全な例です:

Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: self
)

目次​

必須パラメータ​

これらのパラメータは、エージェントが正しく動作するために必須です。

パラメータタイプ説明必須例
clientIdStringNetFUNNELコンソールから提供されるクライアントIDはい"{{CLIENT_ID}}"
delegateNetfunnelDelegateNetfunnelDelegateプロトコルを実装するデリゲートオブジェクトはいself
バイパスモード

clientIdが欠落すると、エージェントはバイパスモードで実行され、待合室なしで直接アクセスを許可します。

clientId​

タイプ: String
必須: ✅ はい
説明: NetFUNNELコンソールから提供されるクライアントID

Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    // ... 他のパラメータ
)

要件:

  • 空であってはならない
  • NetFUNNELコンソールのクライアントIDと一致する必要がある
  • ドキュメントの例ではプレースホルダー{{CLIENT_ID}}を使用

delegate​

タイプ: NetfunnelDelegate
必須: ✅ はい
説明: NetfunnelDelegateプロトコルを実装するデリゲートオブジェクト

class AppDelegate: UIResponder, UIApplicationDelegate, NetfunnelDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Netfunnel.initialize(
            clientId: "{{CLIENT_ID}}",
            delegate: self
        )
        return true
    }
}

要件:

  • NetfunnelDelegateプロトコルを実装する必要がある
  • 必須デリゲートメソッドを実装する必要がある
  • すべてのコールバックシナリオを処理する必要がある

ネットワーク設定​

NetFUNNELサーバー通信のネットワーク動作およびタイムアウトを制御します。

パラメータタイプ必須デフォルト値範囲
networkTimeoutNSNumber (Long)選択3000100–10000
retryCountNSNumber (Int)選択00–10
useNetworkRecoveryModeNSNumber (Bool)選択falsetrue/false

networkTimeout​

NetFUNNELサーバーAPIリクエストが一時的な失敗と見なされる前の最大タイムアウト持続時間です。

属性値
単位ミリ秒 (ms)
範囲100–10000
デフォルト値3000
適用対象NetFUNNELサーバーエンドポイントのみ

動作:

  • タイムアウト内に応答なし → 一時的な失敗
  • 即座にエラー応答 → タイムアウト待機なし
  • 各再試行は同じタイムアウト設定を使用

例:

  • networkTimeout: 1000 → 1秒タイムアウト
  • networkTimeout: 5000 → 5秒タイムアウト

重要な注意事項:

  • 短すぎる値は正常なリクエストをタイムアウトとして処理する可能性がある
  • networkTimeout: 3000およびretryCount: 3の場合、nfNetworkErrorコールバック前の最大待機時間は12秒
  • エラー応答が35msで到着しても、再試行は次の試行前に2.965秒待機する
Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: self,
    networkTimeout: 5000 // 5秒
)

retryCount​

NetFUNNELサーバーAPI呼び出しでの一時的な失敗に対する追加再試行回数です。

属性値
範囲0–10
デフォルト値0
式総試行 = (設定値) + 1
適用対象NetFUNNELサーバーエンドポイントのみ

動作:

  • 一時的な失敗 → 再試行トリガー (再試行回数 > 0の場合)
  • 永続的な失敗 → すべての再試行試行が尽きる
  • 各再試行はnetworkTimeout設定に準拠

例:

  • retryCount: 0 → 再試行なし (単一試行)
  • retryCount: 1 → 1初期 + 1再試行 (総2回試行)
  • retryCount: 2 → 1初期 + 2再試行 (総3回試行)

重要な注意事項:

  • 再試行中にリクエストが成功すると、再試行プロセスが即座に停止される
  • すべての再試行試行が尽きた後、nfNetworkErrorコールバックがトリガーされる
  • 各再試行はnetworkTimeout設定に準拠
Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: self,
    retryCount: 3 // 最大3回再試行
)

useNetworkRecoveryMode​

ネットワーク問題によりユーザーが待合室から追い出されることを防ぎます。 有効化すると、ネットワーク問題が発生してもユーザーは待機状態(モーダルまたは待合室)に留まり、接続が回復すると自動的に再開されます。

属性値
デフォルト値false
適用対象5002 (進入確認)リクエストのみ
核心的な利点ネットワーク問題中の待機体験に中断なし

これが解決する問題:

  • 回復モードなし: ネットワーク失敗 → エラーページ/コールバック → ユーザーが待機位置を失う
  • 回復モード使用: ネットワーク失敗 → 待機状態を維持 → ネットワーク回復時に自動再開

動作:

モード5002 (進入確認)ユーザー体験
true待機状態を維持、自動回復中断なし
false正常再試行 → エラー処理エラーページ/コールバック

回復シナリオ:

  • 迅速な回復: 既存のキー/シーケンスを維持 (キュー位置を維持)
  • 長期中断: 新しいキー/シーケンスを取得 (位置がリセットされる可能性がある)

重要な注意事項:

  • useNetworkRecoveryMode: trueは、ネットワーク失敗中待機中のみ待合室を維持する
  • ネットワークが待機が開始される前に失敗すると、nfNetworkErrorコールバックが依然としてトリガーされる
  • この設定は、一時的なネットワーク問題によりユーザーが待機位置を失うことを防ぐ
Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: self,
    useNetworkRecoveryMode: true // ネットワーク回復を有効化
)

デバッグオプション​

デバッグおよびロギング機能を有効化します。

パラメータタイプ必須デフォルト値オプション
printLogNSNumber (Bool)選択falsetrue/false

printLog​

XcodeコンソールにNetFUNNELログを出力します。

使用方法:

Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: self,
    printLog: true // デバッグロギングを有効化
)

Xcodeコンソールでログを確認:

  1. Xcodeコンソールを開く
  2. NetFUNNELでフィルタリング
  3. NetFUNNELログメッセージを探す

ログ出力:

  • 初期化ステータス
  • ネットワークリクエストの詳細
  • デリゲートメソッド呼び出し
  • エラーメッセージ
  • キー管理イベント

テンプレートオプション​

待合室の外観およびテンプレートを制御します。

パラメータタイプ必須デフォルト値オプション
useNetfunnelTemplateNSNumber (Bool)選択truetrue/false

useNetfunnelTemplate​

デフォルトのNetFUNNEL待合室テンプレートを使用します。

オプション:

  • true (デフォルト値): NetFUNNELの標準待合室テンプレートを使用
  • false: カスタム待合室テンプレートの実装を許可

カスタムテンプレートの実装:

useNetfunnelTemplate: falseの場合、カスタム待合室UIを実装し、リアルタイムの待機情報を受信するためにnfContinueデリゲートメソッドを処理する必要があります。

nfContinueデリゲートパラメータ:

パラメータタイプ説明例
statusCodeInt待機状態に対する応答コード201
messageString待機状態に対するメッセージ"Continue"
aheadWaitIntキューで前にあるユーザー数{{N}}
behindWaitIntキューで後ろにあるユーザー数{{N}}
waitTimeString予想待機時間{{HH:mm:ss}}
progressRateInt進行率パーセンテージ{{0~100}}

基本的なカスタムテンプレートの例:

extension AppDelegate: NetfunnelDelegate {
    func nfContinue(projectKey: String, segmentKey: String, statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
        // カスタム待合室UIを更新
        updateCustomWaitingRoom(aheadWait: aheadWait, behindWait: behindWait, waitTime: waitTime, progressRate: progressRate)
    }
}

完全なカスタムビューコントローラーの実装:

1. カスタムテンプレートで初期化:

Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: self,
    useNetfunnelTemplate: false  // カスタムテンプレートを有効化
)

2. カスタム待合室ビューコントローラー:

class CustomWaitingRoomViewController: UIViewController {
    @IBOutlet weak var waitTimeLabel: UILabel!
    @IBOutlet weak var progressBar: UIProgressView!
    @IBOutlet weak var aheadLabel: UILabel!
    @IBOutlet weak var behindLabel: UILabel!
    @IBOutlet weak var cancelButton: UIButton!
    
    var onCancel: (() -> Void)?
    
    override func viewDidLoad() {
        super.viewDidLoad()
        setupUI()
    }
    
    private func setupUI() {
        view.backgroundColor = UIColor.systemBackground
        progressBar.progress = 0.0
        cancelButton.addTarget(self, action: #selector(cancelTapped), for: .touchUpInside)
    }
    
    func updateWaitingInfo(aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
        DispatchQueue.main.async {
            self.aheadLabel.text = "前のユーザー数: \(aheadWait)"
            self.behindLabel.text = "後のユーザー数: \(behindWait)"
            self.waitTimeLabel.text = waitTime
            self.progressBar.progress = Float(progressRate) / 100.0
        }
    }
    
    @objc private func cancelTapped() {
        dismiss(animated: true) {
            self.onCancel?()
        }
    }
}

3. 完全なデリゲート実装:

extension AppDelegate: NetfunnelDelegate {
    func nfContinue(projectKey: String, segmentKey: String, statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
        DispatchQueue.main.async {
            if self.waitingRoomVC == nil {
                self.waitingRoomVC = CustomWaitingRoomViewController()
                self.waitingRoomVC?.modalPresentationStyle = .fullScreen
                self.waitingRoomVC?.onCancel = {
                    Netfunnel.shared.nfStop(projectKey: projectKey, segmentKey: segmentKey)
                }
                self.window?.rootViewController?.present(self.waitingRoomVC!, animated: true)
            }
            self.waitingRoomVC?.updateWaitingInfo(aheadWait: aheadWait, behindWait: behindWait, waitTime: waitTime, progressRate: progressRate)
        }
    }
    
    func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        DispatchQueue.main.async {
            self.waitingRoomVC?.dismiss(animated: true)
            self.waitingRoomVC = nil
            // メインコンテンツに移動
        }
    }
    
    func nfError(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        DispatchQueue.main.async {
            self.waitingRoomVC?.dismiss(animated: true)
            self.waitingRoomVC = nil
            // エラー処理
        }
    }
}

重要な注意事項:

  • ビューコントローラーの作成: ビューコントローラーを一度だけ作成し、その後updateWaitingInfoでUIを更新
  • UI更新: UI変更のために常にDispatchQueue.main.asyncを使用
  • 適切な終了: 進入キーを返却するためにビューコントローラーを閉じるときにNetfunnel.shared.nfStop()を呼び出す
  • 制限された機能: カスタムテンプレートは高度な待合室機能に制限がある
  • 推奨事項: カスタムUIが必要な場合を除き、useNetfunnelTemplate: trueを使用して全機能を活用

errorBypass​

タイプ: NSNumber (Bool)
必須: ❌ いいえ
デフォルト値: false
説明: エラー時のトラフィック制御バイパス

Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: self,
    errorBypass: false // エラー時にバイパスしない
)

動作:

値動作
falseエラー発生時にもトラフィック制御を維持 (推奨)
trueエラー時にユーザーが待合室をバイパスできるように許可

エラー処理オプション​

エラー処理およびユーザー表示方法を制御します。

パラメータタイプ必須デフォルト値オプション
errorBypassNSNumber (Bool)選択falsetrue/false

errorBypass​

Error/NetworkErrorをSuccessとして処理します。

動作:

  • false (デフォルト値): 正常なエラー処理 (エラー時にコールバック/リダイレクト)
  • true: エラーを成功として処理してサービスが継続できるように許可 (バイパスモード)

errorBypass: trueの場合:

  • nfErrorおよびnfNetworkErrorデリゲートメソッドが呼び出されない
  • 代わりにnfSuccessデリゲートメソッドがトリガーされる
  • nfSuccessデリゲートメソッドのみを実装すればよい
  • すべてのエラー状況がバイパスされる

errorBypass: trueの使用例:

  • テスト環境
  • ネットワーク接続が核心機能に影響を与えないサービス
  • シンプルなイベント参加システム
  • 開発およびデバッグシナリオ

重要な警告:

  • errorBypass: trueはすべてのエラー状況をバイパスする
  • 重要なネットワーク問題を隠す可能性があるため、注意して使用
  • 重要なトラフィック制御が必要なプロダクション環境では推奨されない

処理されるエラータイプ:

  • ネットワークエラー (1001, 1002)
  • サーバーエラー (500)
  • ユーザーキャンセル (499)
  • 無効な構成エラー

デリゲートベースの統合コールバック: errorBypass: falseの場合、次のデリゲートメソッドがトリガーされます:

  • nfNetworkError: ネットワーク関連エラー (1001, 1002)
  • nfError: サーバーエラー (500)
  • nfClose: ユーザーキャンセル (499)

ネットワークエラーコールバック​

NetFUNNEL iOSエージェントは、nfNetworkErrorデリゲートメソッドを通じて詳細なネットワークエラー情報を提供します。

ネットワークエラータイプ:

ステータスコードメッセージ説明
1001Network Not Connectedネットワーク接続がブロックされた (WiFi/セルラーデータが無効化)
1002Network Timeoutネットワーク応答遅延によるタイムアウト

ネットワークエラー処理の例:

extension AppDelegate: NetfunnelDelegate {
    func nfNetworkError(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        switch statusCode {
        case 1001:
            // ネットワーク接続がブロックされた - 即座にユーザー案内を表示
            showAlert(title: "Network Error", message: "ネットワーク接続に失敗しました。ネットワーク設定を確認してください。")
        case 1002:
            // ネットワークタイムアウト - 再試行画面に移動
            navigateToNetworkErrorScreen()
        default:
            break
        }
    }
}

エラー処理戦略:

  • 1001 (Network Not Connected): 即座にユーザー案内 (通知、トーストメッセージ)
  • 1002 (Network Timeout): 再試行オプションがあるエラー画面に移動

高度なオプション​

高度な使用例のための追加設定オプションです。

パラメータタイプ必須デフォルト値オプション
userIdString?選択nilユーザー識別子文字列

userId​

ホワイトリスト/ブラックリスト管理のためのユーザー識別子を設定します。

使用方法:

Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: self,
    userId: "user_67890" // ユーザー別識別子
)

使用例:

  • 特定ユーザーのホワイトリスト
  • 問題のあるユーザーのブラックリスト
  • ユーザー別トラフィック制御
  • 分析および監視

完全な例​

すべてのオプションが含まれた完全な初期化例です:

Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: self,
    networkTimeout: 5000,
    retryCount: 2,
    printLog: false,
    errorBypass: false,
    useNetfunnelTemplate: true,
    userId: "user_67890",
    useNetworkRecoveryMode: true
)

関連ドキュメント​