documentation
NetFUNNEL
Android 에이전트

Android Agent v4.1.1

⭐️ 에이전트 요구 사항 : Java 1.8 / Android SDK 21(Lollipop) 이상

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

Android Agent 동작 흐름도

안드로이드에이전트동작흐름도

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

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

에이전트 적용 방법

Step 1. 라이브러리 추가

라이브러리를 다운 받아 아래와 같이 Gradle에 추가해주세요.

build.gradle 기준

implementation files('libs/netfunnel-android-agent_latest.aar')

build.gradle.kts 기준

implementation(files("libs/netfunnel-android-agent_latest.aar"))

Step 2. 설정 정보 초기화

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

NetFUNNEL 기능을 사용 하기 전, InitNetfunnel, InitEum 함수를 사용하여 초기화 해주세요.

public class Activity extends AppCompatActivity {
    // ...
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity);
        
        // NetFUNNEL 초기화
        Init()
        
        // ...
    }
    // ...
    
    // NetFUNNEL 설정 정보 초기화
    public void Init() {
        Netfunnel.getInstance().InitNetfunnel(
            "{Application Name}", // 애플리케이션의 이름
            "{tenant API URL}",   // API Server URL
            "{tenant NF URL}",    // NetFUNNEL Server URL
            "{nf-setting URL}",   // NetFUNNEL Setting File URL
            "{network Timeout}",  // 넷퍼넬 요청의 최대 타임아웃 시간
            this                  // 대기/차단 창이 생성되기 위한 Activity
        );
        
        Netfunnel.getInstance().InitEum(
            "{EUM Server URL}", // EUM Server URL
            "{timeout}",        // EUM 요청 최대 타임아웃 시간
            this
        );
        
        Netfunnel.getInstance().EUMCollectYN(true); // EUM 수집 여부
    }
}

Step 3. 대기 종료 후 실행될 콜백함수를 구현

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

콜백함수는 NetFUNNEL 제어 응답에 따른 동작이 정의된 인터페이스인 AgentInterface 클래스에서 정의하고 있습니다. 별도의 클래스에서 AgentInterface 클래스 상속받아서 내부 콜백함수들을 구현하시거나 아래와 같이 AgentInterface 클래스의 생성자로부터 내부 콜백함수들을 구현하실 수 있습니다.

AgentInterface 클래스 생성자를 통한 콜백 함수들을 구현 방법

AgentInterface agentInterface = new AgentInterface() {
    @Override
	public void onSuccess() {
	 /*
	  * 대기종료 후, 진입성공 시 호출 (혹은 넷퍼넬 서버문제로 인해 요청실패 시 호출)
	  */
	}
 
	@Override
	public void onCancel() {
	 /*
	  * 대기화면에서 대기취소 버튼 클릭 시 호출
	  */
	}
 
	@Override
	public void nfLog(String _message) {
	  /*
	   * 넷퍼넬 라이브러리에 기록되는 로그가 호출 (넷퍼넬 라이브러리를 디버그할 경우 사용)
	   * 예시 : nfLog.d(_message)
	   */
	}
 
	@Override
	public void onNetworkDisconnect() {
	   /*
		* 디바이스의 네트워크 차단으로 인해, 넷퍼넬 서버요청 실패 시 호출
		*/
	}
 
	@Override
	public void onKeyError() {
		/*
		 * 키 문제 시 호출
		 * 예시 : 만료된 키, 혹은 존재하지 않는 키, 혹은 잘못된 키로 요청할 경우 호출
		 */
	}
 
	@Override
	public void onBlock() {
		/*
		 * SCP 관리자 콘솔의 프로젝트 접근모드 설정이 비활성화 되어있을 경우 호출
		 */
	}
 
	@Override
	public void onIpBlock() {
		/*
		 * SCP 관리자 콘솔의 매크로 차단 설정으로 인해 차단된 경우 호출
		 */
	}
};

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

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

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

완료 처리 함수

함수명 : NFStop

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

onSuccess()콜백 함수를 구현한 예시 코드는 다음과 같습니다.

AgentInterface agentInterface = new AgentInterface() {
@Override
public void onSuccess() {
    // 기본제어 종료함수 실행
    Netfunnel.getInstance().NFStop("{projectKey}", "{segmentKey}");
 
    // 액티비티 전환 수행
    runOnUiThread(new Runnable() {
        @Override
        public void run() {
            Intent intent = new Intent(CurrentActivity.this, NewActivity.class);
            startActivity(intent);
        }
    });
}
};
 

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

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

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

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

