---
updatedAt: 2026-02-04T10:15:28.000Z
agentTools:
  siteIndex: https://developer.bitmovin.com/llms.txt
  projectIndex: https://developer.bitmovin.com/playback/llms.txt
---

# Getting Started

The following tutorial will walk you through adding the Bitmovin Player SDK to a new or existing Android Project. If you're migrating from ExoPlayer to Bitmovin Player, check out our [migration guide](https://developer.bitmovin.com/playback/docs/migrating-from-exoplayer-to-the-bitmovin-player) instead.

## Step 1: Add the SDK to your Project

### Add a Link to the Player SDK repository

Add a link to our release repository to your application's `settings.gradle.kts` file. In addition to that, the Google Maven repository is required.

```kotlin settings.gradle.kts
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://artifacts.bitmovin.com/artifactory/public-releases")
        }
    }
}
```

### Add the Dependency to the Project

Add the Bitmovin Player Android SDK as a dependency to your project as shown below, while replacing `{version-number}` with the desired SDK version number. The available SDK versions are listed in our [release notes](https://developer.bitmovin.com/playback/docs/release-notes-android).

```groovy >_
implementation("com.bitmovin.player:player:{version-number}")
```

## Step 2: Set up your Project

### Edit the manifest file

The Bitmovin Player license key and the necessary permissions have to be added to the manifest file. The license key should be added inside the `application` element.

```xml </>
<meta-data android:name="BITMOVIN_PLAYER_LICENSE_KEY" android:value="<PLAYER_LICENSE_KEY>" />
```

Alternatively, you can specify the license key in the PlayerConfig:

```kotlin
val playerConfig = PlayerConfig(key = "<PLAYER_LICENSE_KEY>")
```

The player requires the `INTERNET` permission. The following line should be added inside the `manifest` element.

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

## Step 3: Set up the Player

### Instantiate the Player (Quick Setup)

To get started quickly with the default Bitmovin Web UI, the PlayerView can be added to the layout:

```xml </>
<com.bitmovin.player.PlayerView
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:id="@+id/playerView"
        android:layout_alignParentTop="true"
        android:layout_alignParentLeft="true"
        android:layout_alignParentStart="true">
</com.bitmovin.player.PlayerView>
```

Then you need to create the source:

```kotlin
val url = "https://cdn.bitmovin.com/content/assets/art-of-motion-dash-hls-progressive/mpds/f08e80da-bf1d-4e3d-8899-f0f6155f6efa.mpd"
val sourceConfig = SourceConfig(url, SourceType.Dash) // or SourceConfig.fromUrl(url) to auto-detect the source type
val source = Source(sourceConfig)
```

Finally, get the player instance in the Activity and load the source into it:

```kotlin
val playerView = this.findViewById(R.id.playerView)
val player = playerView.player
player?.load(source)
```

*At the moment it is not possible to enable or configure Analytics with this variant.*

### Instantiate the Player (Advanced Setup)

For more elaborate workflows, e.g. specific configurations, analytics or a custom UI, the player can also be instantiated explicitly:

```kotlin
val playerConfig = PlayerConfig()
val analyticsConfig = AnalyticsConfig(licenseKey = "<ANALYTICS_LICENSE_KEY>")
val player = Player(context, playerConfig, AnalyticsPlayerConfig.Enabled(analyticsConfig))
```

For Java users the `PlayerFactory` might be more convenient:

```java
Player player = new PlayerBuilder(context)
                .setPlayerConfig(playerConfig)
                .configureAnalytics(analyticsConfig)
                .build()
```

This Player can then be attached to a PlayerView:

```kotlin
val playerView = this.findViewById(R.id.playerView)
playerView.player = player
```

Alternatively, a custom UI can be implemented. See the [corresponding sample](https://github.com/bitmovin/bitmovin-player-android-samples/tree/main/CustomUiKotlin) for details.

Finally, a source is created and loaded into the player. The `SourceMetadata` are optional and can be used to provide more context in the analytics events.

```kotlin
val url = "https://bitmovin-a.akamaihd.net/content/MI201109210084_1/mpds/f08e80da-bf1d-4e3d-8899-f0f6155f6efa.mpd"
val sourceConfig = SourceConfig(url, SourceType.Dash) // or SourceConfig.fromUrl(url) to auto-detect the source type
val sourceMetadata = SourceMetadata(title = "Art of Motion", customData1 = "sample data")
val source = Source(sourceConfig, AnalyticsSourceConfig.Enabled(sourceMetadata))
player.load(source)
```

Similar to before, Java users can use the `SourceFactory` to create a `Source`:

```java
Source source = new SourceBuilder(sourceConfig)
                .configureAnalytics(sourceMetadata)
                .build()
player.load(source);
```

### A note on threading

Both the [Player](https://cdn.bitmovin.com/player/android/3/docs/player-core/com.bitmovin.player.api/-player/index.html) and [Source](https://cdn.bitmovin.com/player/android/3/docs/player-core/com.bitmovin.player.api.source/-source/index.html) instances must be created and accessed on the application’s main thread.

## Step 4: Configure your Player and Analytics License

### Allowlist Application ID

In order to use the player with analytics in your app, you have to allowlist the application ID (package name) of your app. This is a security mechanism and protects your license from being used elsewhere.

Allowlisting can be done in the [Dashboard](https://bitmovin.com/dashboard/player/licenses) under **Player > Licenses** and **Analytics > Licenses**.

![](https://files.readme.io/dbfcc90-screenshot_dashboard_license.noinline-dea1b84725944aea4fe800228db07457.svg)

## Summary

In this tutorial you've learned how to add the Bitmovin Player Android SDK to your project, set up the player and analytics license, and how to configure and use the Player.

Next, you can

* browse our [API reference](https://cdn.bitmovin.com/player/android/3/docs/index.html).
* download fully working [examples](https://github.com/bitmovin/bitmovin-player-android-samples) and explore more features in our GitHub repository.
* choose additional platforms to deploy on in our [Getting Started Hub](https://bitmovin.com/dashboard/player/getting-started) and try our no-code wizards.
* get real-time insights into your Android Player via our [Analytics Dashboard](https://bitmovin.com/dashboard/analytics/audience).
* see if some of the questions you might have are answered in our [Community](https://community.bitmovin.com/) and ask your own!