Skip to main content

Android 퀵 가이드

퀵 가이드는 NetFUNNEL Android 에이전트를 처음 적용하는 개발자가 빠르게 시작할 수 있도록 필수 구현 사항을 간략하게 안내합니다.

1. 디렉터리 구조

아래 단계에서 구현하게 될 NetFUNNEL 적용 예제의 기본 디렉터리 구조입니다. 각 파일은 에이전트 초기화, 진입/종료 콜백 처리, UI 흐름 제어를 담당합니다.

project_root/
├── netfunnel/
│   ├── StartCallback // Handles the start callback
│   └── StopCallback  // Handles the stop callback
│
├── activity/
│   ├── MainActivity  // Calls nfStart - entry request
│   └── EventActivity // Calls nfStop - entry completion
│
└── SampleApplication // Calls initialize - Application class

2. 초기화

NetFUNNEL Android 에이전트는 앱 전역의 안정적인 동작을 위해 앱 진입 시점에 초기화되어야 합니다. Application.onCreate()에서 초기화하고, AndroidManifest.xml의 android:name 속성에 등록합니다.

SampleApplication.kt
import com.nf4.Netfunnel
import android.app.Application

class SampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Netfunnel.initialize(
            clientId = "{CLIENT_ID}"
        )
    }
}
AndroidManifest.xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <uses-permission android:name="android.permission.INTERNET" />

    <application
        android:name=".SampleApplication"
        android:allowBackup="true">
        ...
    </application>

</manifest>

3. 시작 콜백

대기실 시작 이후 호출되는 콜백입니다. 상태에 따라 onSuccess, onContinue, onError 등의 콜백이 호출됩니다. MapsToEventActivity는 대기 성공 또는 오류 발생 시 서비스 화면으로 이동합니다.

info

NetFUNNEL 사용 시 onSuccess, onError, onNetworkError 콜백은 반드시 구현해야 합니다. 그 외의 콜백 함수는 필요 시 구현할 수 있습니다.

StartCallback.kt
import com.nf4.NetfunnelCallback
import android.content.Intent
import android.util.Log
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity

class StartCallback(private val activity: AppCompatActivity) {

    companion object {
        private const val TAG = "NetFUNNEL"
    }

    val callback = object : NetfunnelCallback() {
        override fun onSuccess(statusCode: Int, message: String) {
            /**
            * Logic to handle after passing the waiting queue
            * ex - Proceed to the service screen
            */
            Log.d(TAG, "onSuccess $statusCode $message")
            navigateToEventActivity(activity)
        }

        override fun onError(statusCode: Int, message: String) {
            /**
            * Logic to handle errors
            * ex - Display an error message to the user or bypass
            */
            Log.d(TAG, "onError $statusCode $message")
            navigateToEventActivity(activity)
        }

        override fun onNetworkError(statusCode: Int, message: String) {
            /**
            * Logic to handle network errors
            * ex - Guide user to reconnect or move to a retry screen
            */
            Log.d(TAG, "onNetworkError $statusCode $message")
            when (statusCode) {
                1001 -> {
                    activity.runOnUiThread {
                        Toast.makeText(activity, "Network connection failed. Please check your network settings.", Toast.LENGTH_SHORT).show()
                    }
                }
                1002 -> {
                    navigateToEventActivity(activity)
                }
            }
        }

        override fun onBlock(statusCode: Int, message: String) {
            /**
            * Logic to handle user blocking
            * ex - Display an access restriction message
            */
            Log.d(TAG, "onBlock $statusCode $message")
        }

        override fun onClose(statusCode: Int, message: String) {
            /**
            * Logic to handle when a user cancels waiting (WebView closes, returning to the previous screen)
            * ex - Display a cancellation confirmation Toast
            */
            Log.d(TAG, "onClose $statusCode $message")
        }

        override fun onContinue(statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
            /**
            * UI update logic during waiting (only for custom waiting rooms)
            * ex - Update the custom waiting screen with real-time waiting information
            */
            Log.d(TAG, "onContinue $statusCode $message")
        }
    }

    fun getCallback(): NetfunnelCallback = callback

    fun navigateToEventActivity(activity: AppCompatActivity) {
        val intent = Intent(activity, EventActivity::class.java)
        activity.startActivity(intent)
    }
}

4. 종료 콜백

대기 완료 후 서버에 진입 키를 반납한 결과를 확인하는 콜백입니다.

StopCallback.kt
import com.nf4.NetfunnelCompleteCallback
import android.util.Log

class StopCallback {

    companion object {
        private const val TAG = "NetFUNNEL"
    }

    val callback = object : NetfunnelCompleteCallback() {
        override fun onComplete(statusCode: Int, message: String) {
            /**
            * Logic to handle the result of returning the entry key
            * ex - Proceed to the next page upon successful key return
            */
            Log.d(TAG, "onComplete $statusCode $message")
        }
    }

    fun getCallback(): NetfunnelCompleteCallback = callback
}

5. 시작 함수

nfStart(기본 제어), nfStartSection(구간 제어)은 대기 상태를 확인하고 필요 시 대기실을 띄우기 위한 함수입니다.

MainActivity.kt
import com.nf4.Netfunnel
import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        val callback = StartCallback(this)
        Netfunnel.nfStart("{{PROJECET_KEY}}", "{{SEGMENT_KEY}}", callback.getCallback(), this)
    }
}

6. 종료 함수

nfStop(기본 제어), nfStopSection(구간 제어)은 대기 완료 후 서버에 진입 키를 반납하기 위한 함수입니다. 진입 키를 서버에 반납하여 다음 사용자가 진입할 수 있도록 하며, 일반적으로 서비스 진입 직후 실행합니다.

EventActivity.kt
import com.nf4.Netfunnel
import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle

class EventActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_event)
        val callback = StopCallback()
        Netfunnel.nfStop("{{PROJECET_KEY}}", "{{SEGMENT_KEY}}", callback.getCallback())
    }
}