Install the NetFUNNEL iOS Agent

The NetFUNNEL iOS Agent controls the traffic of web views output from within your application, protecting your service infrastructure and ensuring a stable user experience for your visitors.

• Service: A target website (URL) to control traffic in conjunction with NetFUNNEL.

Requirements

• iOS 12 and above
• Available in Storyboard(obj-c, swift) and Swift UI

How to apply the NetFUNNEL iOS Agent

Apply the agent file

Import the SurffyAgent on the upper class where you want to use the agent.

Initialize the setting informations

To start, it is recommended to utilize the provided initialization function to configure the agent's settings.

The following are the initialization functions:

Initialization functions

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

Add the setConfig code at the override point in viewDidLoad() like the following

//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.
*/
}
];

Tip 1. To confirm that your settings have loaded correctly, use this code.

//ex> swift
var check = agent.checkConfigSuccess()

//ex> obj-c
bool check = [agent checkConfigSuccess];

Tip 2. To use NetFUNNEL immediately upon starting your application, use this code.

To initiate NetFUNNEL upon application launch, we recommend adding a Wait-Start function inside the oneTimeCallback function, which is a callback function that runs once per year after setConfig has successfully loaded the configuration file, as shown below.

//ex> swift
func actionAfterSetting(){
var req = SurffyReqManager.shared
req.NFStart(projectKey: "projectKey", segmentKey: "segmentKey")
}

//ex> obc-c
- (void)actionAfterSetting {
/*
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.
*/

SurffyReqManager * req = [SurffyReqManager shared];
[req NFStartWithProjectKey: @"projectKey" segmentKey:@"segmentKey"];
// Additional UI Process etc.
}

Traffic Control Settings

Basic Control

To apply a virtual waiting room to a specific part of a page (view or activity) that requires traffic management, use the Wait-Start function provided separately.

Check out the following functions.

Wait-Start function for basic control

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

After calling the SurffyReqManager shared singleton object, use the NFStart function.

To retrieve the key given at the beginning of the waiting period, utilize the NFStop function.

//ex> swift
var req = SurffyReqManager.shared
req.NFStart(projectKey: "projectKey", segmentKey: "segmentKey")

//ex> objc-c
SurffyReqManager * req = [SurffyReqManager shared];
[req NFStartWithProjectKey: @"projectKey" segmentKey:@"segmentKey"];

Path Control

To apply a virtual waiting room to a specific part of a page (view or activity) that requires traffic management, use the Wait-Start function provided separately.

To control access to a page with an endpoint, use path control.

• e.g.) Access the event page, purchase a product while signed in, and then sign out.

After calling the SurffyReqManager shared singleton object, use the NFStartSection function.

To retrieve the key given at the beginning of the waiting period, utilize the NFStopSection function.

Wait-Start function for path control

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"];

Tip. Testing the Display of Your Virtual Waiting Room

To verify the exposure of the virtual waiting room, set the limited inflow to 0 in the NetFUNNEL console. This means that no traffic will be allowed into the service. Once you have confirmed that the project key and segment key have the limited inflow set to 0, call the Wait-Start function with those key values to immediately expose the virtual waiting room.

Implement the Delegate

During the waiting period, various callback functions are executed. By utilizing different types of callback functions, you can implement scenarios for accessing, waiting, blocking, and canceling.

Here are the return code information.

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

Here are the Delegate inforomation.

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

Declare the ViewController interface in the actual code by inheriting from SurffyDelegate.

It is possible to inherit from other places besides ViewController if necessary.

//ex> swift
import SurffyAgent
class ViewController: UIViewController, SurffyDelegate {
//
//
}

//ex> obj-c , ViewController.h
@import SurffyAgent;
@interface ViewController : UIViewController <SurffyDelegate>

Implement the callback functions as shown below inside the ViewController implementation that inherits from SurffyDelegate.

//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

Implement the callback on successful access

In the case of successful access, you need to implement two sets.

1. Code for entering the target page
2. Process of retrieving the issued key to the NetFUNNEL server by calling the completion function

