documentation
NetFUNNEL
iOS 에이전트

iOS Agent v4.1.1

NetFUNNEL 에이전트는 NetFUNNEL 서버와 통신하기 위한 일종의 NetFUNNEL 전용 클라이언트 입니다. 사용자는 적용하고자 하는 클라이언트 어플리케이션 코드에 에이전트에서 제공하는 다양한 함수들을 적용, 구현하여 가상 대기실을 적용할 수 있습니다.

⭐️ 에이전트 요구 사항 : iOS 12 이상 / Storyboard(obj-c, swift), Swift UI 에서 사용가능

iOS Agent 동작 흐름도

📌 기본 제어 흐름도
ios에이전트동작흐름도
📌 구간 제어 흐름도
ios에이전트동작흐름도

NetFUNNEL 에이전트는 크게 다음과 같은 동작 흐름을 가지고 있습니다.

1. 대기 전
  • 대기를 하기 전에는 설정정보 초기화를 진행합니다. 이 과정은 NetFUNNEL 서버로부터 설정 정보를 Fetch하여 에이전트가 해당 정보들을 기반으로 객체들을 초기화하는 과정입니다.
  • 별도로 제공해드리는 초기화 함수를 사용하여 NetFUNNEL 에이전트의 설정 정보를 초기화 하세요.
2. 대기 중
  • 가상 대기실을 노출하여 트래픽 대기를 적용하고 싶은 페이지(뷰 혹은 액티비티)의 특정 부분에서 대기를 하는 과정입니다.
  • 별도로 제공해드리는 대기 시작 함수를 사용하여 가상 대기실을 적용하세요.
3. 대기 후
  • 대기가 종료된 이후의 과정입니다. 사용자가 대기가 종료되는 이유는 진입 성공, 진입 실패, 대기 취소이렇게 3가지 경우가 있습니다.
  • 별도로 제공해드리는 delegate 함수와 완료 처리 함수를 사용하여 대기 종료 후 로직을 구현하세요.

에이전트 적용 방법

Step 1. 에이전트 파일 적용

에이전트를 사용하려는 클래스 상단에 SurffyAgent 를 import 합니다.

ios에이전트

Step 2. 설정 정보 초기화

에이전트를 적용하는 첫번째 과정은 별도로 제공해드리는 초기화 함수를 사용하여 NetFUNNEL 에이전트의 설정 정보를 초기화하는 과정입니다. 버전은 아래의 변수로 참조 가능합니다.

변수 종류변수명설명
빌드 버전 확인 변수NetFunnelVersion넷퍼넬 에이전트 파일의 버전

초기화 과정에 사용되는 함수는 다음과 같습니다.

함수 종류함수명인자설명
초기화 함수setConfigtenantURLNF 접속 URL
projectDetailURL설정파일을 가져올 URL
eumURLeum data 수집 URL
delegateNetFunnel delegate 선언 view 위치
oneTimeCallbackNetFUNNEL delegate 선언 view 위치
projectDetailURLsetConfig가 성공적으로 설정파일을 로드한 후, 1회성으로 동작하는 콜백 함수
초기화 체크 함수checkConfigSuccessN/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에 넣거나 콜백으로 추가하면 호출이 보장됩니다.
          */
        }
    ];
💡 Tip. 설정이 잘 로드되었는지 체크하고 싶은 경우
//ex> swift
var check = agent.checkConfigSuccess()
//ex> obj-c
bool check = [agent checkConfigSuccess];
💡 Tip. 어플리케이션이 기동되자마자 NetFUNNEL 대기를 시작하고 싶은 경우

어플리케이션이 기동되자마자 NetFUNNEL 대기를 시작하고 싶은 경우에는, setConfig 가 성공적으로 설정파일을 로드한 후, 1회에 한 해 동작하는 콜백함수인, oneTimeCallback 함수 내에서 대기시작 함수를 아래와 같이 추가하는 것을 권장합니다.

//ex> swift
func actionAfterSetting(){
        var req = SurffyReqManager.shared
        req.NFStart(projectKey: "projectKey", segmentKey: "segmentKey")
}
//ex> obc-c
- (void)actionAfterSetting {
    //setConfig 직후, NF 호출 함수를 사용하면 설정파일이
    //로드되기 전에 함수가 불려서 NF가 작동 안 될 수도 있습니다. 
    //setConfig 직후 1회에 한하여 호출이 보장되는 영역이나 함수는 
    //여기 oneTimeCallback에 넣거나 콜백으로 추가하면 호출이 보장됩니다.
    
  SurffyReqManager * req = [SurffyReqManager shared];
  [req NFStartWithProjectKey: @"projectKey" segmentKey:@"segmentKey"];
  // Additional UI Process etc.
}

