Androidエージェント
概要
NetFUNNEL Androidエージェントは、モバイルアプリケーションからNetFUNNELサーバーと通信する専用クライアントです。ユーザーは、適用したいクライアントアプリケーションのコードにエージェントが提供する各種関数を適用・実装することで、仮想待合室を適用できます。
最小要件
- Android API Level 22（Lollipop 5.1）以上
- Java 1.8以上
- Kotlin 2.0.0-RC1以上
外部依存関係
- Ktor（3.0.0以上）
- Kotlinx Serialization（バージョン問わず）
エージェント動作フロー
待機前
- 待機前に設定情報を初期化します。NetFUNNELサーバーから設定情報を取得し、その情報に基づいてオブジェクトを初期化する過程です。
- 「初期化関数」を使用してNetFUNNELの設定情報を初期化してください。
待機中
- 仮想待合室を表示し、トラフィック待機を適用したい画面（ActivityまたはFragment）で待機させる過程です。
- 「待機開始関数」を使用して仮想待合室を適用してください。
待機後
- 待機終了後の処理です。end-userの待機が終了する状況は次のとおりです。
- 待機完了後、進入成功
- 待機中、サーバーエラーまたはネットワークエラーにより進入失敗
- 待機中、end-userによる待機キャンセル
- 「コールバック関数」と「待機終了関数」を使用して、待機終了後のロジックを実装してください。
エージェントのインストール
備考
本ガイドはAndroid Studio環境を前提に記載しています。
NetFUNNEL Androidエージェントは.aar（Android Archive）形式で提供されます。Androidプロジェクトに.aarファイルを追加し、Gradle設定で依存関係を登録します。
エージェントのダウンロード
NetFUNNELコンソールのエージェントタブからNetFUNNEL Androidエージェントをダウンロードします。
.aarファイルの追加
提供された.aarファイルをプロジェクトのapp/libsディレクトリにコピーします。
プロジェクトルート/
├── app/
| └── libs/
| └── netfunnel-android-agent-release-{{latest}}.aar
| └── netfunnel-android-agent-debug-{{latest}}.aar
└── gradle/
Gradle設定
エージェント依存関係の追加
.aarファイルを認識させるため、build.gradleに次のように依存関係を追加します。
Kotlin DSL（build.gradle.kts）
dependencies {
implementation(files("libs/netfunnel-android-agent-release-{{latest}}.aar"))
...
}
Groovy DSL（build.gradle）
dependencies {
implementation files("libs/netfunnel-android-agent-release-{{latest}}.aar")
...
}
備考
NetFUNNEL Androidエージェントはビルド環境に応じて2種類のファイルを提供します。デバッグ時はdebug、アプリ配布時はreleaseの使用を推奨します。
外部ライブラリの追加
NetFUNNEL Androidエージェントには外部ライブラリが含まれていません。以下のライブラリをプロジェクトに追加してください。
- Ktor: ネットワーク通信ライブラリ（3.0.0以上）
- Kotlinx Serialization: 直列化ライブラリ（バージョン問わず）
Kotlin DSL（build.gradle.kts）
dependencies {
val ktorVersion = "{{KTOR_VERSION}}"
val serializationVersion = "{{SERIALIZATION_VERSION}}"
// Ktor dependencies
implementation("io.ktor:ktor-client-core:$ktorVersion")
implementation("io.ktor:ktor-client-okhttp:$ktorVersion")
implementation("io.ktor:ktor-client-content-negotiation:$ktorVersion")
implementation("io.ktor:ktor-serialization-gson:$ktorVersion")
// Serialization dependency
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:$serializationVersion")
...
}
Groovy DSL（build.gradle）
ext {
ktorVersion = "{{KTOR_VERSION}}"
serializationVersion = "{{SERIALIZATION_VERSION}}"
}
dependencies {
// Ktor dependencies
implementation "io.ktor:ktor-client-core:$ktorVersion"
implementation "io.ktor:ktor-client-okhttp:$ktorVersion"
implementation "io.ktor:ktor-client-content-negotiation:$ktorVersion"
implementation "io.ktor:ktor-serialization-gson:$ktorVersion"
// Serialization dependency
implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:$serializationVersion"
...
}
Manifest設定
NetFUNNELサーバーと通信するため、インターネット使用権限を追加する必要があります。AndroidManifest.xmlでインターネットアクセスを許可してください。
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools">
<!-- インターネット権限 -->
<uses-permission android:name="android.permission.INTERNET" />
</manifest>
エージェントの初期化
NetFUNNEL Androidエージェントはアプリ起動と同時に初期化する必要があります。
備考
ApplicationクラスのonCreate()で、アプリ起動時に1回だけ実行されるよう初期化を行ってください。
Kotlin
Netfunnel.initialize(
clientId = "{{CLIENT_ID}}",
serverUrl = "{{SERVER_URL}}",
errorUrl = "{{ERROR_URL}}",
networkTimeout = 3000,
retryCount = 0,
printLog = false,
errorBypass = false,
useNetfunnelTemplate = true,
userId = "{{USER_ID}}",
useNetworkRecoveyMode = true,
healthCheckUrl = "{{HEALTH_CHECK_URL}}",
statusBarStyle = null
)
Java
Netfunnel.INSTANCE.initialize(
"{{CLIENT_ID}}",
"{{SERVER_URL}}",
"{{ERROR_URL}}",
3000,
0,
false,
false,
true,
"{{USER_ID}}",
true,
"{{HEALTH_CHECK_URL}}",
null
);
| パラメータ | 型 | 説明 | 必須 | 条件 |
|---|---|---|---|---|
| clientId | String | ユーザー固有識別子 | O | 空文字不可 |
| serverUrl | String | NetFUNNELサーバーアドレス | X | なし（デフォルト使用） |
| errorUrl | String | NetFUNNELエラーページのHTMLアドレス | X | なし（デフォルト使用） |
| networkTimeout | Long | ネットワーク応答の最大待機時間 | X | デフォルト(ms): 3,000 最大(ms): 10,000 最小(ms): 100 |
| retryCount | Int | ネットワーク失敗時の再試行回数 | X | デフォルト(回): 0 最大(回): 10 最小(回): 0 |
| printLog | Boolean | デバッグ用ログ出力の有無 | X | デフォルト: false |
| errorBypass | Boolean | エラー時のバイパス有無 | X | デフォルト: false |
| useNetfunnelTemplate | Boolean | コンソールでカスタムしたNetFUNNEL待合室の使用有無 | X | デフォルト: true |
| userId | String | ブラックリスト・ホワイトリスト確認用のend-user固有識別子 | X | デフォルト: null |
| useNetworkRecoveryMode | Boolean | ネットワーク切断時の待合室維持・再接続機能の使用有無 | X | デフォルト: false |
| healthCheckUrl | String | ネットワーク遅延とNetFUNNELサーバー障害を区別するためのヘルスチェックURL | X | デフォルト: null |
| statusBarStyle | String | NetFUNNEL待合室（WebView）のステータスバー透過オプション | X | デフォルト: null |
エージェントの適用
NetFUNNEL Androidエージェントが提供する関数により、特定の画面に待合室を適用できます。
備考
開始・終了関数で使用するプロジェクトキーとセグメントキーは、コンソールのプロジェクトタブで確認できます。
コールバック関数
NetFUNNEL Androidエージェントを使用するには、開始関数と終了関数にコールバック関数を必ず注入する必要があります。
待合室は様々な状況（待機成功、キャンセル、ブロック、エラー、ネットワークエラーなど）で終了し、各状況の処理はコールバック関数で実装できます。
| abstract class | abstract function | 実装必須 |
|---|---|---|
| NetfunnelCallback | onSuccess | 必須 |
| NetfunnelCallback | onError | 必須 |
| NetfunnelCallback | onNetworkError | 必須 |
| NetfunnelCallback | onBlock | 任意 |
| NetfunnelCallback | onClose | 任意 |
| NetfunnelCallback | onContinue | 任意 |
| NetfunnelCompleteCallback | onComplete | 任意 |
開始コールバック - NetfunnelCallback
| コールバック | 状態コード | シナリオ |
|---|---|---|
| onSuccess | 200 | キューを正常に通過しサービス利用が許可された |
| onSuccess | 300 | サブスクリプションまたはライセンス期限切れ コンソールのプロジェクト/セグメント無効化 エージェントのerrorBypass=trueかつエラー発生時 |
| onSuccess | 303 | コンソールのホワイトリストに登録されたIPまたはIDでリクエスト（管理者バイパス） |
| onError | 500 | エージェント初期化なしで開始関数を呼んだ 開始関数に存在しないプロジェクト/セグメントキーを使用 コンソールでセグメント削除 サーバーエラーにより応答が一部欠落 |
| onNetworkError | 1001 | ネットワーク接続ブロック（Wi-Fi・携帯データブロック） |
| onNetworkError | 1002 | ネットワークタイムアウト サーバーエラーにより無効なHTML URLを受信 サーバーダウンにより応答なし（502等） |
| onBlock | 301 | コンソールのセグメントブロック（任意の進入ブロック） |
| onBlock | 302 | コンソールのブラックリストに登録されたIPまたはIDでリクエスト（管理者ブロック） コンソールのBotManager Basic有効（悪意ある進入ブロック） |
| onClose | 495 | 事後待合室の閉じるボタンまたは戻るボタン操作時 |
| onClose | 496 | 事前待合室の閉じるボタンまたは戻るボタン操作時 |
| onClose | 497 | マクロブロックルームの閉じるボタンまたは戻るボタン操作時 |
| onClose | 498 | ブロックルームの閉じるボタンまたは戻るボタン操作時 |
| onClose | 499 | 基本待合室のキャンセルボタンまたは戻るボタン操作時 |
| onContinue | 201 | エージェントのuseNetfunnelTemplate=falseかつデフォルト待機時 |
Kotlin
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")
/**
* キュー通過時に実行するロジック
* ex - サービス画面への進入処理
*/
}
override fun onError(statusCode: Int, message: String) {
Log.d(TAG, "onError $statusCode $message")
/**
* エラー発生時に実行するロジック
* ex - ユーザーにエラーメッセージ表示またはバイパス
*/
}
override fun onNetworkError(statusCode: Int, message: String) {
Log.d(TAG, "onNetworkError $statusCode $message")
/**
* ネットワークエラー発生時に実行するロジック
* ex - 再接続案内またはリトライ画面へ遷移
*/
}
override fun onBlock(statusCode: Int, message: String) {
Log.d(TAG, "onBlock $statusCode $message")
/**
* ユーザー進入ブロック時のロジック
* ex - アクセス制限メッセージ表示
*/
}
override fun onClose(statusCode: Int, message: String) {
Log.d(TAG, "onClose $statusCode $message")
/**
* ユーザーが待機をキャンセルまたは戻る操作をした場合のロジック（WebView終了で前画面に復帰）
* ex - 終了案内のToast表示
*/
}
override fun onContinue(statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
Log.d(TAG, "onContinue $statusCode $message")
/**
* 待機中のUI更新ロジック（自社カスタム待合室使用時のみ）
* ex - カスタム待機画面にリアルタイム待機情報を更新
*/
}
}
fun getCallback(): NetfunnelCallback = callback
}
Java
import com.nf4.NetfunnelCallback;
public class StartCallback{
private static final String TAG = "NetFUNNEL";
private final NetfunnelCallback callback = new NetfunnelCallback() {
@Override
public void onSuccess(int statusCode, @NonNull String message) {
Log.d(TAG, "onSuccess " + statusCode + " " + message);
/**
* キュー通過時に実行するロジック
* ex - サービス画面への進入処理
*/
}
@Override
public void onError(int statusCode, @NonNull String message) {
Log.d(TAG, "onError " + statusCode + " " + message);
/**
* エラー発生時に実行するロジック
* ex - ユーザーにエラーメッセージ表示またはバイパス
*/
}
@Override
public void onNetworkError(int statusCode, @NonNull String message) {
Log.d(TAG, "onNetworkError " + statusCode + " " + message);
/**
* ネットワークエラー発生時に実行するロジック
* ex - 再接続案内またはリトライ画面へ遷移
*/
}
@Override
public void onBlock(int statusCode, @NonNull String message) {
Log.d(TAG, "onBlock " + statusCode + " " + message);
/**
* ユーザー進入ブロック時のロジック
* ex - アクセス制限メッセージ表示
*/
}
@Override
public void onClose(int statusCode, @NonNull String message) {
Log.d(TAG, "onClose " + statusCode + " " + message);
/**
* ユーザーが待機をキャンセルした場合のロジック（WebView終了で前画面に復帰）
* ex - 終了案内のToast表示
*/
}
@Override
public void onContinue(int statusCode, @NonNull String message, int aheadWait, int behindWait, @NonNull String waitTime, int progressRate) {
Log.d(TAG, "onContinue " + statusCode + " " + message);
/**
* 待機中のUI更新ロジック（自社カスタム待合室使用時のみ）
* ex - カスタム待機画面にリアルタイム待機情報を更新
*/
}
};
public NetfunnelCallback getCallback() {
return callback;
}
}
終了コールバック - NetfunnelCompleteCallback
| コールバック | 状態コード | シナリオ |
|---|---|---|
| onComplete | 200 | 待機完了後、サーバーへの進入キー返却に成功した場合 |
| onComplete | 500 | 待機完了後、サーバーへの進入キー返却に失敗した場合 |
Kotlin
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")
/**
* 進入キー返却結果の処理ロジック
* ex - キー返却成功時に次ページへ遷移
*/
}
}
fun getCallback(): NetfunnelCompleteCallback = callback
}
Java
import com.nf4.NetfunnelCompleteCallback;
public class StopCallback {
private static final String TAG = "NetFUNNEL";
private final NetfunnelCompleteCallback callback = new NetfunnelCompleteCallback() {
@Override
public void onComplete(int statusCode, @NonNull String message) {
Log.d(TAG, "onComplete " + statusCode + " " + message);
/**
* 進入キー返却結果の処理ロジック
* ex - キー返却成功時に次ページへ遷移
*/
}
};
public NetfunnelCompleteCallback getCallback() {
return callback;
}
}
基本コントロール
開始関数
特定の画面（ActivityまたはFragment）で待合室を適用するには、「待機開始関数」を使用して仮想待合室を表示します。基本コントロールは、end-userが特定画面に進入する際に待機を適用し、サーバー負荷の調整やend-user体験の管理に役立ちます。
Kotlin
Netfunnel.nfStart("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", callback, activity)
Java
Netfunnel.INSTANCE.nfStart("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", callback, activity);
| パラメータ | 型 | 説明 | 必須 |
|---|---|---|---|
| projectKey | String | コンソールの基本コントロールプロジェクトキー | O |
| segmentKey | String | コンソールの基本コントロールセグメントキー | O |
| callback | NetfunnelCallback | 待合室イベント用のユーザー定義コールバック | O |
| activity | Activity | 待合室を適用する画面 | O |
終了関数
基本コントロールの待機が正常に完了した場合、次の2つを実装する必要があります。
- 待機完了後にサービスへ進入するコード（ターゲットページへ進入するコード）
- ビジネスロジック完了後に「待機終了関数」を呼び、サービス進入キーをNetFUNNELサーバーに返却するコード
Kotlin
Netfunnel.nfStop("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", completeCallback)
Java
Netfunnel.INSTANCE.nfStop("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", completeCallback);
| パラメータ | 型 | 説明 | 必須 |
|---|---|---|---|
| projectKey | String | 待機開始関数で使用したプロジェクトキー | O |
| segmentKey | String | 待機開始関数で使用したセグメントキー | O |
| completeCallback | NetfunnelCompleteCallback | 待機完了後のキー返却用ユーザー定義コールバック | O |
区間コントロール
開始関数
区間コントロールは、特定ページの進入と終了の間に待機状態を適用する方式です。区間コントロールにより、ページの特定区間で円滑な流れを維持できます。
- イベントページ進入後、商品を購入し決済完了ボタンを押した場合
- end-userのログインからログアウトまでの期間
区間コントロールを開始するには、「区間開始関数」で制御区間の開始を定義します。これにより、その区間の流れで待機状態を維持できます。
Kotlin
Netfunnel.nfStartSection("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", callback, activity)
Java
Netfunnel.INSTANCE.nfStartSection("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", callback, activity);
| パラメータ | 型 | 説明 | 必須 |
|---|---|---|---|
| projectKey | String | コンソールの区間コントロールプロジェクトキー | O |
| segmentKey | String | コンソールの区間コントロールセグメントキー | O |
| callback | NetfunnelCallback | 待合室イベント用のユーザー定義コールバック | O |
| activity | Activity | 待合室を適用する画面 | O |
終了関数
区間コントロールの待機が正常に完了した場合、次のように実装できます。
- 待機完了後にサービスへ進入するコード（ターゲットページへ進入するコード）
区間コントロールを終了するには、「区間終了関数」で区間の終了を定義します。これによりend-userの区間コントロールを終了し、次のend-userが進入できるようにします。
Kotlin
Netfunnel.nfStopSection("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", completeCallback)
Java
Netfunnel.INSTANCE.nfStopSection("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", completeCallback);
| パラメータ | 型 | 説明 | 必須 |
|---|---|---|---|
| projectKey | String | 待機開始関数で使用したプロジェクトキー | O |
| segmentKey | String | 待機開始関数で使用したセグメントキー | O |
| completeCallback | NetfunnelCompleteCallback | 待機完了後のキー返却用ユーザー定義コールバック | O |