Completion functions

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

Here are the sample codes that implement SurffyActionSuccess Delegate function.

//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"];
}

Implement callback when an access or wait error occurs

If you receive an error while queuing to use NetFunnel or while waiting, it could be due to the NetFunnel server being down, network connection problems, etc.

Depending on the return code of the error, vaious flows can be implemented.

1. Implement logic such as successful entry if entry is allowed on error.
2. Implement logic such as entry blocked if entry is blocked on error.
3. Implement other logic based on the error.

In the case of blocked or failed access, you can implement logic like the above, and unlike in the case of successful access, you don't need to call a separate completion handling function.

Below is sample code that implements the SurffyActionError Delegate function.

//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
*/
}

Implement a callback to be called when the wait is bypassed

If the console page is checked to not use a netfunnel, the waiting request will receive a 300 or 303 return code and SurffyActionBypass will be executed.

When bypassing the wait, you can implement logic like the following

1. Implement logic such as access success if access is granted
2. Implement other miscellaneous logic

Below is sample code that implements the SurffyActionBypass Delegate function that is executed when the wait is bypassed.

//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
*/
}

Implement a Callback that is Called when a Wait is Cancelled

If a visitor clicks the Cancel Wait button while waiting in a virtual waiting room, the Cancel Wait callback would be triggered. In this situation, you can usually implement the following logic to improve the visitor's experience.

1. If they want to stay on the current page: no logic implementation needed.
2. Implement logic to display a separate modal window indicating that the wait has been canceled.
3. Implement logic to navigate to a specific page indicating that the wait has been canceled.
4. Implement logging logic

In the case of a canceled wait, you can implement any of the above logic, and unlike the case of an entry success, it doesn't require a separate function call to handle the completion.

Below is sample code that implements the SurffyActionCancel callback function that is called when the Cancel Wait button is pressed.

//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
*/
}

Tip. To resume waiting with a separate modal window when the Cancel Wait button is pressed

//ex> swift
func SurffyActionCancel(projectKey: String, segmentKey: String, retcode: Int, cancelTargetAddr: String) {

let alert = UIAlertController(title: "Are you sure you want to close the app?", message: "", preferredStyle: UIAlertController.Style.alert)
let cancle = UIAlertAction(title: "NF re-entry", style: .default, handler: {
action in
let SRM = SurffyReqManager.shared
SRM.NFStart(projectKey: self.proKey.text ?? "", segmentKey: self.segKey.text ?? "")
})
//Make a confirm button
let ok = UIAlertAction(title: "Close", style: .destructive, handler: {
action in
//Perform a specific function
})
alert.addAction(cancle)
//Add a confirm button on the waring window
alert.addAction(ok)
present(alert,animated: true,completion: nil)

}

//ex> obj-c ViewController.m
@interface ViewController ()

@end

@implementation ViewController

- (void)SurffyActionCancelWithProjectKey:(NSString * _Nonnull)projectKey segmentKey:(NSString * _Nonnull)segmentKey retcode:(NSInteger)retcode cancelTargetAddr:(NSString * _Nonnull)cancelTargetAddr {
// Trigged when user canceld NetFUNNEL request
UIAlertController *alert = [UIAlertController alertControllerWithTitle:@"Are you sure you want to close the app?"
message:@"" preferredStyle:UIAlertControllerStyleAlert];

UIAlertAction *cancel = [UIAlertAction actionWithTitle:@"NF 재진입"
style:UIAlertActionStyleDefault
handler:^(UIAlertAction *action) {
SurffyReqManager *SRM = [SurffyReqManager shared];
[SRM NFStartWithProjectKey:self.proKey.text segmentKey:self.segKey.text];
}];

UIAlertAction *ok = [UIAlertAction actionWithTitle:@"종료"
style:UIAlertActionStyleDestructive
handler:^(UIAlertAction *action) {
// Perform a specific function
}];

[alert addAction:cancel];
[alert addAction:ok];
[self presentViewController:alert animated:YES completion:nil];
}

@end