ByteArk Documentation

# ByteArk Lighthouse SDK for Android

ByteArk Lighthouse SDK to collect video viewing statistics data and user behavior from the Client-side. The results will be processed and summarize by ByteArk sytem for more detailed statistics and video viewing behavior. The SDK support standard Android Players including Media3, Exo-player, and Custom Players developed in-house.

# Status

  • SDK version 0.2.6 is the latest stable version released.

# Compatibility

  • ByteArk Lighthouse SDK requires a minimum API level of version 21.
  • ByteArk Lighthouse SDK requires Compile SDK version 32 onwards.

# Installing ByteArk Lighthouse SDK

For an example of Source code for integrating ByteArk Lighthouse SDK on the Android Platform, see this Repository (opens new window) นี้

# Setting up Dependency

Since ByteArk Lighthouse SDK is uploaded to a Private Maven registry, additional setup is required for using the dependency as follows:

  1. Configure settings.gradle to add ByteArk maven to the 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)
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

credentials will be generated by the ByteArk team.

  1. Add Lighthouse SDK dependency in build.gradle for Lighthouse SDK Native dependency.
def lighthouse_sdk_native_version = "0.2.6"
implementation "com.byteark.lighthouse:lighthouse-native-sdk:$lighthouse_sdk_native_version"
1
2
3
  1. Add Network Permission in AndroidManifest.xml.
<uses-permission android:name="android.permission.INTERNET"/>
1

# Setup and Using the SDK

  1. Create a PlayerDataSource by implementing IPlayerDataSource to establish a channel for pulling the necessary data for Analytics from the 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?
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
  1. Create Lighthouse SDK Config using LighthouseNativeSDKConfigBuilder, which requires parameters such as:
  • PlayerDataSource created in step 1.
  • Context of the Activity hosting the Player.
val dataSource = PlayerDataSource(player)
val configBuilder = LighthouseNativeSDKConfigBuilder(dataSource,"YOUR_PROJECT_ID", context)
1
2
3
  1. Create and add Playback Metadata (Optional).

Add PlaybackMetadata using 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()
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

Add PlaybackMetadata to LighthouseNativeSDKConfig using:

configBuilder.playbackMetaData(metadata)
1

More details on Metadata are available here: Metadata Details.

  1. Create LighthouseNativeSDKConfig using build() function of LighthouseNativeSDKConfigBuilder.
val config = configBuilder.build()
1
  1. Create LighthouseNativeSDK, which requires parameters:
  • PlayerDataSource created in step 1.
  • LighthouseNativeSDKConfig created in step 4.
val lighthouseSDK = LighthouseNativeSDK(dataSource, config)
1
  1. Call the setTimers() function after creating lighthouseSDK.
lighthouseSDK.setTimers()
1
  1. Use functions from lighthouseSDK to collect user video playback data based on Player Event.
player's event lighthouse sdk's method
ready playerReady()
loadStart loadStart()
loadedData 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()
playback resize playerResize()
playback video resize resolutionChange()
end playerEnd()
ad request adRequest()
ad complete adComplete()
ad skipped adSkipped()
ad click adClick()
ad error adError()
ad impression adImpression()

Further details on Player Event data are available here: Player Event Details.

Remark:

  • Normally, Ad Events are not provided by Exo Player. To use Ad Events, implement ImaAdsLoader yourself to track the state of ad playback.
  • ByteArk Native Player provide function for tracking ad events, contact sales for more information.
  1. When the Player Instance is destroyed or the Player activity is stopped, call the destroy() function to stop using Lighthouse.
lighthouseSDK.destroy()
1
  1. When the video source changes, call the destroy() function to end the session and create a new Lighthouse instance to start a new session.
lighthouseSDK.destroy()
initLighthouse() // Function to init Lighthouse instance
1
2
  1. When the Application enters the Background state and is not playing in the background, call the flush() function to send Analytic data to the Server.
lighthouseSDK.flush()
1

← iOS →

Pricing Contact Terms of Service