バージョン: 4.6.1

iOSエージェントAPIリファレンス

NetFUNNEL 4 iOSエージェントの関数、デリゲート、および応答形式の完全なリファレンスです。

概要

NetFUNNEL iOSエージェントは、iOSアプリケーションでトラフィック制御を実装するための包括的なAPIを提供します。このリファレンスは、利用可能なすべての関数、デリゲートメソッド、および設定オプションを説明します。

コア関数

エージェントの初期化

設定パラメータでNetFUNNELエージェントを初期化します。

Swift
Objective-C

Netfunnel.initialize(
    clientId: String,
    delegate: NetfunnelDelegate,
    networkTimeout: NSNumber?,
    retryCount: NSNumber?,
    printLog: NSNumber?,
    useNetfunnelTemplate: NSNumber?,
    errorBypass: NSNumber?,
    userId: String?,
    useNetworkRecoveryMode: NSNumber?
)

[agent initializeWithClientId:(NSString *)clientId
                                    delegate:(id<NetfunnelDelegate>)delegate
                              networkTimeout:(NSNumber *)networkTimeout
                                  retryCount:(NSNumber *)retryCount
                                    printLog:(NSNumber *)printLog
                        useNetfunnelTemplate:(NSNumber *)useNetfunnelTemplate
                                 errorBypass:(NSNumber *)errorBypass
                                      userId:(NSString *)userId
                      useNetworkRecoveryMode:(NSNumber *)useNetworkRecoveryMode];

パラメータ:

パラメータ	タイプ	必須	デフォルト値	説明
`clientId`	`String`	✅	-	NetFUNNELコンソールから提供されるクライアントID
`delegate`	`NetfunnelDelegate`	✅	-	プロトコルを実装するデリゲートオブジェクト
`networkTimeout`	`NSNumber (Long)`	❌	3000	ネットワークタイムアウト (ms)、最小: 100、最大: 10000
`retryCount`	`NSNumber (Int)`	❌	0	再試行回数、最小: 0、最大: 10
`printLog`	`NSNumber (Bool)`	❌	false	デバッグロギングを有効化
`useNetfunnelTemplate`	`NSNumber (Bool)`	❌	true	コンソールの待合室テンプレートを使用
`errorBypass`	`NSNumber (Bool)`	❌	false	エラー時にバイパス
`userId`	`String`	❌	N/A	ホワイト/ブラックリストマッチング値
`useNetworkRecoveryMode`	`NSNumber (Bool)`	❌	false	ネットワーク問題中に待合室を開いたままにする

基本コントロール関数

基本コントロール開始

進入速度制限のための基本コントロールを開始します。

Swift
Objective-C

Netfunnel.shared.nfStart(projectKey: String, segmentKey: String)

[[Netfunnel shared] nfStartWithProjectKey:(NSString *)projectKey segmentKey:(NSString *)segmentKey];

パラメータ:

パラメータ	タイプ	必須	説明
`projectKey`	`String`	✅	コンソールの基本コントロールプロジェクトキー
`segmentKey`	`String`	✅	コンソールの基本コントロールセグメントキー

基本コントロール停止

基本コントロールを停止して進入キーを返却します。

Swift
Objective-C

Netfunnel.shared.nfStop(projectKey: String, segmentKey: String)

[[Netfunnel shared] nfStopWithProjectKey:(NSString *)projectKey segmentKey:(NSString *)segmentKey];

パラメータ:

パラメータ	タイプ	必須	説明
`projectKey`	`String`	✅	基本コントロールプロジェクトキー
`segmentKey`	`String`	✅	基本コントロールセグメントキー

区間コントロール関数

区間コントロール開始

同時ユーザー管理のための区間コントロールを開始します。

Swift
Objective-C

Netfunnel.shared.nfStartSection(projectKey: String, segmentKey: String)

[[Netfunnel shared] nfStartSectionWithProjectKey:(NSString *)projectKey segmentKey:(NSString *)segmentKey];

パラメータ:

パラメータ	タイプ	必須	説明
`projectKey`	`String`	✅	コンソールの区間コントロールプロジェクトキー
`segmentKey`	`String`	✅	コンソールの区間コントロールセグメントキー

区間コントロール停止

区間コントロールを停止して区間キーを返却します。

Swift
Objective-C

Netfunnel.shared.nfStopSection(projectKey: String, segmentKey: String)

[[Netfunnel shared] nfStopSectionWithProjectKey:(NSString *)projectKey segmentKey:(NSString *)segmentKey];

パラメータ:

