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

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

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

目次​

完全な初期化例​

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

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    networkTimeout = 3000,
    retryCount = 0,
    printLog = false,
    errorBypass = false,
    useNetfunnelTemplate = true,
    userId = "user_67890",
    useNetworkRecoveryMode = true,
    statusBarStyle = null
)

必須パラメータ​

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

パラメータ型説明必須例
clientIdStringNetFUNNELクライアントIDはい"{{CLIENT_ID}}"
バイパスモード

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

ネットワーク設定​

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

パラメータ型必須デフォルト値範囲
networkTimeoutLongオプション3000100–10000
retryCountIntオプション00–10
useNetworkRecoveryModeBooleanオプションfalsetrue/false

networkTimeout​

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

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

動作:

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

例:

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

重要な注意事項:

  • 短すぎる値は正常なリクエストがタイムアウトとして処理される可能性があります
  • networkTimeout = 3000およびretryCount = 3の場合、onNetworkErrorコールバック前の最大待機時間は12秒です
  • エラー応答が35msに到着しても、再試行は次の試行前に2.965秒待機します

retryCount​

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

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

動作:

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

例:

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

重要な注意事項:

  • 再試行中にリクエストが成功すると、再試行プロセスが即座に停止します
  • すべての再試行試行が枯渇した後、onNetworkErrorコールバックがトリガーされます
  • 各再試行はnetworkTimeout設定に準拠します

useNetworkRecoveryMode​

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

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

これが解決する問題:

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

動作:

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

回復シナリオ:

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

重要な注意事項:

  • useNetworkRecoveryMode = trueは待機中のネットワーク失敗中にのみ待合室を維持します
  • ネットワークが待機が開始される前に失敗すると、onNetworkErrorコールバックが引き続きトリガーされます
  • この設定は一時的なネットワーク問題によりユーザーが待機位置を失うことを防ぎます

デバッグオプション​

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

パラメータ型必須デフォルト値オプション
printLogBooleanオプションfalsetrue/false

printLog​

NetFUNNELログをLogcatに出力します。

使用方法:

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

Logcatでログを確認:

  1. Android Studio Logcatを開く
  2. package:mine NetFUNNELでフィルタリング
  3. NetFUNNELログメッセージを確認

ログ出力:

  • 初期化状態
  • ネットワークリクエストの詳細
  • コールバック応答
  • エラーメッセージ
  • キー管理イベント

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

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

パラメータ型必須デフォルト値オプション
useNetfunnelTemplateBooleanオプションtruetrue/false

useNetfunnelTemplate​

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

オプション:

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

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

useNetfunnelTemplate = falseの場合、カスタム待合室UIを実装し、onContinueコールバックを処理してリアルタイム待機情報を受信する必要があります。

onContinueコールバックパラメータ:

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

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

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. カスタムテンプレートで初期化:

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

2. カスタムダイアログXMLレイアウト:

<!-- dialog_netfunnel.xml -->
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:background="@drawable/bg_dialog_rounded"
    android:orientation="vertical"
    android:padding="24dp">
    
    <TextView
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Expected Wait Time"
        android:textSize="16sp"
        android:textStyle="bold" />
        
    <TextView
        android:id="@+id/txt_wait_time"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="00:00:00"
        android:textSize="28sp"
        android:textStyle="bold" />
        
    <ProgressBar
        android:id="@+id/progress_bar"
        style="?android:attr/progressBarStyleHorizontal"
        android:layout_width="match_parent"
        android:layout_height="12dp"
        android:progress="50" />
        
    <TextView
        android:id="@+id/txt_front_queue"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Users ahead: 0"
        android:textSize="15sp" />
        
    <TextView
        android:id="@+id/txt_behind_queue"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Users behind: 0"
        android:textSize="15sp" />
        
    <Button
        android:id="@+id/btn_cancel"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Close"
        android:textSize="15sp" />
</LinearLayout>

3. カスタムダイアログコントローラー:

class NetfunnelDialog(
    context: Context,
    private val onClose: () -> Unit
) : Dialog(context) {
    private lateinit var binding: DialogNetfunnelBinding
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        binding = DialogNetfunnelBinding.inflate(layoutInflater)
        setContentView(binding.root)
        
        binding.btnCancel.setOnClickListener {
            closeDialog()
        }
    }
    
    private fun closeDialog() {
        dismiss()
        onClose()  // 待機終了のためにNetfunnel.nfStop()を呼び出し
    }
    
    fun updateDialog(aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
        "Users ahead: $aheadWait".also { binding.txtFrontQueue.text = it }
        "Users behind: $behindWait".also { binding.txtBehindQueue.text = it }
        binding.txtWaitTime.text = waitTime
        binding.progressBar.progress = progressRate
    }
}

4. 完全なコールバック実装:

