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

APIリファレンス

NetFUNNEL Androidエージェントの関数、コールバック、応答形式に関する完全なリファレンスです。

目次​

初期化関数​

Netfunnel.initialize​

目的: 必須構成を使用してNetFUNNEL Androidエージェントを初期化します。

関数シグネチャ:

Netfunnel.initialize(
    clientId: String,
    networkTimeout: Long = 3000,
    retryCount: Int = 0,
    printLog: Boolean = false,
    errorBypass: Boolean = false,
    useNetfunnelTemplate: Boolean = true,
    userId: String? = null,
    useNetworkRecoveryMode: Boolean = false,
    statusBarStyle: String? = null
)

クイックパラメータ概要:

カテゴリパラメータ目的
必須clientId必須クライアント構成
ネットワークnetworkTimeout, retryCount, useNetworkRecoveryModeネットワーク動作および安定性
デバッグprintLogデバッグロギングを有効化
エラー処理errorBypassエラー動作の制御
UI/テンプレートuseNetfunnelTemplate, statusBarStyle待合室の外観
高度userIdホワイトリスト/ブラックリスト用のユーザー識別

基本例:

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}"
)

すべてのオプションを含む完全な例:

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    networkTimeout = 5000,
    retryCount = 2,
    printLog = true,
    errorBypass = false,
    useNetfunnelTemplate = true,
    userId = "user_12345",
    useNetworkRecoveryMode = true,
    statusBarStyle = "auto"
)
完全な構成リファレンス

すべての初期化パラメータ、範囲、動作、使用例の詳細については、初期化オプションリファレンスを参照してください。

基本コントロール関数​

基本コントロールはサービスに対する進入速度を制限します。開始関数が呼び出されるとキーが発行され、待合室が表示されます。停止関数が呼び出されるとキーが返却されます。

nfStart​

目的: 基本コントロールのためにキーを発行し、待合室を表示します。

関数シグネチャ:

Netfunnel.nfStart(
    projectKey: String,
    segmentKey: String,
    callback: NetfunnelCallback,
    activity: Activity
)

パラメータ:

パラメータ型説明必須
projectKeyStringコンソールの基本コントロールプロジェクトキーはい
segmentKeyStringコンソールの基本コントロールセグメントキーはい
callbackNetfunnelCallbackVWRイベントを処理するコールバックはい
activityActivity現在のactivityコンテキストはい

戻り値: void

例:

Netfunnel.nfStart(
    projectKey = "service_1",
    segmentKey = "segKey_8612",
    callback = myCallback,
    activity = this
)

nfStop​

目的: 進入が完了した後にキーを返却します。

関数シグネチャ:

Netfunnel.nfStop(
    projectKey: String,
    segmentKey: String,
    completeCallback: NetfunnelCompleteCallback? = null
)

パラメータ:

パラメータ型説明必須
projectKeyStringコンソールの基本コントロールプロジェクトキーはい
segmentKeyStringコンソールの基本コントロールセグメントキーはい
completeCallbackNetfunnelCompleteCallback?キー返却確認のためのコールバックいいえ

戻り値: void

例:

Netfunnel.nfStop(
    projectKey = "service_1",
    segmentKey = "segKey_8612",
    completeCallback = myCompleteCallback
)
自動返却タイムアウト

停止関数を実行しない場合、セグメントタイムアウト設定に応じてキーが自動的に返却されます (デフォルトタイムアウト: 20秒)。

区間コントロール関数​

区間コントロールは特定の区間で固定数の同時ユーザーを維持します。開始関数が呼び出されるとキーが発行されます。停止関数が呼び出されるまでユーザーはアクティブ区間にいるものと見なされ、キュー内の次のユーザーは許可されません。

ユースケース:

  • マルチステッププロセス: イベントページ進入後、製品購入および決済完了ボタンクリックまで
  • ユーザーセッション管理: ユーザーログインからログアウトまで
  • リソース集約的な作業: 特定の機能に対する最適ユーザー数の維持

nfStartSection​

目的: 区間コントロールのためにキーを発行し、待合室を表示します。

