---
title: "Android 환경"
slug: "vpe-android"
updated: 2026-09-17T09:08:00Z
published: 2026-09-17T09:08:00Z
canonical: "guide.ncloud-docs.com/vpe-android"
stale: true
---

> ## Documentation Index
> Fetch the complete documentation index at: https://guide.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Android 환경

Classic/VPC 환경에서 이용 가능합니다.

Android 환경에서는 Android 전용 플레이어 개발을 위한 Video Player Enhancement Android SDK 사용 방법과 플레이어 적용 및 옵션 설정 방법을 설명합니다.

              참고

              

Android용 Video Player Enhancement SDK를 사용하려면 Standard 요금제를 이용해야 하며, 다음과 같은 사양이 요구됩니다.

- 최소 사양: API 26(Oreo 8.0) 이상, gradle 4.2.2 이상
- 개발 환경: Android Studio

## SDK 설치 및 환경 구성

SDK를 설치하고 프레임워크를 추가하는 방법은 다음과 같습니다.

1. 네이버 클라우드 플랫폼 콘솔에서 **Menu** > **All Services** > **Media** > **Video Player Enhancement** 메뉴를 차례대로 클릭해 주십시오.
2. **Video Player Management** 메뉴를 클릭해 주십시오.
3. 플레이어 목록에서 SDK를 다운로드할 플레이어의 **[SDK 주소]** 버튼을 클릭해 주십시오.
4. **모바일 네이티브 SDKs 다운로드**의 **[Android]** 버튼을 클릭해 주십시오.
  - 압축 파일이 다운로드됩니다.
5. 다운로드한 SDK 파일을 `root > app > libs` 경로에 추가해 주십시오.
6. app 레벨 build.gradle 파일의 dependencies에 다음과 같이 추가해 주십시오.

```
dependencies {
    ...
    implementation files('libs/NCPlayerSDK.aar')
    implementation 'com.google.code.gson:gson:2.10.1'
}
```

## 플레이어 적용 및 설정

플레이어를 적용하고 옵션을 설정하려면 다음 절차를 진행해 주십시오.