Step 3. 기본 제어 시작

가상 대기실을 노출하여 트래픽 대기를 적용하고 싶은 페이지(뷰 혹은 액티비티)의 특정 부분에서 대기 적용하기 위해서는 별도로 제공해드리는 대기 시작 함수를 사용하여 가상 대기실을 적용할 수 있습니다.

기본 제어 시작 과정에 사용되는 함수는 다음과 같습니다.

기본 제어 시작 함수

함수 종류함수명인자설명
기본 제어 시작 함수NFStartprojectKey세그먼트 등록시 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"];

Step 4. 구간 제어 시작

가상 대기실을 노출하여 트래픽 대기를 적용하고 싶은 페이지(뷰 혹은 액티비티)의 특정 부분에서 대기 적용하기 위해서는 별도로 제공해드리는 대기 시작 함수를 사용하여 가상 대기실을 적용할 수 있습니다.

이때, 특정 페이지의 진입과 끝 사이에 대기를 걸고 싶은 경우 구간 대기를 사용할 수 있습니다.
ex. 이벤트 페이지 진입부터 진입 후 상품 구매까지의 구간, 또는 로그인부터 로그아웃까지의 구간 등

SurffyReqManager를 shared 로 싱글톤 객체를 호출후, NFStartSection 함수를 사용합니다. 대기 키 반납은 NFStopSection 함수를 사용합니다.

기본 제어 시작 함수

함수 종류함수명인자설명
구간 제어 시작 함수NFStartSectionprojectKey세그먼트 등록시 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"];
💡 Tip. 가상 대기실이 잘 노출되는지 확인하는 방법

가상 대기실이 항상 노출시키기 위해서는 먼저 관리자 콘솔에서 진입 허용수를 0으로 설정해야 합니다. 진입 허용수가 0이라는 뜻은 어떠한 트래픽도 진입시키지 않는 다는 뜻입니다. 진입 허용수가 0으로 설정된 프로젝트 키와 세그먼트 키를 확인하고, 해당 키 값으로 대기 시작함수 를 호출하면 가상 대기실이 바로 노출되는 것을 확인할 수 있습니다.

Step 5. Delegate 구현

대기 중에는 상황에 따라 다양한 콜백함수가 호출됩니다. 콜백 함수의 종류에 따라 진입 성공 및 차단 처리를 할 수 있으며, 대기가 취소되었을 때 콜백함수를 구현하여 진입 차단과 대기 취소시 발생하는 여러 사용자 시나리오를 구현하실 수 있습니다.

다음은 서버로부터 받는 리턴코드와 호출되는 Delegate 안내입니다.

Return Code설명Delegate
0서비스 진입 요청 시 네트워크 에러SurffyActionError
200(SUCCESS)서비스 정상 연결SurffyActionSuccess
201(CONTUNUE)서비스 대기(대기열 진입)-
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
함수명인자설명
SurffyActionSuccessprojectKey진입 시 사용한 project 키 값 ex> service_1
segmentKey진입 시 사용한 segment 키 값 ex> serKey_1234
retcodedelegate 실행 시점의 요청의 결과 코드
SurffyActionErrorprojectKey진입 시 사용한 project 키 값 ex> service_1
segmentKey진입 시 사용한 segment 키 값 ex> serKey_1234
retcodedelegate 실행 시점의 요청의 결과 코드
SurffyActionCancelprojectKey진입 시 사용한 project 키 값 ex> service_1
segmentKey진입 시 사용한 segment 키 값 ex> serKey_1234
retcodedelegate 실행 시점의 요청의 결과 코드
SurffyActionBypassprojectKey진입 시 사용한 project 키 값 ex> service_1
segmentKey진입 시 사용한 segment 키 값 ex> serKey_1234
retcodedelegate 실행 시점의 요청의 결과 코드
SurffyActionBlockprojectKey진입 시 사용한 project 키 값 ex> service_1
segmentKey진입 시 사용한 segment 키 값 ex> serKey_1234
retcodedelegate 실행 시점의 요청의 결과 코드
SurffyCompleteSuccessprojectKey진입 시 사용한 project 키 값 ex> service_1
segmentKey진입 시 사용한 segment 키 값 ex> serKey_1234
SurffyActiSurffyCompleteErroronSuccessprojectKey진입 시 사용한 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