関数シグネチャ:

Netfunnel.nfStartSection(
    projectKey: String,
    segmentKey: String,
    callback: NetfunnelCallback,
    activity: Activity
)

パラメータ:

パラメータ型説明必須
projectKeyStringコンソールの区間コントロールプロジェクトキーはい
segmentKeyStringコンソールの区間コントロールセグメントキーはい
callbackNetfunnelCallbackVWRイベントを処理するコールバックはい
activityActivity現在のactivityコンテキストはい

戻り値: void

例:

Netfunnel.nfStartSection(
    projectKey = "service_1",
    segmentKey = "section_segKey_1234",
    callback = myCallback,
    activity = this
)

nfStopSection​

目的: ユーザーがアクティブ区間を終了するときにキーを返却します。

関数シグネチャ:

Netfunnel.nfStopSection(
    projectKey: String,
    segmentKey: String,
    completeCallback: NetfunnelCompleteCallback? = null
)

パラメータ:

パラメータ型説明必須
projectKeyStringコンソールの区間コントロールプロジェクトキーはい
segmentKeyStringコンソールの区間コントロールセグメントキーはい
completeCallbackNetfunnelCompleteCallback?キー返却確認のためのコールバックいいえ

戻り値: void

例:

Netfunnel.nfStopSection(
    projectKey = "service_1",
    segmentKey = "section_segKey_1234",
    completeCallback = myCompleteCallback
)
区間コントロールの動作

停止関数を実行しない場合、ユーザーはアクティブ区間に留まっているものと見なされ、次のユーザーの進入が遅延する可能性があります。

コールバッククラス​

NetfunnelCallback​

目的: 開始関数に対するNetFUNNELサーバーの応答を処理します。

Androidインターフェース要件

**AndroidではNetfunnelCallbackはすべてのメソッドを実装する必要があるインターフェースです。**一部のメソッドのみを実装することはできません - すべてのコールバックメソッドに対する実装を提供する必要があります。ただし、一部のメソッドは他のメソッドよりも重要です。基本実装の場合、オプショナルメソッドに対してTODO("Not yet implemented")を使用できますが、プロダクションコードではこれを適切な実装に置き換える必要があります。

抽象メソッド:

メソッド必須説明実装戦略
onSuccessはい進入が許可されるかバイパスされるときに呼び出される常に実装 - コアビジネスロジック
onErrorはいシステムエラーが発生したときに呼び出される常に実装 - 一般的にビジネスロジックを進行
onNetworkErrorはいネットワーク接続問題が発生したときに呼び出される常に実装 - 再試行またはビジネスロジックを進行
onBlockオプションユーザーがブロックされるときに呼び出される初期にはTODO使用可能 - ブロックメッセージを表示
onCloseオプションユーザーが待合室を閉じるときに呼び出される初期にはTODO使用可能 - ユーザーキャンセル処理
onContinueオプションカスタム待合室更新のために呼び出される初期にはTODO使用可能 - カスタム待合室にのみ必要

基本実装 (段階的):

初期開発の場合、必須メソッドのみを実装し、残りはTODOを使用できます:

import com.nf4.NetfunnelCallback

class StartCallback {
    companion object {
        private const val TAG = "NetFUNNEL"
    }
    
    private val callback = object : NetfunnelCallback() {
        override fun onSuccess(statusCode: Int, message: String) {
            Log.d(TAG, "onSuccess $statusCode $message")
            // コアビジネスロジック - 常に実装
            proceedWithAction()
        }
        
        override fun onError(statusCode: Int, message: String) {
            Log.d(TAG, "onError $statusCode $message")
            // 一般的にビジネスロジックを進行 - 常に実装
            proceedWithAction()
        }
        
        override fun onNetworkError(statusCode: Int, message: String) {
            Log.d(TAG, "onNetworkError $statusCode $message")
            // 再試行またはビジネスロジックを進行 - 常に実装
            proceedWithAction()
        }
        
        override fun onBlock(statusCode: Int, message: String) {
            TODO("Not yet implemented")
        }
        
        override fun onClose(statusCode: Int, message: String) {
            TODO("Not yet implemented")
        }
        
        override fun onContinue(statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
            TODO("Not yet implemented")
        }
    }
    
