ByteArk Documentation

# ByteArk Lighthouse SDK for iOS

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 players developed based on AV Player.

# Status

  • SDK version 0.2.6 is the latest stable version released.

# Compatibility

  • ByteArk Lighthouse SDK Support iOS 13+

# Installing ByteArk Lighthouse SDK

สFor an example of Source code for integrating ByteArk Lighthouse SDK on the iOS Platform, see more in this Repository (opens new window).

# Installing ByteArk Lighthouse SDK Library

ByteArk Lighthouse SDK can be installed through the following methods:

Use Swift Package Manager to install Lighthouse SDK Native.

  1. In Xcode, go to File > Add Packages.
  2. Enter the URL https://github.com/byteark/lighthouse-sdk-native-ios.git.
  3. Choose the version of the SDK.
  4. Once completed, Xcode will download the Package in the Background.

# CocoaPods

Using CocoaPods to install Lighthouse SDK Native.

More information about CocoaPods (opens new window).

CocoaPods can be installed by running this command in the Terminal:

$ gem install cocoapods
1

Install Lighthouse SDK Native with Cocoapods:

  1. Add the dependency to your Podfile
lighthouse_version = 'v0.2.6'
pod 'LighthouseNativeSDK', :git => 'git@github.com:byteark/lighthouse-sdk-native-ios.git', :tag => lighthouse_version
1
2
3
  1. Install the dependency with the install command
$ pod install
1

Note: Note: Cocoapods will install the SDK from a Github private repository using SSH Key. If you haven't set up an SSH Key for your current Github user, please follow these steps: Add SSH Key for Github User (opens new window).

# Installing and Using the SDK

  1. Create a PlayerDataSource by implementing IPlayerDataSource to establish a channel for pulling necessary data for Analytics from the Player.
class PlayerDataSource: IPlayerDataSource {
  /// - Returns: your player name, to distinguish platforms.
  ///   e.g. byteark-player-ios, byteark-player-android, avplayer, exoplayer etc..., 
  ///   EMPTY STRING IS NOT ALLOWED
  func playerName() -> String {
    // TODO:
  }
  /// - Returns: Your player version
  ///   EMPTY STRING IS NOT ALLOWED
  func playerVersion() -> String {
    // TODO:
  }
  /// - Returns: An Video Key from ByteArk e.g. RI2PimuHxDXw)
  ///   EMPTY STRING IS NOT ALLOWED
  func mediaId() -> String {
    // TODO:
  }
  /// - Returns: current media's title or null
  func mediaTitle() -> String? {
    // TODO: 
  }
  /// - Returns: current media's subtitle (short description) or null
  func mediaSubtitle() -> String? {
    // TODO:
  }
  /// - Returns: MediaTypes.live or MediaTypes.vod
  func mediaType() -> MediaTypes {
    // TODO:
  }
  /// - Returns: media's URL
  ///   EMPTY STRING IS NOT ALLOWED
  func mediaUrl() -> String {
    // TODO:
  }
  /// - Returns: current media's cover image url string or null
  func coverImageUrl() -> String? {
    // TODO:
  }
  /// Returns: player's current playback time (seconds) when video is VOD or null when video is live stream
  func currentTime() -> KotlinLong? {
    // TODO:
  }
  /// - Returns: video's duration (seconds) e.g. 0 when video is live stream
  func duration() -> KotlinLong? {
    // TODO:
  }
  /// - Returns: true when video live stream, false when video is VOD
  func isLive() -> Bool {
    // TODO:
  }
  /// - Returns: how autoplay handled, "autoplay" or "manual" or null if unknown.
  func playbackAutoPlay() -> String? {
    // TODO:
  }
  /// - Returns: current playback rate, such as 1.0 for normal speed.
  func playbackRate() -> Float {
    // TODO:
  }
  /// - Returns: current media resolution name, such as "1080p" or null
  func playbackResolution() -> String? {
    // TODO:
  }
  /// - Returns:
  ///   - ResolutionModes.auto when your player automatic select resolution
  ///   - ResolutionModes.manual when user manual selected resolution
  ///   - null
  func playbackResolutionMode() -> ResolutionModes? {
    // TODO:
  }
  /// - Returns: calculated bandwidth estimate when download video or null
  func playbackBandwidthEstimate() -> KotlinFloat? {
    // TODO:
  }
  /// - Returns: calculated current buffer health or null
  func bufferHealth() -> KotlinFloat? {
    // TODO:
  }
}
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
  1. Create Lighthouse SDK Config Builder using LighthouseNativeSDKConfigBuilder, which requires parameters such as:
  • PlayerDataSource created in step 1.
  • projectId of your project.
let playerDataSource = PlayerDataSource(with: player)
let configBuilder = LighthouseNativeSDKConfigBuilder(
  playerDataSource: playerDataSource,
  projectId: "YOUR_PROJECT_ID",
  )
1
2
3
4
5
6
  1. Create and add Playback Metadata (Optional)

PlaybackMetadata can be created using PlaybackMetadataBuilder

let 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)
let metadata = 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

Then add PlaybackMetadata to LighthouseNativeSDKConfig using:

configBuilder.playbackMetaData(metadata)
1

More details on Metadata are available here: Metadata Details.

  1. Create LighthouseNativeSDKConfig from LighthouseNativeSDKConfigBuilder.
let config = configBuilder.build()
1
  1. Create LighthouseNativeSDK, which requires parameters such as:
  • PlayerDataSource created in step 1.
  • Config created in step 4.
let lighthouseSDK = LighthouseNativeSDK(playerDataSource: playerDataSource, config: 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.

  1. When the Player Instance is destroyed, 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
lighthouseSDK.flush()
1

←

Pricing Contact Terms of Service