ByteArk Lighthouse SDK สำหรับ Android

ByteArk Lighthouse SDK รองรับการเชื่อมต่อกับระบบ ByteArk Lighthouse เพื่อเก็บข้อมูลสถิติการรับชมวิดีโอจากทางฝั่ง Client-side ซึ่งจะทำให้ได้ข้อมูลสถิติ และ พฤติกรรมการดูวิดีโอที่ละเอียดขึ้น โดยสามารถ Support Player มาตรฐานของ Android ได้ทั้ง Media3, Exo-player รวมทั้ง Custom Player ที่พัฒนาด้วยตนเอง

สถานะ

• SDK เวอร์ชั่น 0.2.6 เป็น SDK เวอร์ชั่นเสถียรล่าสุดที่ถูกปล่อย

ความเข้ากันได้

• ByteArk Lighthouse SDK ต้องการ API level ขั้นต่ำเวอร์ชั่น 21
• ByteArk Lighthouse SDK ต้องการ Compile SDK เวอร์ชั่น 32 เป็นต้นไป

การติดตั้ง ByteArk Lighthouse SDK

สำหรับตัวอย่าง Source code การ Integrate ByteArk Lighthouse SDK ของ Platform Android สามารถดูตัวอย่างได้ที่ Repository (opens new window) นี้

การตั้งค่า Dependency

เนื่องด้วย ByteArk Lighthouse SDK ถูกอัพโหลด Private Maven registry การเรียนใช้ dependency จึงต้องมีการตั้งค่าเพิ่มเติมดังนี้

1. ตั้งค่า settings.gradle เพื่อเพิ่ม maven ของ ByteArk เข้าสู่ Project

maven {
  name "GitLab"
  url = "https://gitlab.inox.co.th/api/v4/projects/1138/packages/maven"
  credentials(HttpHeaderCredentials) {
    name = "Private-Token"
    value = "YOUR_PRIVATE_TOKEN"
  }
  authentication {
    header(HttpHeaderAuthentication)
  }
}

โดย credentials จะถูก Generate ให้โดยทีม ByteArk

2. เพิ่ม Lighthouse SDK dependency ใน build.gradle Lighthouse SDK Native dependency

def lighthouse_sdk_native_version = "0.2.6"
implementation "com.byteark.lighthouse:lighthouse-native-sdk:$lighthouse_sdk_native_version"

3. เพิ่ม Network Permission ใน AndroidManifest.xml

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

การติดตั้งและใช้งาน SDK

1. สร้าง PlayerDataSource โดยการ Implement IPlayerDataSource เพื่อสร้างช่องทางในการดึงข้อมูลที่จำเป็นสำหรับการทำ Analytic จาก Player

class PlayerDataSource(): IPlayerDataSource {
    /**
     * @return the current media url string, Empty string is NOT ALLOWED
     */
    fun mediaUrl(): String
    /**
     * @return the current media type (live or vod)
     */
    fun mediaType(): MediaTypes
    /**
     * @return boolean indicated that current media is live streaming
     */
    fun isLive(): Boolean
    /**
     * @return the player name e.g. byteark-player-ios, byteark-player-android, avplayer, exoplayer etc..., Empty string is NOT ALLOWED
     */
    fun playerName(): String
    /**
     * @return the player version, Empty string is NOT ALLOWED
     */
    fun playerVersion(): String
    /**
     * @return autoplay mode or null
     */
    fun playbackAutoPlay(): String?
    /**
     * @return current playback resolution string or null
     */
    fun playbackResolution(): String?
    /**
     * @return current playback resolution mode (auto or manual)
     */
    fun playbackResolutionMode(): ResolutionModes?
    /**
     * @return calculate bandwidth estimate or null
     */
    fun playbackBandwidthEstimate(): Float?
    /**
     * @return current time in seconds or null when current media is live streaming
     */
    fun currentTime(): Long?
    /**
     * @return current media's duration in seconds or 0 when current media is live streaming
     */
    fun duration(): Long?
    /**
     * @return calculate current buffer health or null
     */
    fun bufferHealth(): Float?
    /**
     * @return current mediaId (an Video Key from ByteArk), Empty string is NOT ALLOWED
     */
    fun mediaId(): String
    /**
     * @return current media's title
     */
    fun mediaTitle(): String
    /**
     *@return current media's subtitle (short description) or null
     */
    fun mediaSubtitle(): String?
    /**
     * @return current media's cover image url string or null
     */
    fun coverImageUrl(): String?
    /**
     * @return current playback rate, normal speed = 1
     */
    fun playbackRate(): Float
    /**
     * @return current player component width
     */
    fun playerWidth(): Long?
    /**
     * @return current player component height
     */
    fun playerHeight(): Long?
    /**
     * @return current video width
     */
    fun videoWidth(): Long?
    /**
     * @return current video height
     */
    fun videHeight(): Long?
}

2. สร้าง Lighthouse SDK Config โดย การใช้ LighthouseNativeSDKConfigBuilder ซึ่งต้องการ Parameter ได้แก่

• PlayerDataSource ที่ถูกสร้างจากขั้นตอนที่ 1
• Context ของ Activity ที่ Host Player

val dataSource = PlayerDataSource(player)
val configBuilder = LighthouseNativeSDKConfigBuilder(dataSource,"YOUR_PROJECT_ID", context)