진입에 성공할 경우 호출되는 콜백을 구현

진입에 성공할 경우 두 가지를 구현합니다.
1️⃣ 타겟 페이지로 진입하는 코드
2️⃣ 완료 처리 함수 를 호출하여 발급된 키를 NetFUNNEL 서버에 반납하는 과정을 수행

기본 제어 완료 처리 함수

함수명 : NFStop

인자설명예시
projectKey세그먼트 등록시 NF 콘솔에 출력된 project 키 값service_1
segmentKey세그먼트 등록시 NF 콘솔에 출력된 segment 키 값serKey_1234

구간 제어 완료 처리 함수

함수명 : NFStopSection

인자설명예시
projectKey세그먼트 등록시 NF 콘솔에 출력된 project 키 값service_1
segmentKey세그먼트 등록시 NF 콘솔에 출력된 segment 키 값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"];
}

진입 성공에 해당하는 로직을 구현해야 하는 모든 콜백 함수들을 2. 에이전트 동작 흐름도에서 세부적으로 참고하시기 바랍니다.

진입이 차단되는 경우 호출되는 콜백을 구현

진입이 차단되는 경우는 보통 매크로 성의 잦은 요청이나 잘못된 키를 통해 악의적으로 요청을 하는 경우입니다. 이 같은 시나리오에서는 보통 고객의 유저 경험을 증대시키기 위한 목적으로 보통 아래와 같은 로직을 구현하실 수 있습니다.

진입에 성공할 경우 두 가지를 구현합니다.
1️⃣ 현재 페이지에 머무르고 싶을 경우에는 아무 로직도 구현할 필요가 없음
2️⃣ 진입이 차단되었음을 표시하는 모달 창을 별도로 띄우는 로직을 구현
3️⃣ 진입이 차단되었음을 표시하는 특정 페이지로 이동을 시키는 로직을 구현
4️⃣ 로깅 로직을 구현

진입이 차단 혹은 실패되는 경우에는 위와 같은 로직을 구현하실 수 있으며, 진입 성공 케이스와 다르게 별도의 완료 처리 함수 호출을 필요로 하지 않습니다.

아래는 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. 로깅 로직을 구현
    */
}

진입 차단 혹은 실패에 해당하는 로직을 구현해야 하는 모든 콜백 함수들을 2. 에이전트 동작 흐름도에서 세부적으로 참고하시기 바랍니다.

진입/대기중 에러가 나는 경우 호출되는 콜백을 구현

넷퍼넬 사용을 위해 대기열에 진입 중, 혹은 대기 중 에러가 나는 경우는 넷퍼넬 서버 다운, 네트워크 연결 이상 등의 원인이 있습니다. 진입 차단 혹은 실패에 해당하는 로직을 구현해야 하는 모든 Delegate 함수와 리턴 코드들을 2. 에이전트 동작 흐름도에서 세부적으로 참고하시기 바랍니다. 에러의 리턴코드에 따라, 다양한 흐름을 구현할 수 있습니다.

1️⃣ 에러 발생 시 진입을 허가 할 때 진입 성공과 같은 로직을 구현
2️⃣ 에러 발생 시 진입을 차단 할 때 진입 차단과 같은 로직을 구현
3️⃣ 그 외 에러에 따른 기타 로직을 구현

진입이 차단 혹은 실패되는 경우에는 위와 같은 로직을 구현하실 수 있으며, 진입 성공 케이스와 다르게 별도의 완료 처리 함수 호출을 필요로 하지 않습니다.

아래는 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 가 실행됩니다. 대기를 우회하는 경우에는 아래와 같은 로직등을 구현할 수 있습니다.

1️⃣ 진입을 허가 할 때 진입 성공과 같은 로직을 구현 2️⃣ 그 외 기타 로직을 구현

아래는 대기 우회 시 실행되는 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. 그 외 기타 로직을 구현
    */
}

대기가 취소될 경우 호출되는 콜백을 구현

엔드 유저가 가상 대기실에서 대기를 하고 있는 도중에 대기 취소 버튼을 누르게 경우는 대기 취소 콜백이 호출될 수 있습니다. 이 같은 시나리오에서는 보통 고객의 유저 경험을 증대시키기 위한 목적으로 보통 아래와 같은 로직을 구현하실 수 있습니다.

1️⃣ 현재 페이지에 머무르고 싶을 경우에는 아무 로직도 구현할 필요가 없음
2️⃣ 진입이 차단되었음을 표시하는 모달 창을 별도로 띄우는 로직을 구현
3️⃣ 진입이 차단되었음을 표시하는 특정 페이지로 이동을 시키는 로직을 구현
4️⃣ 로깅 로직을 구현

