PlaynPlay
PlaynPlay

Android

Android SDK를 고객사 앱에 넣어
앱 안에서 보안 재생을 시작합니다

Android 7.1(API 25) 이상을 지원하고 Jetpack Media3를 기반으로 만들어졌습니다. 기본 플레이어 화면을 그대로 띄우거나 앱 화면 안에 플레이어를 넣을 수 있습니다. 워터마크와 루팅·앱 플레이어 감지처럼 Android에서 따로 챙길 보안 항목도 함께 정리했습니다.

최종 수정

Android 앱 보안 재생을 표현한 PlaynPlay 일러스트
User Experience

수강생이 앱에서 보는 플레이어

앱이 presentMediaPlayer()를 호출하면 아래 화면이 열립니다. UI를 따로 만들지 않아도 이 화면으로 재생할 수 있습니다.

  • Controls

    기본 컨트롤 화면

    위쪽에 종료 버튼, 타임바, 메뉴, 화면 속 화면 버튼이 있습니다. 가운데에는 화면 회전 잠금, 구간 반복, 트랙 설정, 0.1배 단위 배속 버튼(0.1~4.0배)이 있고, 아래쪽에는 화면 잠금, 이전·다음, 10초 이동, 화면 크기 조절 버튼이 있습니다.

  • Menu

    재생 목록과 북마크

    메뉴에서 재생 목록의 다른 차시를 고르고, 현재 위치를 북마크로 저장합니다. 제목을 비워 두면 Untitled로 저장되고, 이름 변경과 삭제는 목록 각 행의 버튼으로 합니다.

  • Gestures

    제스처와 키보드·패드

    좌우 드래그로 위치를 옮기고, 화면 왼쪽을 위아래로 끌면 밝기, 오른쪽은 볼륨이 바뀝니다. 방향 패드 좌우 키는 10초, 길게 누르면 1초씩 이동하고 스페이스 키는 재생과 일시 정지를 바꿉니다.

  • Picture in Picture

    화면 속 화면

    Android 8.0(API 26)부터 쓸 수 있습니다. 더블 클릭이나 상단 버튼으로 들어가고, 작은 창에도 진행바와 10초 이동 버튼이 있습니다.

Project Setup

개발팀이 준비할 다섯 단계

Android Studio 기준입니다. 서버 쪽 Callback URL은 PC·iOS와 같은 문서를 따릅니다.

  1. 콘솔에 패키지 이름 등록

    콘솔 설정 > 애플리케이션의 Bundle ID (Package name)에 build.gradle.kts의 applicationId를 추가합니다. 등록하지 않은 앱에서는 AppBundleNotRegisteredException이 발생합니다.

  2. SDK와 의존성 추가

    NPlayerSDK-release.aar를 프로젝트에 넣고 Media3 1.9.2 등 문서에 적힌 의존성을 추가합니다. 코어 라이브러리 디슈가링을 켜고 Java 11로 맞춥니다.

  3. AndroidManifest 수정

    INTERNET, READ_MEDIA_VIDEO, FOREGROUND_SERVICE, FOREGROUND_SERVICE_MEDIA_PLAYBACK 권한과 다운로드 완료 수신기, 플레이어 액티비티, 재생 서비스를 선언합니다. 타깃 API 32 이하는 READ_EXTERNAL_STORAGE를 씁니다.

  4. 서비스 시작과 재생

    앱 시작 시 startMediaPlayerService()에 App ID를 넣습니다. 미디어마다 withDrmConfiguration()으로 App ID와 사용자 ID를 지정한 뒤 엽니다. DRM 설정은 빠뜨릴 수 없는 단계입니다.

  5. Callback URL 서버 연결

    콘솔에 Callback URL을 등록하고 접근 권한 검사와 진행 상태 보고에 응답할 서버를 준비합니다. 2026년 8월 버전부터 진행 상태에 변화가 없으면 진행 보고 호출을 생략합니다.

의존성은 SDK 업데이트에 따라 바뀔 수 있습니다. 2026년 1월 디버깅 프록시 방어가 들어간 버전은 media3-datasource-okhttp 추가를 요구했으니 업데이트 전에 변경 이력을 확인하세요. 전체 일정은 도입 실행 가이드, 웹 연동과의 비교는 개발자 안내에 있습니다.

Feature Table

Android SDK 기능과 설정

재생 화면 설정은 MediaPlayerActivityConfiguration에 모으고, 영상별 시청 규칙은 MediaItem에 지정합니다.

기능내용설정
시청 규칙건너뛰기 금지, 배속 금지. 기본값은 둘 다 허용setSeekable, setDisablePlaybackRate
재생 환경백그라운드 재생 기본 꺼짐, 화면 속 화면·셀룰러 데이터 기본 허용, 화면 방향 고정MediaPlayerActivityConfiguration
배속0.1~4.0배, 배속 중 음정 유지defaultPlaybackRate, preservesPitch
자막WebVTT·SRT·SMI 다중 선택, 크기·색·배경·위치·좌우 여백subtitleTextSize 등
화면확대·축소 50~800%, 화면 크기 모드 5종videoZoom
재생 목록여러 차시 연속 재생, 차시마다 멈춤 선택pauseAtEndOfMediaItems
다운로드기본 3개 동시, 일시 정지·재개·삭제, 자막 함께 저장DownloadManager
오프라인재생 기한 지정, 기한이 지나면 오프라인 권한 만료 오류offlineAccessPeriod
UI 구성기본 화면, 앱 화면 안 Fragment, 뷰 상속 커스텀MediaPlayerBaseFragment, MediaPlayerBaseView