3. สร้างและเพิ่ม Metadata ของ Playback ที่กำลังเล่น (Optional)

สามารถเพิ่มข้อมูล PlaybackMetadata ให้ Playback โดย การใช้ PlaybackMetadataBuilder

val metadataBuilder = PlaybackMetadataBuilder()
metadataBuilder.userId(USER_ID)
metadataBuilder.age(AGE)
metadataBuilder.country(COUNTRY)
metadataBuilder.city(CITY)
metadataBuilder.lat(LAT)
metadataBuilder.long(LONG)
metadataBuilder.gender(GENDER)
metadataBuilder.nationality(NATIONALITY)
metadataBuilder.subscriptionPlan(SUBSCRIPTION_PLAN)
metadataBuilder.accountCreationDate(ACCOUNT_CREATION_DATE)
metadataBuilder.videoTitle(videoItem.title)
metadataBuilder.seriesId(SERIES_ID)
metadataBuilder.seriesTitle(SERIES_TITLE)
metadataBuilder.season(SEASON)
metadataBuilder.episode(EPISODE)
metadataBuilder.subEpisode(SUB_EPISODE)
metadataBuilder.duration(DURATION)
metadataBuilder.publishedDate(PUBLISHED_DATE)
metadataBuilder.genres(GENRES)
metadataBuilder.rating(RATING)
metadataBuilder.d1(D1)
metadataBuilder.d2(D2)
metadataBuilder.d3(D3)
metadataBuilder.d4(D4)
metadataBuilder.d5(D5)
metadataBuilder.d6(D6)
metadataBuilder.d7(D7)
metadataBuilder.d8(D8)
metadataBuilder.d9(D9)
metadataBuilder.d10(D10)
metadataBuilder.build()

จากนั้นสามารถเพิ่ม PlaybackMetadata แนบไปร่วมกับ LighthouseNativeSDKConfig ได้โดยการใช้ฟังก์ชั่น

configBuilder.playbackMetaData(metadata)

โดยรายละเอียดของข้อมูลสามารถศึกษาต่อได้ที่นี่ รายละเอียดข้อมูล Metadata

4. สร้าง LighthouseNativeSDKConfig จาก LighthouseNativeSDKConfigBuilder

val config = configBuilder.build()

5. สร้าง LighthouseNativeSDK ซึ่งต้องการ Parameter ได้แก่

• PlayerDataSource ที่ถูกสร้างจากขั้นตอนที่ 1
• Config ที่สร้างจากขั้นตอนที่ 4

val lighthouseSDK = LighthouseNativeSDK(dataSource, config)

6. สั่งฟังก์ชั่น setTimers หลังจากสร้าง lighthouseSDK

lighthouseSDK.setTimers()

7. สั่งงาน Function จาก lighthouseSDK เพื่อเก็บข้อมูลการเล่นวิดีโอของผู้ใช้โดยอิงจาก Player Event และ Ad Event ตามตารางข้างต้นนี้

player's event	lighthouse sdk's method
ready	playerReady()
load start	loadStart()
loaded data	loadedData()
first play	firstPlayStart()
play	playerPlay()
pause	playerPause()
buffer start	bufferStart()
buffer stop	bufferStop()
seek start	seekStart()
seek stop	seekStop()
error	error()
time update	timeUpdate()
playback rate change	rateChange()
resolution change	resolutionChange()
player's resize	playerResize()
end	playerEnd()
exit	exit()

player's ad event	lighthouse sdk's method
ad request	adRequest()
ad load	adLoad()
ad start	adStart()
ad first quartile	adFirstQuartile()
ad mid point	adMidPoint()
ad third quartile	adThirdQuartile()
ad complete	adComplete()
ad all complete	adAllComplete()
ad skipped	adSkipped()
ad click	adClick()
ad error	adError()
ad impression	adImpression()

โดยรายละเอียดของข้อมูลสามารถศึกษาต่อได้ที่นี่ รายละเอียดข้อมูล Player Event

Remark:

• โดยปกติ Ad Event จะไม่ถูกออกมาให้จาก Exo Player หากต้องการใช้งาน Ad Event จะต้อง Implement ImaAdsLoader เองเพื่อ Track State ของการเล่นโฆษณา
• หากต้องการใช้งาน Ad Event สามารถใช้ Feature จาก ByteArk Native Player ได้, สามารถติดต่อทีมงานเพื่อขอข้อมูลเพิ่มเติม

8. เมื่อ Player Instance ถูก destroy หรือ หยุดใช้ Player activity, สั่งฟังก์ชั่น destroy() เพื่อหยุดใช้งาน Lighthouse

lighthouseSDK.destroy()

9. เมื่อ Source ของวิดีโอถูกเปลี่ยน สั่งฟังก์ชั่น destroy() เพื่อจบการทำงานของ Session และสร้าง Instance ของ Lighthouse ใหม่เพื่อเริ่ม Session ใหม่

lighthouseSDK.destroy()
initLighthouse() // Function to init Lighthouse instance

10. เมื่อ Application เข้าสู่ Background state และไม่มีการเล่นใน Background สั่งงานฟังก์ชั่น flush() เพื่อส่งข้อมูล Analytic เข้าสู่ Server

lighthouseSDK.flush()