パラメータ	タイプ	必須	説明
`projectKey`	`String`	✅	区間コントロールプロジェクトキー
`segmentKey`	`String`	✅	区間コントロールセグメントキー

ユーティリティ関数

バージョン取得

NetFUNNEL iOSエージェントのバージョンを返します。

Swift
Objective-C

let version = Netfunnel.shared.getVersion()

NSString *version = [[Netfunnel shared] getVersion];

戻り値:

タイプ	説明
`String`	NetFUNNELエージェントバージョン文字列

デリゲートプロトコル

NetfunnelDelegateプロトコルは、NetFUNNELイベントを処理するためのコールバックメソッドを定義します。

必須メソッド

nfSuccess

ユーザーがキューを正常に通過したときに呼び出されます。

Swift
Objective-C

func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String)

- (void)nfSuccessWithProjectKey:(NSString *)projectKey
                      segmentKey:(NSString *)segmentKey
                      statusCode:(NSInteger)statusCode
                         message:(NSString *)message;

パラメータ:

パラメータ	タイプ	説明
`projectKey`	`String`	プロジェクトキー
`segmentKey`	`String`	セグメントキー
`statusCode`	`Int`	ステータスコード (200, 300, 303)
`message`	`String`	成功メッセージ

ステータスコード:

コード	シナリオ
200	キューを通過; アクセスが許可された
300	サブスクリプション/ライセンス期限切れ; プロジェクト/セグメントが無効化; `errorBypass = true`でエラー
303	ホワイトリストのIP/IDからのリクエスト (管理者バイパス)

nfError

システムエラーが発生したときに呼び出されます。

Swift
Objective-C

func nfError(projectKey: String, segmentKey: String, statusCode: Int, message: String)

- (void)nfErrorWithProjectKey:(NSString *)projectKey
                    segmentKey:(NSString *)segmentKey
                    statusCode:(NSInteger)statusCode
                       message:(NSString *)message;

パラメータ:

パラメータ	タイプ	説明
`projectKey`	`String`	プロジェクトキー
`segmentKey`	`String`	セグメントキー
`statusCode`	`Int`	ステータスコード (500)
`message`	`String`	エラーメッセージ

ステータスコード:

コード	シナリオ
500	初期化なしでStartが呼び出された; 無効なキー; セグメントが削除された; 部分的なサーバーレスポンス

nfNetworkError

ネットワークエラーが発生したときに呼び出されます。

Swift
Objective-C

func nfNetworkError(projectKey: String, segmentKey: String, statusCode: Int, message: String)

- (void)nfNetworkErrorWithProjectKey:(NSString *)projectKey
                           segmentKey:(NSString *)segmentKey
                           statusCode:(NSInteger)statusCode
                              message:(NSString *)message;

パラメータ:

パラメータ	タイプ	説明
`projectKey`	`String`	プロジェクトキー
`segmentKey`	`String`	セグメントキー
`statusCode`	`Int`	ステータスコード (1001, 1002)
`message`	`String`	ネットワークエラーメッセージ

ステータスコード:

コード	シナリオ
1001	ネットワーク接続が切断された (Wi-Fi/セルラーがオフ)
1002	ネットワークタイムアウト; 無効なHTML URL; サーバーダウン (例: 502)

オプショナルメソッド

nfBlock

ユーザーがブロックされたときに呼び出されます。

Swift
Objective-C

func nfBlock(projectKey: String, segmentKey: String, statusCode: Int, message: String)

- (void)nfBlockWithProjectKey:(NSString *)projectKey
                   segmentKey:(NSString *)segmentKey
                   statusCode:(NSInteger)statusCode
                      message:(NSString *)message;

ステータスコード:

コード	シナリオ
301	コンソールでセグメントがブロックされた (善意のブロック)
302	ブラックリストのIP/IDからのリクエスト; BotManager Basicが有効化された (悪意のあるブロック)

nfClose

ユーザーが待合室を閉じたときに呼び出されます。

Swift
Objective-C

func nfClose(projectKey: String, segmentKey: String, statusCode: Int, message: String)

- (void)nfCloseWithProjectKey:(NSString *)projectKey
                   segmentKey:(NSString *)segmentKey
                   statusCode:(NSInteger)statusCode
                      message:(NSString *)message;

ステータスコード:

コード	シナリオ
495	待合室後: 閉じるボタンがクリックされた
496	待合室前: 閉じるボタンがクリックされた
497	マクロブロック画面: 閉じるボタンがクリックされた
498	ブロック画面: 閉じるボタンがクリックされた
499	デフォルト待合室: キャンセルボタンがクリックされた

