การติดตั้ง ByteArk Player SDK for Android

การติดตั้ง ByteArk Player SDK for Android มีขั้นตอนมากกว่าแพลตฟอร์มอื่นเล็กน้อย เนื่องจาก SDK ถูกเก็บไว้บน GitLab Private Maven Registry หน้านี้จะพาคุณตั้งค่าโปรเจกต์ทีละขั้นตอน ตั้งแต่การเพิ่ม token ไปจนถึงการขอ License Key

Note

ก่อนเริ่มติดตั้ง โปรเจกต์ของคุณควรมีสิ่งต่อไปนี้:

• JDK 17 ขึ้นไป
• compileSdk 37 และ minSdk 24
• GitLab Private Token 2 ตัว (สำหรับ ByteArk Player และ ByteArk Lighthouse)
• ByteArk License Key (ดูขั้นตอนที่ 5)

1. เพิ่ม Private Token ใน local.properties

เนื่องจาก SDK ถูกเก็บไว้บน GitLab Private Maven Registry การจะดาวน์โหลด SDK ได้จึงต้องยืนยันตัวตนด้วย token ก่อน ให้เพิ่ม token ทั้งสองตัวลงในไฟล์ local.properties ที่ root ของโปรเจกต์

gitLabByteArkPlayerPrivateToken=<YOUR_PLAYER_TOKEN>
gitLabByteArkLighthousePrivateToken=<YOUR_LIGHTHOUSE_TOKEN>

ข้อควรระวัง

ไฟล์ local.properties มีข้อมูล token ที่เป็นความลับ อย่า commit ไฟล์นี้ขึ้น git โดยปกติไฟล์นี้จะถูกระบุไว้ใน .gitignore อยู่แล้ว

2. ตั้งค่า GitLab Maven Registry ใน settings.gradle.kts

ByteArk Player เป็น dependency ที่ไม่มีอยู่บน google() หรือ mavenCentral() คุณจึงต้องบอก Gradle ว่าจะไปดาวน์โหลด SDK จากที่ไหน โดยเพิ่มโค้ดในบล็อก dependencyResolutionManagement เพื่ออ่านค่า token จาก local.properties แล้วชี้ไปที่ GitLab Maven Registry พร้อมแนบ token เป็น Private-Token header

dependencyResolutionManagement {
    // อ่าน token จาก local.properties
    val localProperties = java.util.Properties().apply {
        val f = file("local.properties")
        if (f.exists()) f.inputStream().use { load(it) }
    }
    val playerToken = localProperties.getProperty("gitLabByteArkPlayerPrivateToken") ?: ""
    val lighthouseToken = localProperties.getProperty("gitLabByteArkLighthousePrivateToken") ?: ""
    // helper สำหรับสร้าง GitLab Maven repo พร้อมแนบ Private-Token header
    fun RepositoryHandler.gitlabMaven(projectId: Int, token: String) = maven {
        url = uri("https://gitlab.inox.co.th/api/v4/projects/$projectId/packages/maven")
        credentials(HttpHeaderCredentials::class) { name = "Private-Token"; value = token }
        authentication { create<HttpHeaderAuthentication>("header") }
    }
    repositories {
        // เพิ่ม repo เหล่านี้ในบล็อก repositories เดิม
        maven { setUrl("https://raw.githubusercontent.com/NielsenDigitalSDK/nielsenappsdk-android/master/") } // Nielsen
        gitlabMaven(1158, playerToken)       // ByteArk Player
        gitlabMaven(1138, lighthouseToken)   // Lighthouse
    }
}

Note

หลังจากแก้ไขไฟล์ Gradle ทุกครั้ง อย่าลืมกด Sync Now ใน Android Studio

3. เปิด desugaring และเพิ่ม dependency ใน app/build.gradle.kts

SDK เรียกใช้ Java 8+ API ที่ไม่มีในอุปกรณ์ Android รุ่นเก่า (minSdk 24) คุณจึงต้องเปิด coreLibraryDesugaring เพื่อ backport API เหล่านั้นลงมา จากนั้นเพิ่ม dependency ของ SDK เพียงตัวเดียว ส่วน Media3, IMA, Nielsen, Lighthouse, Ktor, Glide และอื่นๆ จะถูกดึงมาแบบ transitive จาก byteark-player-library โดยอัตโนมัติ คุณไม่ต้องประกาศซ้ำ

android {
    compileOptions {
        isCoreLibraryDesugaringEnabled = true
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }
}
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
    implementation("com.byteark.android:byteark-player-library:1.2.14")  // ตัว SDK หลัก
}

Note

กด Sync Now อีกครั้งหลังแก้ไขไฟล์นี้

4. ตั้งค่า AndroidManifest.xml

เพิ่ม permission ที่ระดับ <manifest>, เปิด usesCleartextTraffic และประกาศ <service> สำหรับ media session โดยแต่ละส่วนมีหน้าที่ดังนี้

• INTERNET และ ACCESS_NETWORK_STATE: สำหรับสตรีมวิดีโอ
• FOREGROUND_SERVICE: สำหรับเล่นวิดีโอแบบเบื้องหลัง
• <service>: คือ media session ของ Player หากไม่ประกาศ จะเล่นแบบเบื้องหลังและแสดง notification ไม่ได้

<!-- permission ทั้ง 3 ตัวต้องอยู่ที่ระดับ <manifest> เท่านั้น ห้ามอยู่ใน <application> -->
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
<application
    android:usesCleartextTraffic="true"
    ... >
    <!-- จำเป็นสำหรับ media session และการเล่นเบื้องหลัง -->
    <service
        android:name="com.byteark.bytearkplayercore.handler.exoplayer.service.ByteArkPlayerService"
        android:enabled="true" android:exported="true">
        <intent-filter>
            <action android:name="androidx.media3.session.MediaLibraryService"/>
            <action android:name="android.media.browse.MediaBrowserService" />
        </intent-filter>
    </service>
    <!-- เพิ่มเฉพาะเมื่อใช้ Ads หรือ Google Chromecast -->
    <meta-data android:name="com.google.android.gms.ads.APPLICATION_ID"
        android:value="ca-app-pub-3940256099942544~3347511713"/>
    <meta-data android:name="com.google.android.gms.cast.framework.OPTIONS_PROVIDER_CLASS_NAME"
        android:value="com.byteark.bytearkplayercore.handler.exoplayer.cast.ByteArkCastOptions"/>
</application>

ข้อควรระวัง

usesCleartextTraffic="true" จำเป็นเมื่อสตรีมผ่าน http เพื่อไม่ให้ Android บล็อกการเชื่อมต่อ หากวิดีโอของคุณเป็น https ทั้งหมด สามารถข้ามการตั้งค่านี้ได้

Note

<meta-data> ทั้งสองตัวเพิ่มเฉพาะเมื่อใช้งาน Ads หรือ Google Chromecast เท่านั้น หากไม่ได้ใช้ สามารถข้ามได้

5. ขอ License Key

ByteArk Player SDK for Android ต้องใช้ License Key ในการเปิดใช้งาน กรุณาติดต่อ sales@byteark.com เพื่อขอ License Key สำหรับโปรเจกต์ของคุณ

License Key จะถูกนำไปใช้ตอนสร้าง ByteArkPlayerBuilder ผ่าน withLicenseKey(...)

val playerBuilder = ByteArkPlayerBuilder.Builder()
  .withContext(this)
  .withLicenseKey("<YOUR_LICENSE_KEY>")
  .withAutoPlay()
  .withControl()
  .build()