- [1. 초기화](/docs/vpe-android#1%EC%B4%88%EA%B8%B0%ED%99%94)
- [2. 플레이어 설정](/docs/vpe-android#2%ED%94%8C%EB%A0%88%EC%9D%B4%EC%96%B4%EC%84%A4%EC%A0%95)
- [3. 이벤트 설정](/docs/vpe-android#3%EC%9D%B4%EB%B2%A4%ED%8A%B8%EC%84%A4%EC%A0%95)

### 1. 초기화

다음과 같이 NCPlayerSDK 인스턴스를 초기화하고 Delegate를 설정해 주십시오.

```
...
import com.sgrsoft.ncp_aos.*
...
class MainActivity : AppCompatActivity() {
    ...
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        ...
        var delegate = PlayerDelegate()
        NCPlayer.delegate = delegate

    }
}
```

### 2. 플레이어 설정

플레이어를 설정하는 방법은 다음과 같습니다.

1. 네이버 클라우드 플랫폼 콘솔에서 **Menu** > **All Services** > **Media** > **Video Player Enhancement** 메뉴를 차례대로 클릭해 주십시오.
2. **Video Player Management** 메뉴를 클릭해 주십시오.
3. 설정할 플레이어의 **[SDK 주소]** 버튼을 클릭해 주십시오.
4. Player SDK 주소 팝업 창이 나타나면 **SDK 주소**에서 access_key 값을 확인해 주십시오.  

![vpe-ios_key_ko](https://cdn.document360.io/6998976f-9d95-4df8-b847-d375892b92c2/Images/Documentation/vpe-ios_key_ko.png?sv=2026-02-06&spr=https&st=2026-10-26T20%3A10%3A36Z&se=2026-10-26T21%3A10%3A36Z&sr=c&sp=r&sig=ED6jV2ARFp497oTAmL6rIeEoaw%2BhJTAUs7jRANRivvk%3D)
5. Android Studio에서 NCPlayerView를 사용할 UIView를 생성해 주십시오.
6. 플레이어의 옵션을 설정해 주십시오.

```
import com.sgrsoft.ncp_aos.*
...
class MainActivity : AppCompatActivity() {
    ...
    private lateinit var webView: WebView;
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        ...

        webView = findViewById(R.id.webVIew)
      
        // 등록된 APPLICATION_ID를 사용, 콘솔에 등록되어 있는 패키지 아이디만 허용됨
        var packageId = BuildConfig.APPLICATION_ID
     
        // licenseKey = access_key
        var licenseKey = "{access_key}" 
     
        // 화면 녹화 및 캡처 방지 기능 사용 여부(true: 기능 제한)
        var isScreenCaptureDeny = false
     
        // NCPlayerView 생성
        var player = NCPlayerView()
     
        // NCPlayerView 웹뷰와 연결
        player.webView = webView
     
        NCPlayer.prefs.setString("appId",packageId)
        NCPlayer.prefs.setString("licenseKey",licenseKey)
        NCPlayer.prefs.setString("isScreenCaptureDeny", isScreenCaptureDeny.toString())
     
        // 플레이어 옵션(콘솔에서 만들어진 스크립트 코드 사용)
        val playerOptions = 
        """
        {
            "playlist":[
                {
                    "file":"https://CDN도메인/example_video_01.mp4",
                    "poster":"https://CDN도메인/example_video_01.png",
                }
            ],
            "autostart":true,
        }
     
        """
        // 실행
        player.play(playerOptions,this)
    }
}
```
  - [플레이어 설정](/docs/vpe-web#%ED%94%8C%EB%A0%88%EC%9D%B4%EC%96%B4%EC%84%A4%EC%A0%95)과 이 가이드의 플레이어 설정 스크립트를 참고해 주십시오.
7. 녹화 방지를 위해 다음과 같이 코드를 작성해 주십시오.

```
import com.sgrsoft.ncp_aos.*
...
class MainActivity : AppCompatActivity() {
    ...
    
    private lateinit var webView: WebView;
    var player = NCPlayerView()
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        ...
        // 화면 녹화 및 캡처 방지 기능 사용 여부(true: 기능 제한)
        val isScreenCaptureDeny = false
        
        // NCPlayer에 변수 등록
        // "" 안의 string 값은 변경 금지
        NCPlayer.prefs.setString("isScreenCaptureDeny", isScreenCaptureDeny.toString())
    }
}
```
8. Picture in Picture 기능 사용을 위해 다음과 같이 코드를 작성해 주십시오.

```
override fun onUserLeaveHint() {
// 가로 비율을 원할 경우 <예시> 16,9
// 세로 비율을 원할 경우 <예시> 9,16
player.enterPip(this,9,16)
}
```
9. 웹뷰를 사용하는 경우 메모리 누수(Memory Leak) 방지를 위해 다음과 같이 플레이어 해제 코드를 작성해 주십시오.

```
import com.sgrsoft.ncp_aos.*
...
class PlayerDelegate: NCPlayerEventInterface{
... 
    player.destroy()
}
```

### 3. 이벤트 설정

Player Event API를 통해 Video Player Enhancement 플레이어에서 발생하는 이벤트를 바인딩하여 활용할 수 있습니다. 방법은 다음과 같습니다.

1. `NCPlayerNetworkStatus` 메소드를 이용하여 디바이스의 네트워크 상태를 확인해 주십시오.

```
import com.sgrsoft.ncp_aos.*
...
class PlayerDelegate: NCPlayerEventInterface{
    ...
    override fun NCPlayerNetworkStatus(state: String) {
        // state: ONLINE = 이상 없음 (ONLINE)
        // state: OFFLINE = 문제 발생 (OFFLINE 혹은 통신 장애 발생)
    }
}
```
2. 설정하고자 하는 이벤트에 따라 설정 방법을 확인해 주십시오.
  - [가로 모드 활성화 이벤트](/docs/vpe-android#%EA%B0%80%EB%A1%9C%EB%AA%A8%EB%93%9C%ED%99%9C%EC%84%B1%ED%99%94%EC%9D%B4%EB%B2%A4%ED%8A%B8)
  - [TimeUpdate 이벤트](/docs/vpe-android#TimeUpdate%EC%9D%B4%EB%B2%A4%ED%8A%B8)
  - [PrevTrack 이벤트](/docs/vpe-android#PrevTrack%EC%9D%B4%EB%B2%A4%ED%8A%B8)
  - [NextTrack 이벤트](/docs/vpe-android#NextTrack%EC%9D%B4%EB%B2%A4%ED%8A%B8)
  - [컨트롤바 활성화 이벤트](/docs/vpe-android#%EC%BB%A8%ED%8A%B8%EB%A1%A4%EB%B0%94%ED%99%9C%EC%84%B1%ED%99%94%EC%9D%B4%EB%B2%A4%ED%8A%B8)
  - [재생 이벤트](/docs/vpe-android#%EC%9E%AC%EC%83%9D%EC%9D%B4%EB%B2%A4%ED%8A%B8)
  - [일시 정지 이벤트](/docs/vpe-android#%EC%9D%BC%EC%8B%9C%EC%A0%95%EC%A7%80%EC%9D%B4%EB%B2%A4%ED%8A%B8)
  - [재생 완료 이벤트](/docs/vpe-android#%EC%9E%AC%EC%83%9D%EC%99%84%EB%A3%8C%EC%9D%B4%EB%B2%A4%ED%8A%B8)
  - [전체 화면 이벤트](/docs/vpe-android#%EC%A0%84%EC%B2%B4%ED%99%94%EB%A9%B4%EC%9D%B4%EB%B2%A4%ED%8A%B8)

#### 가로 모드 활성화 이벤트

디바이스를 가로로 전환 시 이벤트를 발생시키려면 `NCPlayerIsLandscape` 메소드를 이용하여 다음과 같이 설정해 주십시오.

```
import com.sgrsoft.ncp_aos.*
...
class PlayerDelegate: NCPlayerEventInterface{
    ...
    override fun NCPlayerIsLandscape(state: Boolean) {
    
    }
}
```

#### TimeUpdate 이벤트

재생 시간 변화 감지 시 이벤트를 발생시키려면 `NCPlayerOnTimeUpdate` 메소드를 이용하여 다음과 같이 설정해 주십시오.

```
import com.sgrsoft.ncp_aos.*
...
class PlayerDelegate: NCPlayerEventInterface{
    ...
    override fun NCPlayerOnTimeUpdate(data: JSONObject?) {
        // data = {"sourceType":"vod","currentTime":1,"duration":7715,"percent":0.008898181834278056,"viewingTime":1}
    }
}
```

              참고

              

각 속성에 대한 자세한 설명은 [timeupdate 스크립트](/docs/vpe-web#timeupdate%EC%8A%A4%ED%81%AC%EB%A6%BD%ED%8A%B8)를 참고해 주십시오.

#### PrevTrack 이벤트

플레이리스트 중 이전 영상으로 이동 시 이벤트를 발생시키려면 `NCPlayerOnPrevTrack` 메소드를 이용하여 다음과 같이 설정해 주십시오.

```
import com.sgrsoft.ncp_aos.*
...
class PlayerDelegate: NCPlayerEventInterface{
    ...
    override fun NCPlayerOnPrevTrack(data: JSONObject?) {
        // {"file":"","poster":"","description":{"title":"title","created_at":"","profile_name":"string","profile_image":"string"}}
    }
}
```

              참고

              

각 속성에 대한 자세한 설명은 [prevTrack 스크립트](/docs/vpe-web#prevTrack%EC%8A%A4%ED%81%AC%EB%A6%BD%ED%8A%B8)를 참고해 주십시오.

#### NextTrack 이벤트

플레이리스트 중 다음 영상으로 이동 시 이벤트를 발생시키려면 `NCPlayerOnNextTrack` 메소드를 이용하여 다음과 같이 설정해 주십시오.

```
import com.sgrsoft.ncp_aos.*
...
class PlayerDelegate: NCPlayerEventInterface{
    ...
    override fun NCPlayerOnNextTrack(data: JSONObject?) {
        // {"file":"","poster":"","description":{"title":"title","created_at":"","profile_name":"string","profile_image":"string"}}
    }
}
```

              참고

              

각 속성에 대한 자세한 설명은 [nextTrack 스크립트](/docs/vpe-web#nextTrack%EC%8A%A4%ED%81%AC%EB%A6%BD%ED%8A%B8)를 참고해 주십시오.

#### 컨트롤바 활성화 이벤트

플레이어에서 컨트롤바 활성화/비활성화 시 이벤트를 발생시키려면 `NCPlayerOnControlbarActive` 메소드를 이용하여 다음과 같이 설정해 주십시오.

```
import com.sgrsoft.ncp_aos.*
...
class PlayerDelegate: NCPlayerEventInterface{
    ...
    override fun NCPlayerOnControlbarActive(active: JSONObject?) {
        // active: true, false
    }
}
```

#### 재생 이벤트

플레이어에서 영상 재생 시 이벤트를 발생시키려면 `NCPlayerOnPlay` 메소드를 이용하여 다음과 같이 설정해 주십시오.

```
import com.sgrsoft.ncp_aos.*
...
class PlayerDelegate: NCPlayerEventInterface{
    ...
    override fun NCPlayerOnPlay() {
    
    }
}
```

#### 일시 정지 이벤트

플레이어에서 영상 일시 정지 시 이벤트를 발생시키려면 `NCPlayerOnPause` 메소드를 이용하여 다음과 같이 설정해 주십시오.

```
import com.sgrsoft.ncp_aos.*
...
class PlayerDelegate: NCPlayerEventInterface{
    ...
    override fun NCPlayerOnPause() {
    
    }
}
```

#### 재생 완료 이벤트

플레이어에서 영상 재생 완료 시 이벤트를 발생시키려면 `NCPlayerOnEnd` 메소드를 이용하여 다음과 같이 설정해 주십시오.

```
import com.sgrsoft.ncp_aos.*
...
class PlayerDelegate: NCPlayerEventInterface{
    ...
    override fun NCPlayerOnEnd() {
    
    }
}
```

#### 전체 화면 이벤트

전체 화면 전환 시 이벤트를 발생시킬 수 있으며, 디바이스 회전 시 전체 화면으로 자동 전환하도록 설정할 수 있습니다.

**전체 화면 이벤트**

플레이어를 전체 화면으로 전환 시 이벤트를 발생시키려면 `NCPlayerOnFullscreen` 메소드를 이용하여 다음과 같이 설정해 주십시오.

```
import com.sgrsoft.ncp_aos.*
...
class PlayerDelegate: NCPlayerEventInterface{
    ...
    
    val delegate = PlayerDelegate()
    NCPlayer.delegate = delegate
    
    override fun NCPlayerOnFullscreenState(state: Boolean) {
        // fullscreen true / false
    }
    
    // 전체 화면이 꺼졌을 때 발생하는 이벤트
    override fun NCPlayerOnFullscreenOff() {
    
    }
    
    // 전체 화면이 되었을 때 발생하는 이벤트
    override fun NCPlayerOnFullscreenOn() {
    
    }
}
```

**전체 화면 자동 전환**

디바이스 회전 시 전체 화면으로 자동 전환하는 기능을 제공하려면 다음과 같이 설정해 주십시오.

```
override fun onConfigurationChanged(newConfig: Configuration) {
    super.onConfigurationChanged(newConfig)

    if (newConfig.orientation == Configuration.ORIENTATION_PORTRAIT)
    {
        NCPlayer.delegate?.NCPlayerIsLandscape(false)
        player.fullscreenOff()
    }
    else if (newConfig.orientation == Configuration.ORIENTATION_LANDSCAPE)
    {
        NCPlayer.delegate?.NCPlayerIsLandscape(true)
        player.fullscreenOn()
    }
}
```