nfContinue

カスタム待機UIを使用する場合 (useNetfunnelTemplate = false) に呼び出されます。

Swift
Objective-C

func nfContinue(projectKey: String, segmentKey: String, statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int)

- (void)nfContinueWithProjectKey:(NSString *)projectKey
                      segmentKey:(NSString *)segmentKey
                      statusCode:(NSInteger)statusCode
                         message:(NSString *)message
                       aheadWait:(NSInteger)aheadWait
                      behindWait:(NSInteger)behindWait
                        waitTime:(NSString *)waitTime
                    progressRate:(NSInteger)progressRate;

パラメータ:

パラメータ	タイプ	説明
`projectKey`	`String`	プロジェクトキー
`segmentKey`	`String`	セグメントキー
`statusCode`	`Int`	ステータスコード (201)
`message`	`String`	継続メッセージ
`aheadWait`	`Int`	キューで前にあるユーザー数
`behindWait`	`Int`	キューで後ろにあるユーザー数
`waitTime`	`String`	予想待機時間
`progressRate`	`Int`	進行率パーセンテージ (0-100)

ステータスコード:

コード	シナリオ
201	`useNetfunnelTemplate = false`の場合 (カスタム待機UI使用中)

nfComplete

サーバーへのキー返却が完了したときに呼び出されます。

Swift
Objective-C

func nfComplete(projectKey: String, segmentKey: String, statusCode: Int, message: String)

- (void)nfCompleteWithProjectKey:(NSString *)projectKey
                      segmentKey:(NSString *)segmentKey
                      statusCode:(NSInteger)statusCode
                         message:(NSString *)message;

ステータスコード:

コード	シナリオ
200	サーバーへの進入キー返却成功
500	サーバーへの進入キー返却失敗

ベストプラクティス

1. UI更新には常にメインキューを使用

func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
    DispatchQueue.main.async {
        // ここでUI更新
        self.updateUI()
    }
}

2. すべての必須デリゲートメソッドを実装

class ViewController: UIViewController, NetfunnelDelegate {
    // 必須メソッド
    func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) { }
    func nfError(projectKey: String, segmentKey: String, statusCode: Int, message: String) { }
    func nfNetworkError(projectKey: String, segmentKey: String, statusCode: Int, message: String) { }
    
    // オプショナルメソッド (必要に応じて実装)
    func nfBlock(projectKey: String, segmentKey: String, statusCode: Int, message: String) { }
    func nfClose(projectKey: String, segmentKey: String, statusCode: Int, message: String) { }
    func nfContinue(projectKey: String, segmentKey: String, statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) { }
    func nfComplete(projectKey: String, segmentKey: String, statusCode: Int, message: String) { }
}

3. エラーを適切に処理

func nfError(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
    // デバッグのためにエラーロギング
    print("NetFUNNEL Error: \(statusCode) - \(message)")
    
    // サービスの可用性のために元のロジックを進行
    DispatchQueue.main.async {
        self.proceedWithOriginalLogic()
    }
}

4. キーを即座に返却

// 基本コントロール - 作業後即座にキー返却
private func performAction() {
    // 作業ロジック
    actionService.performAction { [weak self] result in
        // 作業完了後即座にキー返却
        Netfunnel.shared.nfStop(projectKey: "project", segmentKey: "segment")
    }
}

// 区間コントロール - 全体の区間が完了したときにキー返却
private func completeSection() {
    // 区間完了ロジック
    sectionService.completeSection { [weak self] result in
        if result.success {
            // 区間が完全に完了したときにキー返却
            Netfunnel.shared.nfStopSection(projectKey: "project", segmentKey: "segment")
        }
    }
}

5. 説明的なプロジェクト/セグメントキーを使用

// ✅ 良い: 説明的なキー
Netfunnel.shared.nfStart(projectKey: "ecommerce_app", segmentKey: "checkout_protection")

// ❌ 悪い: 一般的なキー
Netfunnel.shared.nfStart(projectKey: "project1", segmentKey: "segment1")

エラー処理

一般的なエラーシナリオ

エラータイプ	ステータスコード	原因	解決方法
システムエラー	500	無効なキー、セグメントが削除された	コンソール構成を確認
ネットワークエラー	1001	インターネット接続なし	ネットワーク回復モードを有効化
ネットワークエラー	1002	サーバータイムアウト/ダウン	サーバーステータスを確認
ブロック	301	セグメントがブロックされた	セグメントの有効化を確認
ブロック	302	ユーザーがブラックリストにある	ユーザーステータスを確認