아래는 onBlock 콜백 함수를 구현한 예시 코드입니다.

AgentInterface agentInterface = new AgentInterface() {
    @Override
    public void onBlock() {
        /*
		1. 현재 페이지에 머무르고 싶을 경우에는 아무 로직도 구현할 필요가 없음
		2. 진입이 차단되었음을 표시하는 모달 창을 별도로 띄우는 로직을 구현
		3. 진입이 차단되었음을 표시하는 특정 페이지로 이동을 시키는 로직을 구현
		4. 로깅 로직을 구현
		*/
    }
};

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

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

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

대기가 취소되는 경우에는 위와 같은 로직을 구현할 수 있으며, 진입 성공 케이스와 다르게 별도의 완료 처리 함수 호출을 필요로 하지 않습니다. 아래는 대기 취소 버튼이 눌렸을 때 호출되는 onCancel콜백 함수를 구현한 예시 코드입니다.

AgentInterface agentInterface = new AgentInterface() {
    @Override
    public void onCancel() {
        /*
		1. 현재 페이지에 머무르고 싶을 경우에는 아무 로직도 구현할 필요가 없음
		2. 진입이 차단되었음을 표시하는 모달 창을 별도로 띄우는 로직을 구현
		3. 진입이 차단되었음을 표시하는 특정 페이지로 이동을 시키는 로직을 구현
		4. 로깅 로직을 구현
		*/
    }
};
💡 Tip. 대기 취소 버튼을 누를 때 별도의 모달창을 띄우고 대기를 재시작하는 방법
AgentInterface agentInterface = new AgentInterface() {
    @Override
    public void onCancel() {
        AlertDialog.Builder builder = new AlertDialog.Builder(activity);
        builder.setTitle("알림");
        builder.setMessage("앱을 종료하시겠습니까, 재진입 시도하시겠습니까?");
        builder.setPositiveButton("종료", new DialogInterface.OnClickListener() {
            @Override
            public void onClick(DialogInterface dialog, int which) {
                activity.finish();
            }
        });
 
        builder.setNegativeButton("재진입 시도", new DialogInterface.OnClickListener() {
            @Override
            public void onClick(DialogInterface dialog, int which) {
                Netfunnel.getInstance().NFStart(projectKey, segmentKey, agentInterface);
            }
        });
        builder.show();
    }
};

Step 4. 대기 시작

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

NetFUNNEL 가상 대기실을 노출시켜서 엔드 유저를 대기시키기 위한 코드 부분에 NFStart() 함수 호출시켜 주세요.

Netfunnel.getInstance().NFStart("{project Key}", "{segment Key}", agentInterface);
💡

Tip. 가상 대기실이 잘 노출되는지 확인하는 방법
진입 허용수가 0이라는 뜻은 어떠한 트래픽도 진입 시키지 않는다는 뜻입니다. 진입 허용수가 0으로 설정된 프로젝트 키와 세그먼트 키를 확인하고, 해당 키 값으로 대기 시작 함수를 호출하면 가상 대기실이 바로 노출되는 것을 확인할 수 있습니다.


부록

Object, Class

NameTypeDescription
NetfunnelObjectNetFUNNEL 기능 동작의 뼈대를 담당하고 있으며 해당 Object의 함수를 사용하여 NetFUNNEL 동작을 실행합니다.
AgentInterfaceabstract Class추상화 클래스로 NetFUNNEL 응답에 대한 기능을 정의하기 위한 인터페이스로 제공됩니다.<br><br>해당 객체를 생성하여 NetFUNNEL 동작 실행 시 인자로 전달해야 합니다.
EUMInterceptClassClassOkhttp 통신을 사용할 경우 Intercept 기능을 활용하여, 해당 클래스를 Intercept하고, 네트워크 통신에 걸린 시간을 모니터링 할 수 있습니다.

Netfunnel Function

InitNetfunnel
NetFUNNEL 기능 동작을 위한 초기화 데이터를 전달 받아 NetFUNNEL 설정 값을 읽어오는 함수입니다. 세부 인자는 Console페이지의 Agent탭의 값을 복사하여 사용하면 됩니다.