private val callback = object : NetfunnelCallback() {
    override fun onContinue(statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
        activity.runOnUiThread {
            if (dialog == null) {
                dialog = NetfunnelDialog(activity) { 
                    Netfunnel.nfStop("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", stopCallback)
                }.apply {
                    setCanceledOnTouchOutside(false)
                    show()
                }
            }
            dialog?.updateDialog(aheadWait, behindWait, waitTime, progressRate)
        }
    }
    
    override fun onSuccess(statusCode: Int, message: String) {
        dialog?.dismiss()
        dialog = null
        // メインActivityに移動
    }
    
    override fun onError(statusCode: Int, message: String) {
        dialog?.dismiss()
        dialog = null
        // エラー処理
    }
}

重要な注意事項:

  • ダイアログ作成: ダイアログを一度だけ作成し、その後updateDialog()でUIを更新
  • UI更新: UI変更時は常にrunOnUiThreadを使用
  • 適切な終了: 進入キーを返却するためにダイアログを閉じる際にNetfunnel.nfStop()を呼び出し
  • 制限された機能: カスタムテンプレートは高度な待合室機能に制限があります
  • 推奨事項: カスタムUIが必要な場合を除き、完全な機能のためにuseNetfunnelTemplate = trueを使用

エラー処理オプション​

エラーが処理され、ユーザーに表示される方法を制御します。

パラメータ型必須デフォルト値オプション
errorBypassBooleanオプションfalsetrue/false

errorBypass​

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

動作:

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

errorBypass = trueの場合:

  • onErrorおよびonNetworkErrorコールバックが呼び出されない
  • 代わりにonSuccessコールバックがトリガーされる
  • onSuccessコールバックのみを実装すればよい
  • すべてのエラー状況がバイパスされる

errorBypass = trueのユースケース:

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

重要な警告:

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

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

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

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

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

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

NetFUNNEL AndroidエージェントはonNetworkErrorコールバックを通じて詳細なネットワークエラー情報を提供します。

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

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

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

private val callback = object : NetfunnelCallback() {
    override fun onNetworkError(statusCode: Int, message: String) {
        when (statusCode) {
            1001 -> {
                // ネットワーク接続がブロックされた - 即座にユーザー案内を表示
                showToast("ネットワーク接続に失敗しました。ネットワーク設定を確認してください。", activity)
            }
            1002 -> {
                // ネットワークタイムアウト - 再試行画面に移動
                navigateToNetworkErrorActivity(activity)
            }
        }
    }
}

エラー処理戦略:

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

UI構成​

待合室UIの外観および動作を制御します。

パラメータ型必須デフォルト値オプション
statusBarStyleString?オプションnullnull, "auto", "black", "white"

statusBarStyle​

NetFUNNEL待合室(WebView)のステータスバースタイルおよびアイコン色を制御します。

利用可能な値:

値説明動作
null (デフォルト値)アプリのデフォルトテーマを使用ステータスバーが表示される、フルスクリーンモードなし
"auto"テーマに応じた自動アイコン色ライトモード: 黒色アイコン、ダークモード: 白色アイコン
"black"常に黒色アイコンテーマに関係なく固定された黒色アイコン色
"white"常に白色アイコンテーマに関係なく固定された白色アイコン色

動作の詳細:

デフォルト値 (null):

  • アプリのデフォルトテーマ設定に従う
  • フルスクリーンモードが適用されない
  • ステータスバーが正常に表示される

オプション値 ("auto", "black", "white"):

  • フルスクリーンモードが自動的に適用される
  • ステータスバーが透明になる
  • 選択したオプションに応じてアイコン色が制御される

使用例:

1. デフォルト動作:

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    statusBarStyle = null  // アプリのデフォルトテーマを使用
)

2. 自動アイコン色:

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    statusBarStyle = "auto"  // テーマに応じてアイコン色を自動調整
)

3. 固定された黒色アイコン:

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    statusBarStyle = "black"  // 常に黒色アイコン
)

4. 固定された白色アイコン:

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    statusBarStyle = "white"  // 常に白色アイコン
)

重要な注意事項:

  • フルスクリーンモード: オプション値("auto", "black", "white")を使用すると、フルスクリーンモードが自動的に適用されます
  • 透明度: オプション値を使用すると、ステータスバーが透明になります
  • テーマ互換性: "auto"オプションはライト/ダークテーマに自動的に適応します
  • アイコン可視性: 待合室の背景に応じて適切なアイコン色を選択
ステータスバー構成ガイド

ステータスバー構成オプションの詳細については、機能ガイド - 待合室ステータスバー設定を参照してください。

高度なオプション​

高度なユースケースのための追加構成オプションです。

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

userId​

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

使用方法:

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

ユースケース:

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

完全な例​

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

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    networkTimeout = 5000,
    retryCount = 2,
    printLog = false,
    errorBypass = false,
    useNetfunnelTemplate = true,
    userId = "user_67890",
    useNetworkRecoveryMode = true,
    statusBarStyle = null
)

関連ドキュメント​