エラー回復戦略

func nfNetworkError(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
    switch statusCode {
    case 1001: // ネットワーク接続が切断された
        // オフラインメッセージを表示、ネットワーク回復モードを有効化
        showOfflineMessage()
    case 1002: // ネットワークタイムアウト/サーバーダウン
        // 再試行オプションを表示、サーバーステータスを確認
        showRetryOption()
    default:
        // 不明なネットワークエラーをロギング
        print("Unknown network error: \(statusCode)")
    }
}

パフォーマンス考慮事項

1. デリゲートメソッドのオーバーヘッドを最小化

// ✅ 良い: 効率的なデリゲート実装
func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
    DispatchQueue.main.async { [weak self] in
        self?.handleSuccess()
    }
}

// ❌ 悪い: デリゲートで重い作業
func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
    // 重い作業は別のメソッドに移動すべき
    performHeavyOperation()
    updateDatabase()
    sendAnalytics()
}

2. 弱い参照を使用

class ViewController: UIViewController, NetfunnelDelegate {
    func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        DispatchQueue.main.async { [weak self] in
            self?.handleSuccess()
        }
    }
}

3. キー返却タイミングの最適化

// ✅ 良い: 最適なタイミングでキー返却
override func viewWillDisappear(_ animated: Bool) {
    super.viewWillDisappear(animated)
    Netfunnel.shared.nfStop(projectKey: "project", segmentKey: "segment")
}

// ❌ 悪い: 早すぎるキー返却
override func viewDidLoad() {
    super.viewDidLoad()
    Netfunnel.shared.nfStop(projectKey: "project", segmentKey: "segment") // 早すぎる!
}

デバッグ

デバッグロギングの有効化

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

ネットワークリクエストの監視

XcodeのNetwork InspectorやCharles Proxyなどのツールを使用してNetFUNNELリクエストを監視します:

開始リクエスト: NetFUNNELサーバーへのリクエストを探す
キー返却リクエスト: nfStop/nfStopSectionリクエストを探す
タイムアウト延長: 5003リクエストを探す (区間コントロール)

一般的なデバッグシナリオ

問題	デバッグステップ
待合室が表示されない	進入許容数 = 0を確認、セグメントの有効化を確認
キーが返却されない	`nfStop`/`nfStopSection`呼び出しを確認
デリゲートでアプリがクラッシュ	メインキューでUI更新を確認
ネットワークエラー	`printLog = true`を有効化、接続を確認

概要​

コア関数​

エージェントの初期化​

基本コントロール関数​

基本コントロール開始​

基本コントロール停止​

区間コントロール関数​

区間コントロール開始​

区間コントロール停止​

ユーティリティ関数​

バージョン取得​

デリゲートプロトコル​

必須メソッド​

nfSuccess​

nfError​

nfNetworkError​

オプショナルメソッド​

nfBlock​

nfClose​

nfContinue​

nfComplete​

ベストプラクティス​

1. UI更新には常にメインキューを使用​

2. すべての必須デリゲートメソッドを実装​

3. エラーを適切に処理​

4. キーを即座に返却​

5. 説明的なプロジェクト/セグメントキーを使用​

エラー処理​

一般的なエラーシナリオ​

エラー回復戦略​

パフォーマンス考慮事項​

1. デリゲートメソッドのオーバーヘッドを最小化​

2. 弱い参照を使用​

3. キー返却タイミングの最適化​

デバッグ​

デバッグロギングの有効化​

ネットワークリクエストの監視​

一般的なデバッグシナリオ​

概要

コア関数

エージェントの初期化

基本コントロール関数

基本コントロール開始

基本コントロール停止

区間コントロール関数

区間コントロール開始

区間コントロール停止

ユーティリティ関数

バージョン取得

デリゲートプロトコル

必須メソッド

nfSuccess

nfError

nfNetworkError

オプショナルメソッド

nfBlock

nfClose

nfContinue

nfComplete

ベストプラクティス

1. UI更新には常にメインキューを使用

2. すべての必須デリゲートメソッドを実装

3. エラーを適切に処理

4. キーを即座に返却

5. 説明的なプロジェクト/セグメントキーを使用

エラー処理

一般的なエラーシナリオ

エラー回復戦略

パフォーマンス考慮事項

1. デリゲートメソッドのオーバーヘッドを最小化

2. 弱い参照を使用

3. キー返却タイミングの最適化

デバッグ

デバッグロギングの有効化

ネットワークリクエストの監視

一般的なデバッグシナリオ