콘텐츠로 이동
NetFUNNEL Docs

퀵가이드

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

1. 디렉터리 구조

섹션 제목: “1. 디렉터리 구조”

아래는 예제의 기본 디렉터리 구조입니다. 각 파일은 에이전트 초기화, 진입 요청, 진입 완료 처리를 담당합니다.

app/src/main/
├── AndroidManifest.xml      // 인터넷 권한 · Application 등록
└── java/com/example/
    ├── SampleApplication.kt // initialize 호출 - 에이전트 초기화
    ├── MainActivity.kt      // nfStart 호출 - 진입 요청
    └── EventActivity.kt     // nfStop 호출 - 진입 완료 처리

2. 에이전트 초기화

섹션 제목: “2. 에이전트 초기화”

Android 에이전트는 안정적인 동작을 위해 앱 실행 시 가장 먼저 초기화되어야 합니다. 따라서 Application 클래스의 onCreate()에서 초기화 함수를 호출합니다. (에이전트 설치와 자세한 초기화 설정은 통합 가이드를 참고하세요.)

SampleApplication.kt
import com.nf4.Netfunnel


class SampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Netfunnel.initialize(clientId = "{CLIENT_ID}")
    }
}

AndroidManifest.xml에 NetFUNNEL 서버와 통신하기 위한 인터넷 권한을 추가하고, 위에서 만든 Application 클래스를 등록합니다.

AndroidManifest.xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android">


    <!-- 인터넷 접속 권한 허용 -->
    <uses-permission android:name="android.permission.INTERNET" />


    <!-- Application 클래스 등록 -->
    <application
        android:name=".SampleApplication"
        ... >
    </application>


</manifest>

3. 콜백 함수

섹션 제목: “3. 콜백 함수”

시작 함수(nfStart, nfStartSection)에 전달한 콜백으로 넷퍼넬 서버의 응답을 받습니다. 응답은 콜백 메서드와 상태 코드(statusCode), 메시지(message)로 전달되며, 콜백에 따라 분기 처리합니다.

  • onSuccess: 진입 또는 우회 응답. 화면 이동·함수 실행 등 기존 서비스 로직을 실행합니다.
  • onError: 시스템 에러. 원활한 이용을 위해 onSuccess와 동일하게 기존 로직을 실행합니다.
  • onNetworkError: 네트워크 장애. 기존 로직을 실행하거나, 악용 방지를 위해 다시 대기하도록 처리할 수 있습니다.
private val startCallback = object : NetfunnelCallback() {
    override fun onSuccess(statusCode: Int, message: String) {
        // 대상 화면으로 이동
        startActivity(Intent(this@MainActivity, EventActivity::class.java))
    }


    override fun onError(statusCode: Int, message: String) {
        // 기존 서비스 로직 실행
        startActivity(Intent(this@MainActivity, EventActivity::class.java))
    }


    override fun onNetworkError(statusCode: Int, message: String) {
        // 네트워크 에러 안내 후 재시도
        Toast.makeText(this@MainActivity, "네트워크 요청에 실패했습니다. 다시 시도합니다.", Toast.LENGTH_SHORT).show()
        Netfunnel.nfStart("{PROJECT_KEY}", "{SEGMENT_KEY}", this, this@MainActivity)
    }
}

4. 시작 함수

섹션 제목: “4. 시작 함수”

nfStart(기본 제어), nfStartSection(구간 제어)는 대기 상태를 감지하고 필요 시 대기실을 띄우는 함수입니다. 대기실을 띄울 화면(Activity)을 마지막 파라미터로 전달합니다.

Netfunnel.nfStart("{PROJECT_KEY}", "{SEGMENT_KEY}", startCallback, this)

5. 종료 함수

섹션 제목: “5. 종료 함수”

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

Netfunnel.nfStop("{PROJECT_KEY}", "{SEGMENT_KEY}", object : NetfunnelCompleteCallback() {})

6. 코드 기반 적용 예시

섹션 제목: “6. 코드 기반 적용 예시”

6.1 MainActivity에서 EventActivity로 이동

섹션 제목: “6.1 MainActivity에서 EventActivity로 이동”

MainActivity에서 EventActivity로 이동하는 버튼에서 시작 함수를 호출해 대기열을 적용하고, onSuccess 응답을 받으면 EventActivity로 이동합니다. EventActivity가 생성되면 종료 함수를 호출해 키를 반납합니다. (기본 제어와 구간 제어의 적용 방식은 동일합니다.)

MainActivity.kt
import com.nf4.Netfunnel
import com.nf4.NetfunnelCallback


class MainActivity : AppCompatActivity() {


    private val startCallback = object : NetfunnelCallback() {
        override fun onSuccess(statusCode: Int, message: String) = goToEvent()
        // 시스템 에러 시에도 서비스 이용을 위해 이동
        override fun onError(statusCode: Int, message: String) = goToEvent()
        override fun onNetworkError(statusCode: Int, message: String) = goToEvent()
    }


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


        findViewById<Button>(R.id.btnEvent).setOnClickListener {
            Netfunnel.nfStart("{PROJECT_KEY}", "{SEGMENT_KEY}", startCallback, this)
        }
    }


    private fun goToEvent() {
        startActivity(Intent(this, EventActivity::class.java))
    }
}
EventActivity.kt
import com.nf4.Netfunnel
import com.nf4.NetfunnelCompleteCallback


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


        // 화면 진입 후 진입 키 반납
        Netfunnel.nfStop("{PROJECT_KEY}", "{SEGMENT_KEY}", object : NetfunnelCompleteCallback() {})
    }
}

6.2 하나의 화면 안에서 함수를 실행

섹션 제목: “6.2 하나의 화면 안에서 함수를 실행”

한 화면 안에서 시작 함수 호출 후, onSuccess에서 서비스 로직(예: 주문 요청)을 처리한 뒤 적절한 위치에서 종료 함수를 실행합니다.

OrderActivity.kt
private val startCallback = object : NetfunnelCallback() {
    override fun onSuccess(statusCode: Int, message: String) {
        requestOrder {
            // 주문 처리가 끝나면 진입 키 반납
            Netfunnel.nfStop("{PROJECT_KEY}", "{SEGMENT_KEY}", object : NetfunnelCompleteCallback() {})
        }
    }
    override fun onError(statusCode: Int, message: String) = requestOrder {}
    override fun onNetworkError(statusCode: Int, message: String) = requestOrder {}
}


fun onOrderButtonClick() {
    Netfunnel.nfStart("{PROJECT_KEY}", "{SEGMENT_KEY}", startCallback, this)
}