넷퍼넬 iOS 에이전트는 어플리케이션 내에서 출력되는 Web-View에서 발생하는 트래픽을 제어하여 서비스 인프라를 보호하고 방문자에게 원활한 사용자 경험을 제공합니다.
- 서비스 란? : 넷퍼넬과 연동하여 트래픽 제어를 걸기 위한 대상 웹 사이트(URL)를 의미합니다.
에이전트 요구사항
- iOS 12 이상
- Storyboard(obj-c, swift), Swift UI 에서 사용가능
에이전트 적용 방법
에이전트 파일 적용
에이전트를 사용하려는 클래스 상단에 SurffyAgent 를 import 합니다.
설정 정보 초기화
에이전트를 적용하는 첫번째 과정은 별도로 제공해드리는 초기화 함수를 사용하여 NetFUNNEL 에이전트의 설정 정보를 초기화하는 과정입니다.
초기화 과정에 사용되는 함수는 다음과 같습니다.
초기화 함수
함수 종류 | 함수명 | 인자 | 설명 |
초기화 함수 | setConfig | tenantURL | NF 접속 URL |
projectDetailURL | 설정파일을 가져올 URL | ||
eumURL | eum data 수집 URL | ||
delegate | NetFUNNEL delegate 선언 view 위치 | ||
oneTimeCallback | setConfig가 성공적으로 설정파일을 로드한 후, 1회성으로 동작하는 콜백 함수 | ||
초기화 체크 함수 | checkConfigSuccess | N/A | 정상 로드인 경우 true 반환, 비정상 로드인 경우 false 반환 |
setConfig 함수를 viewDidLoad() 함수 override 위치에 아래와 같이 코드를 추가합니다.
//ex> swift
let agent = NetFunnelAgent.shared
agent.setConfig(tenantURL: "NetFUNNEL 콘솔 페이지에서 안내되는 테넌트 주소",
projectDetailURL: "NetFUNNEL 콘솔 페이지에서 안내되는 설정파일 로드 주소",
eumURL : "NetFUNNEL 콘솔 페이지에서 안내되는 EUM 주소",
delegate: self,
oneTimeCallback: "setConfig 직후, NF 호출 함수를 사용하면 설정파일이
로드되기 전에 함수가 불려서 NF가 작동 안 될 수도 있습니다.
setConfig 직후 1회에 한하여 호출이 보장되는 영역이나 함수는
여기 oneTimeCallback에 넣거나 콜백으로 추가하면 호출이 보장됩니다.")
//ex> obj-c
NetFunnelAgent *agent = [NetFunnelAgent shared];
[agent setConfigWithTenantURL:@"NetFUNNEL 콘솔 페이지에서 안내되는 테넌트 주소"
projectDetailURL:@"NetFUNNEL 콘솔 페이지에서 안내되는 설정파일 로드 주소"
eumURL:@"NetFUNNEL 콘솔 페이지에서 안내되는 EUM 주소"
delegate:self
oneTimeCallback:^{
/*
setConfig 직후, NF 호출 함수를 사용하면 설정파일이
로드되기 전에 함수가 불려서 NF가 작동 안 될 수도 있습니다.
setConfig 직후 1회에 한하여 호출이 보장되는 영역이나 함수는
여기 oneTimeCallback에 넣거나 콜백으로 추가하면 호출이 보장됩니다.
*/
}
];
트래픽 제어 설정
기본 제어
가상 대기실을 노출하여 트래픽 대기를 적용하고 싶은 페이지(뷰 혹은 액티비티)의 특정 부분에서 대기 적용하기 위해서는 별도로 제공해드리는 대기 시작 함수를 사용하여 가상 대기실을 적용할 수 있습니다.
일반 대기 시작 과정에 사용되는 함수는 다음과 같습니다.
기본 제어 시작 함수
함수 종류 | 함수명 | 인자 | 설명 |
기본 제어 대기 시작 함수 | NFStart | projectKey |
NF 콘솔에 출력된 project 키 값 ex) service_1 |
segmentKey |
세그먼트 등록시 NF 콘솔에 출력된 segment 키 값 ex) segKey_1234 |
SurffyReqManager를 shared 로 싱글톤 객체를 호출 후, 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"];
구간 제어
가상 대기실을 노출하여 트래픽 대기를 적용하고 싶은 페이지(뷰 혹은 액티비티)의 특정 부분에서 대기 적용하기 위해서는 별도로 제공해드리는 대기 시작 함수를 사용하여 가상 대기실을 적용할 수 있습니다.
이때, 특정 페이지의 진입과 끝 사이에 대기를 걸고 싶은 경우 구간 대기를 사용할 수 있습니다.
ex> 이벤트 페이지 진입 - 진입 후 상품 구매, 로그인 - 로그아웃 등
SurffyReqManager를 shared 로 싱글톤 객체를 호출후, NFStartSection 함수를 사용합니다. NFStopSection 함수를 사용하여 대기 시작 시점에 제공된 키를 회수 합니다.
구간 제어 시작 함수
함수 종류 | 함수명 | 인자 | 설명 |
기본 제어 대기 시작 함수 | NFStartSection | projectKey |
NF 콘솔에 출력된 project 키 값 ex) service_1 |
segmentKey |
세그먼트 등록시 NF 콘솔에 출력된 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 | 설명 | Delegate |
0 | 서비스 진입 요청시 네트워크 에러 | SurffyActionError |
200 (SUCCESS) | 서비스 정상 연결 | SurffyActionSuccess |
201 (CONTINUE) | 서비스 대기 (대기열 진입) | |
300 (BYPASS) | 서비스 우회 | SurffyActionBypass |
301 (SERVERSIDE_BLOCK) | 서비스 차단 | SurffyActionBlock |
302 (SERVERSIDE_IP_BLOCK) | 서비스 차단 | SurffyActionBlock |
303 (EXPRESS_NUMBER) | 서비스 우회 | SurffyActionBypass |
499 (USER_CANCEL) | 사용자가 대기창에서 취소했을 경우 | SurffyActionCancel |
500 | 네트워크 | SurffyActionError |
기타 50x ~ 999 | 기타 에러 | SurffyActionError |
1001 |
디바이스 네트워크 단절 (모바일 네트워크, WiFi) |
SurffyActionBlock |
다음은 Delegate의 정의입니다.
함수종류 | 함수명 | 인자 | 설명 |
---|---|---|---|
Delegate |
SurffyActionSuccess |
projectKey |
진입 시 사용한 project 키 값 ex) service_1 |
|
|
segmentKey |
진입 시 사용한 segment 키 값 ex) serKey_1234 |
|
|
retcode |
delegate 실행 시점의 요청의 결과 코드 |
Delegate |
SurffyActionError |
projectKey |
진입 시 사용한 project 키 값 ex) service_1 |
|
|
segmentKey |
진입 시 사용한 segment 키 값 ex) serKey_1234 |
|
|
retcode |
delegate 실행 시점의 요청의 결과 코드 |
Delegate |
SurffyActionCancel |
projectKey |
진입 시 사용한 project 키 값 ex) service_1 |
|
|
segmentKey |
진입 시 사용한 segment 키 값 ex) serKey_1234 |
|
|
retcode |
delegate 실행 시점의 요청의 결과 코드 |
Delegate |
SurffyActionBypass |
projectKey |
진입 시 사용한 project 키 값 ex) service_1 |
|
|
segmentKey |
진입 시 사용한 segment 키 값 ex) serKey_1234 |
|
|
retcode |
delegate 실행 시점의 요청의 결과 코드 |
Delegate |
SurffyActionBlock |
projectKey |
진입 시 사용한 project 키 값 ex) service_1 |
|
|
segmentKey |
진입 시 사용한 segment 키 값 ex) serKey_1234 |
|
|
retcode |
delegate 실행 시점의 요청의 결과 코드 |
Delegate |
SurffyCompleteSuccess |
projectKey |
진입 시 사용한 project 키 값 ex) service_1 |
|
|
segmentKey |
진입 시 사용한 segment 키 값 ex) serKey_1234 |
Delegate |
SurffyCompleteError |
projectKey |
진입 시 사용한 project 키 값 ex) service_1 |
|
|
segmentKey |
진입 시 사용한 segment 키 값 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. retcode 는 200
}
func SurffyActionBlock(projectKey: String, segmentKey: String, retcode: Int) {
print("SurffyActionBlock called ", retcode)
//차단시에 실행되는 delegate. retcode 는 301 혹은 302
}
func SurffyActionError(projectKey: String?, segmentKey: String?, retcode: Int) {
print("SurffyActionError called ",retcode)
//에러 발생시에 실행되는 delegate. retcode 는 0, 500, 501~999.
}
func SurffyActionBypass(projectKey: String, segmentKey: String, retcode: Int){
print("SurffyActionBypass called ",retcode)
//대기 우회 설정시에 실행되는 delegate. retcode 는 300, 303
}
func SurffyActionCancel(projectKey: String, segmentKey: String, retcode: Int, cancelTargetAddr: String) {
print("SurffyActionCancel called ", retcode)
//대기 취소시에 실행되는 delegate. retcode 는 499
}
func SurffyCompleteSuccess(projectKey: String, segmentKey: String) {
print("SurffyCompleteSuccess called")
//키 반납 성공시에 실행되는 delegate.
}
func SurffyCompleteError(projectKey: String, segmentKey: String) {
print("SurffyActionComplete error called")
//키 반납 실패시에 실행되는 delegate.
}
}
//ex> obj-c, ViewController.m
@interface ViewController ()
@end
@implementation ViewController
- (void)SurffyActionBlockWithProjectKey:(NSString * _Nonnull)projectKey segmentKey:(NSString * _Nonnull)segmentKey retcode:(NSInteger)retcode {
//차단시에 실행되는 delegate. retcode 는 301 혹은 302
}
- (void)SurffyActionBypassWithProjectKey:(NSString * _Nonnull)projectKey segmentKey:(NSString * _Nonnull)segmentKey retcode:(NSInteger)retcode {
//대기 우회 설정시에 실행되는 delegate. retcode 는 300, 303
}
- (void)SurffyActionCancelWithProjectKey:(NSString * _Nonnull)projectKey segmentKey:(NSString * _Nonnull)segmentKey retcode:(NSInteger)retcode cancelTargetAddr:(NSString * _Nonnull)cancelTargetAddr {
//대기 취소시에 실행되는 delegate. retcode 는 499
}
- (void)SurffyActionErrorWithProjectKey:(NSString * _Nullable)projectKey segmentKey:(NSString * _Nullable)segmentKey retcode:(NSInteger)retcode {
//에러 발생시에 실행되는 delegate. retcode 는 0, 500, 501~999
}
- (void)SurffyActionSuccessWithProjectKey:(NSString * _Nonnull)projectKey segmentKey:(NSString * _Nonnull)segmentKey retcode:(NSInteger)retcode {
//대기 성공시에 실행되는 delegate. retcode 는 200
}
- (void)SurffyCompleteErrorWithProjectKey:(NSString * _Nonnull)projectKey segmentKey:(NSString * _Nonnull)segmentKey {
//키 반납 성공시에 실행되는 delegate.
}
- (void)SurffyCompleteSuccessWithProjectKey:(NSString * _Nonnull)projectKey segmentKey:(NSString * _Nonnull)segmentKey {
//키 반납 실패시에 실행되는 delegate.
}
@end
진입에 성공할 경우 호출되는 콜백을 구현
진입에 성공할 경우 두 가지 구현을 합니다.
- 타겟 페이지로 진입하는 코드
- 완료 처리 함수를 호출하여 발급된 키를 NetFUNNEL 서버에 반납하는 과정을 수행
완료 처리 함수
함수 종류 | 함수명 | 인자 | 설명 |
---|---|---|---|
기본 제어 완료 처리 함수 |
NFStop |
projectKey |
NF 콘솔에 출력된 project 키 값 ex) service_1 |
|
|
segmentKey |
세그먼트 등록시 NF 콘솔에 출력된 segment 키 값 ex) serKey_1234 |
구간 제어 완료 처리 함수 |
NFStopSection |
projectKey |
NF 콘솔에 출력된 project 키 값 ex) service_1 |
|
|
segmentKey |
세그먼트 등록시 NF 콘솔에 출력된 segment 키 값 ex) serKey_1234 |
아래는 SurffyActionSuccess Delegate 함수를 구현한 예시 코드입니다.
//ex> swift
let SRM = SurffyReqManager.shared
SRM.NFStart(projectKey: "projectKey", segmentKey: "segmentKey")
...
func SurffyActionSuccess(projectKey: String, segmentKey: String, retcode: Int) {
/*
타겟 페이지 진입 후 액션
*/
// 대기 키 반납
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 {
/*
타겟 페이지 진입 후 액션
*/
// 대기 키 반납
[req NFStopWithProjectKey: @"projectKey" segmentKey:@"segmentKey"];
}
진입이 차단되는 경우 호출되는 콜백을 구현 할 때
진입이 차단되는 경우는 보통 매크로 성의 잦은 요청이나 잘못된 키를 통해 악의적으로 요청을 하는 경우 입니다.
이 같은 시나리오에서는 보통 고객의 유저 경험을 증대 시키기 위한 목적으로 보통 아래와 같은 로직을 구현하실 수 있습니다.
- 현재 페이지에 머무르고 싶을 경우 : 로직 구현 필요 없음
- 진입이 차단되었음을 표시하는 모달 창을 별도로 띄우는 로직을 구현
- 진입이 차단되었음을 표시하는 특정 페이지로 이동을 시키는 로직을 구현
- 로깅 로직을 구현
진입이 차단 혹은 실패 되는 경우에는 위와 같은 로직을 구현하실 수 있으며, 진입 성공 케이스와 다르게 별도의 완료 처리 함수 호출을 필요로 하지 않습니다.
아래는 SurffyActionBlock Delegate 함수를 구현한 예시 코드입니다.
//ex> swift
let SRM = SurffyReqManager.shared
SRM.NFStart(projectKey: "projectKey", segmentKey: "segmentKey")
...
func SurffyActionBlock(projectKey: String, segmentKey: String, retcode: Int) {
/*
1. 현재 페이지에 머무르고 싶을 경우에는 아무 로직도 구현할 필요가 없음
2. 진입이 차단되었음을 표시하는 모달 창을 별도로 띄우는 로직을 구현
3. 진입이 차단되었음을 표시하는 특정 페이지로 이동을 시키는 로직을 구현
4. 로깅 로직을 구현
*/
}
//ex> obj-c
SurffyReqManager * req = [SurffyReqManager shared];
[req NFStartWithProjectKey: @"projectKey" segmentKey:@"segmentKey"];
...
- (void)SurffyActionBlockWithProjectKey:(NSString * _Nonnull)projectKey segmentKey:(NSString * _Nonnull)segmentKey retcode:(NSInteger)retcode {
/*
1. 현재 페이지에 머무르고 싶을 경우에는 아무 로직도 구현할 필요가 없음
2. 진입이 차단되었음을 표시하는 모달 창을 별도로 띄우는 로직을 구현
3. 진입이 차단되었음을 표시하는 특정 페이지로 이동을 시키는 로직을 구현
4. 로깅 로직을 구현
*/
}
진입/대기중 에러가 나는 경우 호출되는 콜백을 구현
넷퍼넬 사용을 위해 대기열에 진입 중, 혹은 대기 중 에러가 나는 경우는 넷퍼넬 서버 다운, 네트워크 연결 이상 등의 원인이 있습니다.
에러의 리턴 코드에 따라, 다양한 흐름을 구현할 수 있습니다.
- 에러 발생 시 진입을 허가 할 때 진입 성공과 같은 로직을 구현
- 에러 발생 시 진입을 차단 할 때 진입 차단과 같은 로직을 구현
- 그 외 에러에 따른 기타 로직을 구현
진입이 차단 혹은 실패되는 경우에는 위와 같은 로직을 구현하실 수 있으며, 진입 성공 케이스와 다르게 별도의 완료 처리 함수 호출을 필요로 하지 않습니다.
아래는 SurffyActionError Delegate 함수를 구현한 예시 코드입니다.
//ex> swift
let SRM = SurffyReqManager.shared
SRM.NFStart(projectKey: "projectKey", segmentKey: "segmentKey")
...
func SurffyActionError(projectKey: String, segmentKey: String, retcode: Int) {
/*
1. 진입 허가 시에는 SurffyActionSucess와 같은 로직을 구현
2. 진입 차단 시에는 SurffyActionBlock과 같은 로직을 구현
3. 그외 로직을 구현
*/
}
//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. 진입 허가 시에는 SurffyActionSucessWithProjectKey와 같은 로직을 구현
2. 진입 차단 시에는 SurffyActionBlockWithProjectKey와 같은 로직을 구현
3. 그외 로직을 구현
*/
}
대기가 우회되는 경우 호출되는 콜백을 구현
콘솔페이지에서 넷퍼넬을 사용하지 않는 걸로 체크 시, 대기 요청은 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. 진입을 허가 할 때 진입 성공과 같은 로직을 구현
2. 그 외 기타 로직을 구현
*/
}
//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. 진입을 허가 할 때 진입 성공과 같은 로직을 구현
2. 그 외 기타 로직을 구현
*/
}
대기가 취소될 경우 호출되는 콜백을 구현
방문자가 가상 대기실에서 대기 중에 대기 취소 버튼을 누르는 경우 대기 취소 콜백이 호출될 수 있습니다. 이 같은 상황에서 방문자의 유저 경험을 증대 시키기 위한 목적으로 보통 아래와 같은 로직을 구현하실 수 있습니다.
- 현재 페이지에 머무르고 싶을 경우 : 로직 구현 필요 없음
- 대기가 취소되었음을 표시하는 모달 창을 별도로 띄우는 로직을 구현
- 대기가 취소되었음을 표시하는 특정 페이지로 이동을 시키는 로직을 구현
- 로깅 로직을 구현
대기가 취소되는 경우에는 위와 같은 로직을 구현하실 수 있으며, 진입 성공 케이스와 다르게 별도의 완료 처리 함수 호출을 필요로 하지 않습니다.
아래는 대기 취소 버튼이 눌렸을 때 호출되는 SurffyActionCancel 콜백 함수를 구현한 예시 코드입니다.
//ex> swift
let SRM = SurffyReqManager.shared
SRM.NFStart(projectKey: "projectKey", segmentKey: "segmentKey")
...
func SurffyActionCancel(projectKey: String, segmentKey: String, retcode: Int) {
/*
1. 현재 페이지에 머무르고 싶을 경우에는 아무 로직도 구현할 필요가 없음
2. 대기가 취소되었음을 표시하는 모달 창을 별도로 띄우는 로직을 구현
3. 대기가 취소되었음을 표시하는 특정 페이지로 이동을 시키는 로직을 구현
4. 로깅 로직을 구현
*/
}
//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. 현재 페이지에 머무르고 싶을 경우에는 아무 로직도 구현할 필요가 없음
2. 대기가 취소되었음을 표시하는 모달 창을 별도로 띄우는 로직을 구현
3. 대기가 취소되었음을 표시하는 특정 페이지로 이동을 시키는 로직을 구현
4. 로깅 로직을 구현
*/
}
댓글
댓글 0개
이 문서에는 댓글을 달 수 없습니다.