대기가 취소되는 경우에는 위와 같은 로직을 구현하실 수 있으며, 진입 성공 케이스와 다르게 별도의 완료 처리 함수 호출을 필요로 하지 않습니다.

아래는 대기 취소 버튼이 눌렸을 때 호출되는 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. 로깅 로직을 구현
    */
}
💡 Tip. 대기 취소 버튼을 눌렀을 때 별도의 모달창을 띄우고 대기를 재시작하는 방법
//ex> swift
func SurffyActionCancel(projectKey: String, segmentKey: String, retcode: Int, cancelTargetAddr: String) {
 
        let alert = UIAlertController(title: "정말 앱을 종료하시겠습니까?", message: "", 
          preferredStyle: UIAlertController.Style.alert)
        let cancle = UIAlertAction(title: "NF 재진입", style: .default, handler: {
            action in
            let SRM = SurffyReqManager.shared
            SRM.NFStart(projectKey: self.proKey.text ?? "", segmentKey: self.segKey.text ?? "")
        })
        //확인 버튼 만들기
        let ok = UIAlertAction(title: "종료", style: .destructive, handler: {
            action in
            //특정기능 수행
        })
        alert.addAction(cancle)
        //확인 버튼 경고창에 추가하기
        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:@"정말 앱을 종료하시겠습니까?"
                                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) {
                          // 특정 기능 
                          }];
 
    [alert addAction:cancel];
    [alert addAction:ok];
    [self presentViewController:alert animated:YES completion:nil];
}
 
@end

FAQ

🙋 Delegate 에서 주어지는 retcode란 무엇이고, 언제 필요한 값인가요?

🧑‍💻 retcode (Return Code, 리턴코드) 란 가상 대기 요청 시, 넷퍼넬 서버로부터 받는 결과 코드입니다. 리턴코드와 delegate 의 조합으로 원하시는 로직을 정의할 수 있습니다. 자세한 내용은 진입/대기중 에러가 나는 경우 호출되는 콜백을 구현을 참고 부탁드립니다.

ex.서비스 대기 요청 시 네트워크 단절 코드를(retcode : 0) 받았을 때 정상동작(대기를 우회)하고 싶은 경우

func SurffyActionError(projectKey: String, segmentKey: String, retcode: Int) {
    
    if(retcode == 0){
      /*
      projectKey, segmentKey 에 따라 의도하는 서비스가 정상동착하는 로직을 구현
      */
    }
}

ex. 서비스 대기 요청 시 네트워크 단절 코드를(retcode : 0) 받았을 때 차단하고 싶은 경우

func SurffyActionError(projectKey: String, segmentKey: String, retcode: Int) {
    
    if(retcode == 0){
      /*
      projectKey, segmentKey 에 따라 의도하는 서비스가 차단되는 로직을 구현
      */
    }
}

🙋 앱이 기동 될 때 넷퍼넬을 사용하고 싶은데 대기가 걸리지 않아요. 어떻게 해야 하나요?

🧑‍💻 넷퍼넬 설정이 로드되기 전에 넷퍼넬 요청이 불려질 경우 요청이 대기열에 정상적으로 들어가지 않을 수 있습니다. Step 2oneTimeCallback 항목을 참고 부탁드립니다.


🙋 기본 제어란 무엇이고, 구간 제어란 무엇인가요? 둘의 차이점에는 어떤 것이 있나요?

🧑‍💻 기본 제어란 특정 로직이나 액션자체에 대기를 거는 제어를 의미합니다. 기본 제어의 대기 키 반납은 대기 직후에 이루어지며(SurffyActionSuccess 에 키 반납을 하는 경우), 다음 대기자의 순번이 줄어들게 됩니다.
ex. 앱 진입에 대한 대기, 버튼 클릭에 대한 대기

구간 제어 란 특정 로직이나 액션 구간에 대기를 거는 제어를 의미합니다. 구간 제어는 진입 시점과 종료 시점을 설정해서, 진입부터 종료 사이의 총 진입 허용수 만큼만 트래픽을 조절합니다. 구간 제어의 대기 키 반납은 명시적인 키 반납 함수가 호출되어야 실행됩니다.
ex. 로그인(진입)-로그아웃(종료), 페이지 진입(진입)-페이지 이동(종료)


🙋 NF 서버가 다운될 경우에도 서비스를 정상동작하고 싶을 때에는, 어떤 구현을 해야하나요?