각 기능이 수강 운영에서 어떤 의미인지는 플레이어 기능에서 이어서 볼 수 있습니다.

Android Security

Android에서 따로 확인할 보안 항목

워터마크 설정 구조와 루팅·앱 플레이어 감지는 모바일 SDK 문서 중 Android에만 있습니다.

  • Watermark

    워터마크 설정

    문구, 글자색(hex), 불투명도와 크기(0.0~1.0), 표시 유지 시간과 출력 주기를 정합니다. 앱은 현재 적용된 설정을 currentWatermarkSettings로 읽습니다.

    • 고정 5곳: 네 모서리와 가운데
    • 영역 무작위 6곳: 상단·하단 각 3영역
    • 전체 영역 무작위 1가지
  • Device Check

    루팅·앱 플레이어 감지

    기기가 루팅됐거나 앱 플레이어가 감지되면 onDeviceRootedOrAppPlayerDetected()가 호출됩니다. 앱은 이 메서드를 재정의해 재생 중단 같은 대응을 넣습니다. 2025년 1월 버전에서 앱 플레이어 차단 로직이 개선됐습니다.

  • Capture & Proxy

    녹화 차단과 통신 보호

    녹화·캡처 차단은 2024년 4월에 추가됐고, 2026년 6월에는 오프라인 재생 중 녹화 차단 문제가 고쳐졌습니다. 2026년 1월 디버깅 프록시 방어, 2월 다운로드 파일의 DRM 키 저장 방식 개선이 이어졌습니다.

    보안 기능 전체 보기

재생 거부 원인은 MediaPlayerException 하위 예외 17종으로 구분됩니다. 원인별 안내 문구를 출시 전에 정해 두기를 권합니다.

Events

운영 데이터로 쓰는 이벤트

앱 쪽 이벤트는 고객사 앱이 직접 받고, 서버 쪽 보고는 Callback URL로 들어옵니다. 두 기록을 함께 보면 진도와 이탈 원인을 맞춰 볼 수 있습니다.

이벤트받는 정보운영 활용 예
PlaybackFinish미디어, 마지막 위치, 길이, 종료 원인(끝까지 재생·오류·사용자 종료)완강과 중도 이탈 구분
PositionDiscontinuity이동 전 위치와 이동 후 위치건너뛴 구간 기록
RateChange바뀐 재생 속도배속 시청 기록
ACTION_PLAYBACK_FINISHED미디어 uri, 재생 위치, 전체 길이, 종료 이유브로드캐스트 수신기에서 종료 처리
DownloadManager.Listener항목 추가·삭제, 상태 변경, 진행률다운로드함 화면과 이력

서버 쪽 보고로 진도율을 계산하는 방법은 진도 데이터 설계에서 다룹니다.

Android 도입 FAQ

  • 이미 Media3로 만든 플레이어가 있습니다. 그대로 쓸 수 있나요?

    Android SDK는 Jetpack Media3 기반이라 Media3 기능을 그대로 씁니다. 직접 만든 Player를 MediaPlayer(innerPlayer)로 감싸 등록할 수 있고, 자막은 Media3의 setSubtitleConfigurations()로 붙입니다.

  • 다운로드 파일은 어디에 저장되나요?

    DownloadManager의 downloadsUri가 최상위 폴더이고, 항목별 상대 경로는 displayPath로 확인합니다. 저장소 선택 기능은 2024년 4월에 추가됐습니다. SD 카드가 없을 때와 저장 공간이 부족할 때는 실패 사유가 따로 구분됩니다.

  • 빌드할 때 Compile SDK 버전 오류가 납니다.

    Project Structure 창의 Modules 탭에서 Compile Sdk Version을 맞게 고칩니다. 문서 FAQ에 화면과 함께 정리된 사례입니다.

  • 업데이트는 어떻게 따라가나요?

    SDK와 샘플은 문서의 최신 버전 링크로 받습니다. 변경 이력에는 2023년 12월 첫 버전부터 2026년 10월까지 68건이 있고, 2026년에만 16건입니다. 웹 강의실에서 재생하는 PC 흐름은 Windows·macOS 페이지를 보세요.

Get Started

PlaynPlay 도입을 위한
기술적 지원과 서비스를 제공합니다.

제품 문의부터 데모 시연까지, 모든 지원을 위해 세일즈 및 기술 지원 팀이 준비되어 있습니다.

  • 제품 및 도입 문의

    도입 범위, 일정, 견적을 상담합니다. 서비스 형태와 사용자 규모를 알려주시면 맞는 연동 방식과 보안 설정을 제안합니다.

  • Trial 신청

    PlaynPlay의 기능을 먼저 테스트해 보세요. 트라이얼 기간 동안 귀사의 제품과 PlaynPlay를 연동하고 성능과 기능을 직접 검증할 수 있습니다.

  • PlaynPlay 기술 문의

    SDK 연동, Callback URL 설계, DRM 패키징 중에 생기는 질문에 기술팀이 답합니다. 공개된 개발 문서와 샘플 프로젝트도 함께 확인하세요.