Installation

Installing the ByteArk Player SDK for Android takes a few more steps than the other platforms, because the SDK is hosted on a private GitLab Maven Registry. This page walks you through setting up your project step by step, from adding the tokens to requesting a License Key.

Note

Before you start, your project should have:

• JDK 17 or newer
• compileSdk 37 and minSdk 24
• Two GitLab Private Tokens (for ByteArk Player and ByteArk Lighthouse)
• A ByteArk License Key (see step 5)

1. Add your Private Tokens to local.properties

The SDK is hosted on a private GitLab Maven Registry, so you need a token to authenticate before Gradle can download it. Add both tokens to the local.properties file at your project root.

gitLabByteArkPlayerPrivateToken=<YOUR_PLAYER_TOKEN>
gitLabByteArkLighthousePrivateToken=<YOUR_LIGHTHOUSE_TOKEN>

Caution

local.properties contains secret tokens. Never commit it to git. It's usually already listed in .gitignore.

2. Configure the GitLab Maven Registry in settings.gradle.kts

ByteArk Player isn't available on google() or mavenCentral(), so you need to tell Gradle where to fetch it. In the dependencyResolutionManagement block, read the tokens from local.properties, then point at the GitLab Maven Registry and attach the token as a Private-Token header.

dependencyResolutionManagement {
    // read tokens from 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 that builds a GitLab Maven repo with a 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 {
        // add these to the existing repositories block
        maven { setUrl("https://raw.githubusercontent.com/NielsenDigitalSDK/nielsenappsdk-android/master/") } // Nielsen
        gitlabMaven(1158, playerToken)       // ByteArk Player
        gitlabMaven(1138, lighthouseToken)   // Lighthouse
    }
}

Note

Click Sync Now in Android Studio after every Gradle change.

3. Enable desugaring and add the dependency in app/build.gradle.kts

The SDK uses Java 8+ APIs that aren't available on older Android devices (minSdk 24), so enable coreLibraryDesugaring to backport them. Then add a single SDK dependency. Media3, IMA, Nielsen, Lighthouse, Ktor, Glide, and the rest are pulled in transitively from byteark-player-library, so you don't declare them again.

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")  // the core SDK
}

Note

Click Sync Now again after editing this file.

4. Configure AndroidManifest.xml

Add the permissions at the <manifest> level, enable usesCleartextTraffic, and declare the media session <service>. Here's what each part does:

• INTERNET and ACCESS_NETWORK_STATE: stream video
• FOREGROUND_SERVICE: enable background playback
• <service>: the player's media session; without it, background playback and notifications won't work

<!-- these 3 permissions must be at the <manifest> level only, never inside <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"
    ... >
    <!-- required for media session and background playback -->
    <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>
    <!-- only when using Ads or 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>

Caution

usesCleartextTraffic="true" is required when streaming over http, so Android doesn't block the connection. If all your videos are https, you can skip it.

Note

The two <meta-data> entries are only needed when using Ads or Google Chromecast. Skip them otherwise.

5. Request a License Key

The ByteArk Player SDK for Android requires a License Key to run. Contact sales@byteark.com to request a License Key for your project.

The License Key is used when building ByteArkPlayerBuilder via withLicenseKey(...).

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

Caution

If you don't provide a License Key when creating the player, the app will crash as soon as playback starts.

Next steps

Once the SDK is installed, the next step is rendering the player in your app.

• Using the SDK: walkthrough for setting up ByteArkPlayerFragment
• Options: all builder methods and setting objects
• API Reference: the full ByteArkPlayerFragmentController interface