🧑‍💻 NF 서버 단절 시 동작되는 SurffyActionError Delegate 내 구현을 통해 정상 서비스를 제공 가능합니다.

ex. NF 서비스 대기 요청 시 네트워크 단절 코드를(retcode : 0) 받았을 때 대기를 우회하고 싶은 경우

func SurffyActionError(projectKey: String, segmentKey: String, retcode: Int){
    
    if(retcode == 0){
      /*
      projectKey, segmentKey 에 따라 의도하는 서비스가 정상동착하는 로직을 구현
      */
    }
}

ex. NF 진입 부분이 아닌 서비스 대기 요청 시 네트워크 단절 코드를(retcode : 0) 받았을 때 차단하고 싶은 경우

func SurffyActionError(projectKey: String, segmentKey: String, retcode: Int){
    
    if(retcode == 0){
      /*
      projectKey, segmentKey 는 nil 값이 리턴.
      의도하는 기타 로직 구현이 가능합니다.
      */
    }
}

부록

API 설명

구분함수명인자설명
설정 로드setConfigtenantURLNF 접속 URL
projectDetailURL설정파일을 가져올 URL
eumURLeum data 수집 URL
delegateNetFunnel delegate 선언 view 위치
oneTimeCallbacksetConfig 가 성공적으로 설정파일 로드한 후, 1회에 한 해 동작하는 콜백함수
URL 기반 NFstartManagerURL 값NF 콘솔페이지에 등록한 URL 값
URL 기반 NFcompleteManagerURL 값NF 콘솔페이지에 등록한 URL 값
Key 기반 NFNFStartprojectKey세그먼트 등록시 NF 콘솔페이지에 출력된 project 키 값 ex> service_1
segmentKey세그먼트 등록시 NF 콘솔페이지에 출력된 segment 키 값 ex> serKey_1234
Key 기반 NFNFStopprojectKey세그먼트 등록시 NF 콘솔페이지에 출력된 project 키 값 ex> service_1
segmentKey세그먼트 등록시 NF 콘솔페이지에 출력된 segment 키 값 ex> serKey_1234
Key 기반 NF (구간제어)NFStartSectionprojectKey세그먼트 등록시 NF 콘솔페이지에 출력된 project 키 값 ex> service_1
segmentKey세그먼트 등록시 NF 콘솔페이지에 출력된 segment 키 값 ex> serKey_1234
Key 기반 NF (구간제어)NFStopSectionprojectKey세그먼트 등록시 NF 콘솔페이지에 출력된 project 키 값 ex> service_1
segmentKey세그먼트 등록시 NF 콘솔페이지에 출력된 segment 키 값 ex> serKey_1234
delegateSurffyActionSuccessprojectKey진입 시 사용한 project 키 값 ex> service_1
segmentKey진입 시 사용한 segment 키 값 >ex> serKey_1234
retcodedelegate 실행 시점의 요청의 결과 코드
delegateSurffyActionSuccessprojectKey진입 시 사용한 project 키 값 ex> service_1
segmentKey진입 시 사용한 segment 키 값 >ex> serKey_1234
retcodedelegate 실행 시점의 요청의 결과 코드
delegateSurffyActionErrorprojectKey진입 시 사용한 project 키 값 ex> service_1
segmentKey진입 시 사용한 segment 키 값 >ex> serKey_1234
retcodedelegate 실행 시점의 요청의 결과 코드
delegateSurffyActionCancelprojectKey진입 시 사용한 project 키 값 ex> service_1
segmentKey진입 시 사용한 segment 키 값 >ex> serKey_1234
retcodedelegate 실행 시점의 요청의 결과 코드
delegateSurffyActionBypassprojectKey진입 시 사용한 project 키 값 ex> service_1
segmentKey진입 시 사용한 segment 키 값 >ex> serKey_1234
retcodedelegate 실행 시점의 요청의 결과 코드
delegateSurffyActionBlockprojectKey진입 시 사용한 project 키 값 ex> service_1
segmentKey진입 시 사용한 segment 키 값 >ex> serKey_1234
retcodedelegate 실행 시점의 요청의 결과 코드
delegateSurffyCompleteSuccessprojectKey진입 시 사용한 project 키 값 ex> service_1
segmentKey진입 시 사용한 segment 키 값 >ex> serKey_1234
delegateSurffyCompleteErrorprojectKey진입 시 사용한 project 키 값 ex> service_1
segmentKey진입 시 사용한 segment 키 값 >ex> serKey_1234