    fun getCallback(): NetfunnelCallback = callback
}

完全な実装 (プロダクション準備):

プロダクションコードの場合、すべてのメソッドを適切な処理とともに実装します:

import com.nf4.NetfunnelCallback

class StartCallback {
    companion object {
        private const val TAG = "NetFUNNEL"
    }
    
    private val callback = object : NetfunnelCallback() {
        override fun onSuccess(statusCode: Int, message: String) {
            Log.d(TAG, "onSuccess $statusCode $message")
            /**
             * キュー通過処理ロジック
             * 例 - サービス画面進入処理
             */
            proceedWithAction()
        }
        
        override fun onError(statusCode: Int, message: String) {
            Log.d(TAG, "onError $statusCode $message")
            /**
             * システムエラー処理ロジック - サービス可用性を維持するためにビジネスロジックを進行
             * 例 - サーバーエラーは一般的に一時的であり、ユーザーアクセスをブロックすべきではない
             */
            proceedWithAction()
        }
        
        override fun onNetworkError(statusCode: Int, message: String) {
            Log.d(TAG, "onNetworkError $statusCode $message")
            /**
             * ネットワークエラー処理ロジック - ロギングのみ実行、ビジネスロジックは実行しない
             * 例 - 自動ネットワーク回復のためにuseNetworkRecoveryMode = trueを使用
             */
            // 注意: ここではビジネスロジックを実行しない - ネットワーク回復モードに依存
        }
        
        override fun onBlock(statusCode: Int, message: String) {
            Log.d(TAG, "onBlock $statusCode $message")
            /**
             * ユーザー進入ブロック処理ロジック
             * 例 - アクセス制限メッセージを表示
             */
            showBlockedMessage()
        }
        
        override fun onClose(statusCode: Int, message: String) {
            Log.d(TAG, "onClose $statusCode $message")
            /**
             * ユーザーキャンセル処理ロジック (WebViewが自動的に閉じられ、前の画面に戻る)
             * 例 - 終了通知Toastを表示
             */
            handleUserCancel()
        }
        
        override fun onContinue(statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
            Log.d(TAG, "onContinue $statusCode $message")
            /**
             * 待機進行状況UI更新ロジック (カスタム待合室使用時にのみ適用)
             * 例 - カスタム待機画面にリアルタイム待機情報を更新
             */
            updateCustomWaitingRoom(aheadWait, behindWait, waitTime, progressRate)
        }
    }
    
    fun getCallback(): NetfunnelCallback = callback
}

応答処理戦略:

応答タイプステータスコード動作ビジネスロジックユーザー通知
Success200, 300, 303実行✅ はいオプション
Error500実行✅ はいオプション
NetworkError1001, 1002ロギングのみ❌ いいえオプション
Block301, 302停止❌ いいえ必須
Close495-499停止❌ いいえオプション

onErrorはビジネスロジックを実行するがonNetworkErrorは実行しない理由:

onError (ステータスコード 500) - サーバーエラー:

  • シナリオ: NetFUNNELサーバーが内部エラーに遭遇
  • 戦略: サービス可用性を維持するためにビジネスロジックを実行
  • 根拠: サーバーエラーは一般的に一時的であり、ユーザーアクセスをブロックすべきではない
  • 結果: NetFUNNELに問題があっても継続する堅牢なサービス

onNetworkError (ステータスコード 1001, 1002) - ネットワーク問題:

  • シナリオ: ネットワーク接続問題 (オフライン、タイムアウト)
  • 戦略: ロギングのみ実行、ビジネスロジックは実行しない
  • 根拠: 自動ネットワーク回復のためにuseNetworkRecoveryMode = trueを使用
  • 結果: ネットワーク問題中にユーザーが待合室に留まり、接続が回復すると自動的に再開

ネットワーク回復モードの構成:

最適なネットワークエラー処理のためにApplicationクラスでネットワーク回復を有効にします:

// SampleApplication.kt
Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    useNetworkRecoveryMode = true  // 自動ネットワーク回復を有効化
)

NetfunnelCompleteCallback​

目的: 停止関数に対するNetFUNNELサーバーの応答を処理します。

抽象メソッド:

メソッド必須説明
onCompleteいいえキー返却が完了したときに呼び出される

実装例:

import com.nf4.NetfunnelCompleteCallback

class StopCallback {
    companion object {
        private const val TAG = "NetFUNNEL"
    }
    
    private val callback = object : NetfunnelCompleteCallback() {
        override fun onComplete(statusCode: Int, message: String) {
            Log.d(TAG, "onComplete $statusCode $message")
            /**
             * 進入キー返却結果処理ロジック
             * 例 - キー返却が成功したら次のページに移動
             */
            handleKeyReturnCompletion()
        }
    }
    
    fun getCallback(): NetfunnelCompleteCallback = callback
}

応答オブジェクトスキーマ​

コールバックメソッドは次のパラメータを受け取ります:

パラメータ型説明例
statusCodeIntHTTPステータスコード200, 300, 500, 1001など
messageString応答メッセージ"Success", "Bypass", "Server Error"など
aheadWaitIntキュー前のユーザー数 (onContinueのみ)5
behindWaitIntキュー後のユーザー数 (onContinueのみ)10
waitTimeString予想待機時間 (onContinueのみ)"2 minutes"
progressRateInt進行率パーセンテージ (onContinueのみ)75

ステータスコードリファレンス​

可能なすべてのステータスコードとその意味に関する完全なリファレンスです。

ステータスStatusCodeMessage説明
Success200Successキューを正常に通過し、サービスに進入した。正常なキュー通過。
300Bypassさまざまな条件により進入がバイパスされた。例: サブスクリプション/ライセンス期限切れ、コンソールでプロジェクト/セグメント無効化、errorBypass=true設定およびエラー発生。
303Expressエクスプレス進入成功。コンソールホワイトリストに登録されたIPまたはID (管理者バイパス)。
Error500Server Errorシステムエラーが発生した。例: 開始関数の前にエージェント初期化関数が呼び出されていない、存在しないプロジェクト/セグメントキーを使用、コンソールでセグメント削除、部分応答損失を引き起こすサーバーエラー。
NetworkError1001Network Not Connectedネットワーク接続がブロックされた。WiFi/セルラーデータ無効化。
1002Network Timeoutネットワークタイムアウトが発生した。例: ネットワーク遅延、不正な待合室HTML URL受信、サーバーダウン (502など)。
Block301Blockセグメントがブロック状態である。コンソールでセグメントブロック (善意の進入ブロック)。
302Macro Blockユーザーがブロックされた。例: コンソールブラックリストに登録されたIPまたはID (管理者ブロック)、BotManager Basic有効化 (悪意のある進入ブロック)。
Close495Closed PostWaiting Room事後待合室が閉じられた。ユーザーが事後待合室で閉じるボタンをクリック。
496Closed PreWaiting Room事前待合室が閉じられた。ユーザーが事前待合室で閉じるボタンをクリック。
497Closed Macro Blocking Roomマクロブロック室が閉じられた。ユーザーがマクロブロック室で閉じるボタンをクリック。
498Closed Blocking Roomブロック室が閉じられた。ユーザーがブロック室で閉じるボタンをクリック。
499Canceled Waiting Room基本待合室でキャンセル/閉じるボタンをクリック。ユーザーが基本待合室でキャンセルボタンをクリック。
Continue201Continueカスタムテンプレートのための待合室更新。エージェントuseNetfunnelTemplate=false設定および基本待機中。

ユーティリティ関数​

getVersion​

目的: NetFUNNEL Androidエージェントの現在のバージョンを取得します。

関数シグネチャ:

Netfunnel.getVersion(): String

戻り値: String - NetFUNNEL Androidエージェントのバージョン文字列

例:

val version = Netfunnel.getVersion()
Log.d("NetFUNNEL", "Agent version: $version")

関連ドキュメント​