NetFUNNEL iOSエージェントは、アプリケーション内で出力されるWeb-Viewで発生するトラフィックをコントロールしてサービスインフラを保護し、訪問者にスムーズなユーザー体験を提供します。
- サービスとは? : NetFUNNEL と連動してトラフィックコントロールをかけるための対象ウェブサイト(URL)を意味します。
要求事項
- iOS 12以降
- Storyboard(obj-c, swift), Swift UI で使用可能。
NetFUNNEL iOSエージェントの適用方法
エージェントファイルの適用
エージェントを利用する上位クラスでSurffyAgentをインポートします。
設定情報の初期化
最初に、エージェントの設定を構成するために、提供された初期化関数を利用することを推奨します。
以下に初期化関数を示します:
初期化関数
Function type | Name | Argument | Description |
Initialization | setConfig | tenantURL | NF access URL |
projectDetailURL | URL to get the configuration file from | ||
eumURL | eum data collection URL | ||
delegate | NetFUNNEL delegate declaration view location | ||
oneTimeCallback | Once the configuration has been loaded successfully using setConfig, a callback function will be triggered only once. | ||
Check Initialization | checkConfigSuccess | N/A | Returns true for normal load, false for abnormal load |
viewDidLoad() のオーバーライドポイントに、以下のように setConfig コードを追加します。
//ex> swift
let agent = NetFunnelAgent.shared
agent.setConfig(tenantURL: "The Tenant address provided in the NetFUNNEL console",
projectDetailURL: "The Configuration file load address provided in the NetFUNNEL console",
eumURL : "The EUM address provided in the NetFUNNEL console",
delegate: self,
oneTimeCallback: "It is important to note that after calling setConfig,
the NF function may not work properly if the configuration file has not been loaded.
If there are areas or functions that need to be called only once immediately after setConfig,
place them in a oneTimeCallback or add them as a separate callback.")
//ex> obj-c
NetFunnelAgent *agent = [NetFunnelAgent shared];
[agent setConfigWithTenantURL:@"The Tenant address provided in the NetFUNNEL console"
projectDetailURL:@"The Configuration file load address provided in the NetFUNNEL console"
eumURL:@"The EUM address provided in the NetFUNNEL console"
delegate:self
oneTimeCallback:^{
/*
It is important to note that after calling setConfig,
the NF function may not work properly if the configuration file has not been loaded.
If there are areas or functions that need to be called only once immediately after setConfig,
place them in a oneTimeCallback or add them as a separate callback.
*/
}
];
トラフィック制御の設定
基本コントロール
トラフィック管理が必要なページ(ビューやアクティビティ)の特定の部分に仮想待合室を適用するには、別途提供される待機開始関数をご利用ください。
以下の機能をご確認ください。
基本コントロールのための待機開始関数
Function type | Name | Argument | Description |
Wait-Start function for basic control | NFStart | projectKey |
The project key can be found in the NetFUNNEL console. ex) service_1 |
segmentKey |
The segment key can be found in the NetFUNNEL console when creating a segment. ex) segKey_1234 |
SurffyReqManager 共有シングルトン・オブジェクトを呼び出した後、NFStart 関数を使用する。
待ち時間の最初に与えられたキーを取得するには、NFStop関数を使用する。
//ex> swift
var req = SurffyReqManager.shared
req.NFStart(projectKey: "projectKey", segmentKey: "segmentKey")
//ex> objc-c
SurffyReqManager * req = [SurffyReqManager shared];
[req NFStartWithProjectKey: @"projectKey" segmentKey:@"segmentKey"];
区間コントロール
トラフィック管理が必要なページ(ビューまたはアクティビティ)の特定の部分に仮想待合室を適用するには、別途提供される待機開始関数を使用します。
エンドポイントを持つページへのアクセスを制御するには、区間コントロールを使用します。
- 例)イベントページにアクセスし、サインインした状態で商品を購入し、サインアウトする。
SurffyReqManager共有シングルトン オブジェクトを呼び出した後、NFStartSection関数を使用します。
待ち時間の最初に渡されたキーを取得するには、NFStopSection関数を利用します。
区間コントロールのための待機開始関数
Function type | Name | Argument | Description |
Wait-Start function for path control | NFStartSection | projectKey |
The project key can be found in the NetFUNNEL console. ex) service_1 |
segmentKey |
The segment key can be found in the NetFUNNEL console when creating a segment. ex) segKey_1234 |
//ex> swift
var req = SurffyReqManager.shared
req.NFStartSection(projectKey: "projectKey", segmentKey: "segmentKey")
//ex> objc-c
SurffyReqManager * req = [SurffyReqManager shared];
[req NFStartSectionWithProjectKey: @"projectKey" segmentKey:@"segmentKey"];
Delegate実装
待機中は状況に応じて様々なコールバック関数が呼び出されます。コールバック関数の種類によって進入成功とブロック処理をすることができ、待機がキャンセルされたときにコールバック関数を実装して進入ブロックと待機キャンセル時に発生する様々なユーザーシナリオを実装することができます。
以下はサーバーから受け取るリターンコードと呼び出されるDelegateの案内です。
Return Code | Description | Delegate |
0 |
Network error for request to enter the service |
SurffyActionError |
200 (SUCCESS) |
Connection success |
SurffyActionSuccess |
201 (CONTINUE) | Waiting (Enter the queue) | |
300 (BYPASS) | Bypass access | SurffyActionBypass |
301 (SERVERSIDE_BLOCK) | Access Blocked | SurffyActionBlock |
302 (SERVERSIDE_IP_BLOCK) | IP Blocked | SurffyActionBlock |
303 (EXPRESS_NUMBER) | Bypass access | SurffyActionBypass |
499 (USER_CANCEL) |
When a visitor cancels their wait in the waiting room |
SurffyActionCancel |
500 | Unknown Network error | SurffyActionError |
기타 50x ~ 999 | Other errors | SurffyActionError |
1001 |
Device network disconnection (Mobile, Wi-fi, etc) |
SurffyActionBlock |
以下はDelegateの定義です。
Function Type | Name | Argument | Description |
---|---|---|---|
Delegate |
SurffyActionSuccess |
projectKey |
The project key used when entering ex) service_1 |
|
|
segmentKey |
The segment key used when entering ex) service_1 |
|
|
retcode |
Result code for the request at the time when delegate execution. |
Delegate |
SurffyActionError |
projectKey |
The project key used when entering ex) service_1 |
|
|
segmentKey |
The segment key used when entering ex) serKey_1234 |
|
|
retcode |
Result code for the request at the time when delegate execution. |
Delegate |
SurffyActionCancel |
projectKey |
The project key used when entering ex) service_1 |
|
|
segmentKey |
The segment key used when entering ex) serKey_1234 |
|
|
retcode |
Result code for the request at the time when delegate execution. |
Delegate |
SurffyActionBypass |
projectKey |
The project key used when entering ex) service_1 |
|
|
segmentKey |
The segment key used when entering ex) serKey_1234 |
|
|
retcode |
Result code for the request at the time when delegate execution. |
Delegate |
SurffyActionBlock |
projectKey |
The project key used when entering ex) service_1 |
|
|
segmentKey |
The segment key used when entering ex) serKey_1234 |
|
|
retcode |
Result code for the request at the time when delegate execution. |
Delegate |
SurffyCompleteSuccess |
projectKey |
The project key used when entering ex) service_1 |
|
|
segmentKey |
The segment key used when entering ex) serKey_1234 |
Delegate |
SurffyCompleteError |
projectKey |
The project key used when entering ex) service_1 |
|
|
segmentKey |
The segment key used when entering ex) serKey_1234 |
実際のコードでは下記のようにSurffyDelegateを継承してViewControllerインターフェースを宣言します。
必要に応じてViewController以外でも継承が可能です。
//ex> swift
import SurffyAgent
class ViewController: UIViewController, SurffyDelegate {
//
//
}
//ex> obj-c , ViewController.h
@import SurffyAgent;
@interface ViewController : UIViewController <SurffyDelegate>
SurffyDelegateを継承したViewControllerの実装体の中で下記のようにコールバック関数を実装します。
//ex> swift
class ViewController: UIViewController, SurffyDelegate {
func SurffyActionSuccess(projectKey: String, segmentKey: String, retcode: Int) {
print("SurffyActionSuccess called ",retcode)
//delegate executed when wait is success. retcode is 200
}
func SurffyActionBlock(projectKey: String, segmentKey: String, retcode: Int) {
print("SurffyActionBlock called ", retcode)
//delegate executed when blocked. retcode is 301 or 302
}
func SurffyActionError(projectKey: String?, segmentKey: String?, retcode: Int) {
print("SurffyActionError called ",retcode)
//delegate executed when error occurred. retcode is 0 or 500 or 501 ~ 999.
}
func SurffyActionBypass(projectKey: String, segmentKey: String, retcode: Int){
print("SurffyActionBypass called ",retcode)
//delegate executed when setting up a wait bypass. retcode is 300 or 303
}
func SurffyActionCancel(projectKey: String, segmentKey: String, retcode: Int, cancelTargetAddr: String) {
print("SurffyActionCancel called ", retcode)
//delegate run on cancel wait. retcode is 499
}
func SurffyCompleteSuccess(projectKey: String, segmentKey: String) {
print("SurffyCompleteSuccess called")
//delegate executed when retrieval key is successful.
}
func SurffyCompleteError(projectKey: String, segmentKey: String) {
print("SurffyActionComplete error called")
//delegate executed when retrieval key is failed.
}
}
//ex> obj-c, ViewController.m
@interface ViewController ()
@end
@implementation ViewController
- (void)SurffyActionSuccessWithProjectKey:(NSString * _Nonnull)projectKey segmentKey:(NSString * _Nonnull)segmentKey retcode:(NSInteger)retcode {
//delegate executed when wait is success. retcode is 200
}
- (void)SurffyActionBlockWithProjectKey:(NSString * _Nonnull)projectKey segmentKey:(NSString * _Nonnull)segmentKey retcode:(NSInteger)retcode {
//delegate executed when blocked. retcode is 301 or 302
}
- (void)SurffyActionBypassWithProjectKey:(NSString * _Nonnull)projectKey segmentKey:(NSString * _Nonnull)segmentKey retcode:(NSInteger)retcode {
//delegate executed when setting up a wait bypass. retcode is 300 or 303
}
- (void)SurffyActionCancelWithProjectKey:(NSString * _Nonnull)projectKey segmentKey:(NSString * _Nonnull)segmentKey retcode:(NSInteger)retcode cancelTargetAddr:(NSString * _Nonnull)cancelTargetAddr {
//delegate run on cancel wait. retcode is 499
}
- (void)SurffyActionErrorWithProjectKey:(NSString * _Nullable)projectKey segmentKey:(NSString * _Nullable)segmentKey retcode:(NSInteger)retcode {
//delegate executed when error occurred. retcode is 0 or 500 or 501 ~ 999.
}
- (void)SurffyCompleteErrorWithProjectKey:(NSString * _Nonnull)projectKey segmentKey:(NSString * _Nonnull)segmentKey {
//delegate executed when retrieval key is successful.
}
- (void)SurffyCompleteSuccessWithProjectKey:(NSString * _Nonnull)projectKey segmentKey:(NSString * _Nonnull)segmentKey {
//delegate executed when retrieval key is failed.
}
@end
エントリーに成功した時に呼び出されるコールバックを実装する方法
進入に成功した場合二つの実装をします。
- ターゲットページに入るコード
- 完了処理関数を呼び出して発行されたキーをNetFUNNELサーバーに返却する過程を実行します。
完了処理関数
Function type | Name | Argument | Description |
---|---|---|---|
Completion function for basic control |
NFStop |
projectKey |
The project key can be found in the NetFUNNEL console. ex) service_1 |
|
|
segmentKey |
The segment key can be found in the NetFUNNEL console when creating a segment. ex) segKey_1234 |
Completion function for path control |
NFStopSection |
projectKey |
The project key can be found in the NetFUNNEL console. ex) service_1 |
|
|
segmentKey |
The segment key can be found in the NetFUNNEL console when creating a segment. ex) segKey_1234 |
以下は、SurffyActionSuccess Delegate関数を実装したサンプルコードです。
//ex> swift
let SRM = SurffyReqManager.shared
SRM.NFStart(projectKey: "projectKey", segmentKey: "segmentKey")
...
func SurffyActionSuccess(projectKey: String, segmentKey: String, retcode: Int) {
/*
Action after access the target page
*/
// Retrieve the waiting key
let req = SurffyReqManager.shared
req.NFStop(projectKey: "projectKey", segmentKey: "segmentKey">)
}
//ex> obj-c
SurffyReqManager * req = [SurffyReqManager shared];
[req NFStartWithProjectKey: @"projectKey" segmentKey:@"segmentKey"];
...
- (void)SurffyActionSuccessWithProjectKey:(NSString * _Nonnull)projectKey segmentKey:(NSString * _Nonnull)segmentKey retcode:(NSInteger)retcode {
/*
Action after access the target page
*/
// Retrieve the waiting key
[req NFStopWithProjectKey: @"projectKey" segmentKey:@"segmentKey"];
}
アクセスまたは待機エラー発生時のコールバックの実装
NetFunnelを使用するためのキューイング中、または待機中にエラーが発生した場合、NetFunnelサーバーがダウンしている、ネットワーク接続の問題などが考えられます。
エラーのリターンコードに応じて、様々なフローを実装できます。
- エラー時にエントリーが許可された場合、エントリー成功などのロジックを実装する。
- エラーでエントリーがブロックされた場合、エントリーがブロックされたなどのロジックを実装する。
- その他、エラーに応じたロジックを実装する。
アクセスがブロックされた場合や失敗した場合は、上記のようなロジックを実装すればよく、アクセスが成功した場合とは異なり、別途完了処理関数を呼び出す必要はありません。
以下はSurffyActionError Delegate関数を実装したサンプルコードです。
//ex> swift
let SRM = SurffyReqManager.shared
SRM.NFStart(projectKey: "projectKey", segmentKey: "segmentKey")
...
func SurffyActionError(projectKey: String, segmentKey: String, retcode: Int) {
/*
1. Implement logic like SurffyActionSuccess when granting access.
2. implement logic like SurffyActionBlock when blocking access
3. implement other logic
*/
}
//ex> obj-c
SurffyReqManager * req = [SurffyReqManager shared];
[req NFStartWithProjectKey: @"projectKey" segmentKey:@"segmentKey"];
...
- (void)SurffyActionErrorWithProjectKey:(NSString * _Nonnull)projectKey segmentKey:(NSString * _Nonnull)segmentKey retcode:(NSInteger)retcode {
/*
1. Implement logic like SurffyActionSuccess when granting access.
2. implement logic like SurffyActionBlock when blocking access
3. implement other logic
*/
}
待機がバイパスされた場合に呼び出されるコールバックを実装する方法
コンソールページでネットファーネルを使用していないことをチェックすると、待機リクエストは300, 303のリターンコードを受け取り、SurffyActionBypassが実行されます。
待機をバイパスする場合は下記のようなロジックなどを実装することができます。
- 進入を許可する時、進入成功のようなロジックを実装する。
- その他その他のロジックを実装
以下は待機バイパス時に実行されるSurffyActionBypass Delegate関数を実装したサンプルコードです。
//ex> swift
let SRM = SurffyReqManager.shared
SRM.NFStart(projectKey: "projectKey", segmentKey: "segmentKey")
...
func SurffyActionBypass(projectKey: String, segmentKey: String, retcode: Int) {
/*
1. Implement logic such as access success when granting access
2. Implement other miscellaneous logic
*/
}
//ex> obj-c
SurffyReqManager * req = [SurffyReqManager shared];
[req NFStartWithProjectKey: @"projectKey" segmentKey:@"segmentKey"];
...
- (void)SurffyActionBypassWithProjectKey:(NSString * _Nonnull)projectKey segmentKey:(NSString * _Nonnull)segmentKey retcode:(NSInteger)retcode {
/*
1. Implement logic such as access success when granting access
2. Implement other miscellaneous logic
*/
}
待機がキャンセルされた場合に呼び出されるコールバックを実装する部屋
訪問者が仮想待合室で待機中に待機キャンセルボタンを押した場合、待機キャンセルコールバックが呼び出されることがあります。このような状況で訪問者のユーザーエクスペリエンスを向上させる目的で、通常下記のようなロジックを実装することができます。
- 現在のページに留まりたい場合:ロジックを実装する必要はありません。
- 待機がキャンセルされたことを表示するモーダルウィンドウを別途表示するロジックを実装します。
- 待機がキャンセルされたことを表示する特定のページに移動させるロジックを実装します。
ロギングロジックを実装 - 待機がキャンセルされる場合には、上記のようなロジックを実装することができ、エントリー成功ケースと違って、別途の完了処理関数の呼び出しを必要としません。
以下は待機キャンセルボタンが押された時に呼び出されるSurffyActionCancelコールバック関数を実装したサンプルコードです。
//ex> swift
let SRM = SurffyReqManager.shared
SRM.NFStart(projectKey: "projectKey", segmentKey: "segmentKey")
...
func SurffyActionCancel(projectKey: String, segmentKey: String, retcode: Int) {
/*
1. No need to implement logic if you want to stay on the current page
2. implement logic to open a separate modal window to indicate that the wait has been canceled
3. Implement logic to take the visitor to a special page that indicates the wait has been canceled.
4. Implement logging logic
*/
}
//ex> obj-c
SurffyReqManager * req = [SurffyReqManager shared];
[req NFStartWithProjectKey: @"projectKey" segmentKey:@"segmentKey"];
...
- (void)SurffyActionCancelWithProjectKey:(NSString * _Nonnull)projectKey segmentKey:(NSString * _Nonnull)segmentKey retcode:(NSInteger)retcode {
/*
1. No need to implement logic if you want to stay on the current page
2. implement logic to open a separate modal window to indicate that the wait has been canceled
3. Implement logic to take the visitor to a special page that indicates the wait has been canceled.
4. Implement logging logic
*/
}
コメント
0件のコメント
記事コメントは受け付けていません。