ArgumentTypeArgument Description필수 여부
appNameStringApp 구분을 위한 사용자의 고유한 AppNameO
apiURLStringAPI 서버 주소O
nfURLStringNetFUNNEL 서버 주소O
settingURLStringNetFUNNEL 동작 설정 파일의 주소O
functionTimeoutLongNetFUNNEL 동작 네트워크 타임아웃 설정 값O
activityActivity대기/차단 창이 생성되기 위한 ActivityO

NFStart
NetFUNNEL 기본제어를 시작하는 함수입니다.

ArgumentTypeArgument Description필수 여부
projectKeyString프로젝트 KeyO
segmentKeyString세그먼트 KeyO
callbackAgentInterfaceNetFUNNEL 제어 응답에 따른 동작이 정의된 인터페이스O

NFStop
NetFUNNEL 키를 반납을 하는 함수입니다.

ArgumentTypeArgument Description필수 여부
projectKeyString프로젝트 KeyO
segmentKeyString세그먼트 KeyO

NFStartSection
NetFUNNEL 구간제어를 시작하는 함수입니다.

ArgumentTypeArgument Description필수 여부
projectKeyString프로젝트 KeyO
segmentKeyString세그먼트 KeyO
callbackAgentInterfaceNetFUNNEL 제어 응답에 따른 동작이 정의된 인터페이스O

NFStopSection
NetFUNNEL 구간제어를 종료와 키를 반납하는 함수입니다.

ArgumentTypeArgument Description필수 여부
projectKeyString프로젝트 KeyO
segmentKeyString세그먼트 KeyO

InitEum
End User Monitoring 기능을 사용하기 위해 Eum 기능을 초기화 합니다.

ArgumentTypeArgument Description필수 여부
eumURLStringEUM 서버 주소 (Netfunnel 서버 주소와 동일)O
timeoutLongEUM 동작 네트워크 타임아웃 설정 값O
activityActivityEUM 수집 데이터 중 디바이스의 정보를 일부 수집하여 Activity를 필요로 합니다. 값이 없을 경우 디바이스의 정보를 수집하지 않습니다.O

EUMBegin
End User Monitoring 기능의 구간 시작을 해당 함수를 사용하여 직접 설정할 수 있습니다.

ArgumentTypeArgument Description필수 여부
urlStringEUM 구간 측정을 도메인 단위로 관리하고, 도메인 단위로 UI에 표출됩니다.O

EUMEnd
해당 함수를 사용하여 EUMBegin ~ EUMEnd까지의 소요시간을 측정하여 별도의 수집 데이터와 함께 전송합니다.

ArgumentTypeArgument Description필수 여부
urlStringEUM 구간 측정을 도메인 단위로 관리하고, 도메인 단위로 UI에 표출됩니다.O

EUMCollectYN
해당 함수를 사용하여 EUM 수집을 비활성화 할 수 있습니다.

ArgumentTypeArgument Description필수 여부
bBooleanInitEum 호출 시 기본적으로 EUM 수집이 활성화 되어있습니다. 해당 값을 false로 변경하여 EUM 수집을 비활성화 할 수 있습니다.O

AgentInterface Function

onSuccess
NetFUNNEL 응답 성공 시 호출됩니다.

ArgumentTypeArgument Description필수 여부
---O

onCancel
사용자가 대기/차단 취소 요청 시 호출됩니다.

ArgumentTypeArgument Description필수 여부
---O

onNetworkDisconnect
넷퍼넬 서버에 요청에 실패했으나, 그 원인이 디바이스의 네트워크가 차단된 경우에 호출 됩니다.

ArgumentTypeArgument Description필수 여부
---O

onKeyError
이미 만료된 키, 혹은 존재하지 않는 키, 혹은 잘못된 키로 요청할 경우 호출됩니다.

ArgumentTypeArgument Description필수 여부
---O

onBlock
관리자 콘솔에서 프로젝트 접근 모드 설정이 비활성화 되어 있을 경우에 호출됩니다.

ArgumentTypeArgument Description필수 여부
---O

onIpBlock
관리자 콘솔에서 매크로 차단 기능 잦은 요청이 차단된 경우 호출됩니다.

ArgumentTypeArgument Description필수 여부
---O

nfLog
라이브러리 내부 동작을 사용자의 앱을 테스트하며 파악할 수 있도록 해당 함수를 통하여 로그를 전달합니다.

ArgumentTypeArgument Description필수 여부
messageStringLibrary 동작 로그O