Android and Android TV Integration

Peer5 integrates with Android very well and integration is straightforward and easy.

We have integrations for hybrid apps, PWAs, React Native apps and of course native Android applications. This document covers all forms of this integration. Android TV and set-top boxes are also supported in the SDK. If you have questions about integrating with set-top boxes or would like to discuss case studies and see if it makes sense for your business please do not hesitate to Chat with us or send us an email.

Non-Native Apps

Hybrid Application

Since a hybrid application is just an HTML5 application in disguise, Peer5 will work out of the box with hybrid applications. In the same page or view in which you initialize your video player - include the Peer5 scripts.

Delivery of P2P content will work on all Android versions from 5.0 and up (versions with WebRTC support).

React Native Application

Integration through React Native depends on whether you're performing video playback using an HTML5 player or a native player.

If you're using an HTML5 player, please follow the web integration instructions. For native playback, please follow the native application instructions below.

Progressive Web App

See our dedicated PWA docs.

Native Application

Peer5 has a thin native Android SDK that is embeddable in your native app. The Peer5 Android SDK works with any Android player although we recommend ExoPlayer which we've found to give good playback results.

Player requests for video segments (.ts files) are intercepted and instead of always serving them directly from HTTP, they are load balanced between HTTP and P2P.

Supported Technologies

Player: Any Android Player. Android Version Support: Jelly Bean 4.1 (API level 16), P2P Supported from Lollipop 5.0 (API level 21) Playback Technologies: HLS, DASH

Installation Instructions

It is always recommended to run the latest version of the SDK although older versions are also supported. If you prefer to pin the dependency to a specific version - use this format com.peer5.android:sdk:x.y.z. latest version can be seen in the Maven repo info

Gradle

1. In your project's build.gradle add the Peer5 SDK repository inside repositories:

• note - adding the repository to you app's build.gradle will cause build errors - it must be added to the project level file.

   allprojects {
      repositories {
         maven {
            url "https://sdk.peer5.com/android"
         }
   }

2. Add the SDK as a dependency to your application's build.gradle file under dependencies:

implementation "com.peer5.android:sdk:3.+"

---

Maven

1. in your pom.xml the the Peer5 SDK repository

    <repositories>
        <repository>
            <id>Peer5</id>
            <url>https://sdk.peer5.com/android</url>
        </repository>
    </repositories>

2. Add the SDK as a dependency (update x.x to the latest version)

    <dependencies>
        <dependency>
            <groupId>com.peer5.android</groupId>
            <artifactId>sdk</artifactId>
            <version>3.x.x</version>
        </dependency>
    </dependencies>

---

3. Register with Peer5 and get your Customer ID.

Add this metadata tag to your AndroidManifest.xml inside the <application> tag after all activities:

<meta-data android:value="Your-CustomerID-Goes-Here"
           android:name="com.peer5.ApiKey"/>

---

4. Before setting your player's stream url, switch it with a Peer5 url:

Java:

import com.peer5.sdk.Peer5Sdk;

String peer5Url = Peer5Sdk.getPeer5StreamUrl(url); // kotlin is similar

Full example with ExoPlayer:

String peer5Url = Peer5Sdk.getPeer5StreamUrl(m3u8Url.toString());
Uri peer5Uri = Uri.parse(peer5Url);

// In older versions of ExoPlayer: use `new HlsMediaSource` instead of HlsMediaSource.Factory 
HlsMediaSource source = new HlsMediaSource.Factory(mediaDataSourceFactory).createMediaSource(peer5Uri);
player.prepare(mediaSource);

---

5. Allow Cleartext (HTTP) traffic for 127.0.0.1 - (Android 9 and newer)

Starting Android 9 HTTP traffic is disabled by default. read more about this change here.
Without allowing HTTP for 127.0.0.1 this error might show up when trying to play:
Cleartext HTTP traffic to 127.0.0.1 not permitted.

Create file in res/xml/network_security_config.xml with content:

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">127.0.0.1</domain>
    </domain-config>
</network-security-config>

In AndroidManifest.xml add the android:networkSecurityConfig="@xml/network_security_config" attribute to the application tag

<?xml version="1.0" encoding="utf-8"?>
<manifest>
    <uses-permission android:name="android.permission.INTERNET" />
    <application
        android:networkSecurityConfig="@xml/network_security_config">

    </application>
</manifest>

Exo Player UX Plugin

We also provide a UX plugin for Exo player that reports playback metrics such as rebufferring etc. Supported Exo versions 2.5 - 2.11.

1. Add the plugin as dependency alongside the sdk

implementation "com.peer5.android:sdk:3.+"
implementation "com.peer5.android:exo-plugin:3.+"

1. Integrate every time a player instance is created

this.uxPlugin = new Peer5ExoUXPlugin(player, getApplicationContext());

// when player is released (destroyed)
this.uxPlugin.dispose();

---

That’s all that’s needed for you to get started!

Advanced Configuration

Disabling Auto Initialization

By default, the Peer5Sdk will initialize when the app starts automatically. This is preferable since it assures that the SDK is ready and optimized when video playback starts. In some cases you might want to opt out of this automatic behavior and initialize the SDK yourself.

The following explains how to disable the auto-init feature and initialize the SDK manually (Not recommended)

1. Add the following meta tag to AndroidManifest.xml inside <application> tag

<meta-data
    android:name="com.peer5.AutoInit"
    android:value="false" />

1. Initialize the SDK. It takes a couple of seconds for Peer5 to fully initialize and optimize, so init should be called before the actual playback takes place as early as possible.

Peer5Sdk.init(context)

⚠️ Important! ⚠️

Peer5Sdk.getPeer5StreamUrl() must not be called until the SDK is ready. To check if the SDK is ready call:

Peer5Sdk.isReady()

---

SDK FAQ

Q: How can I check that the SDK is integrated correctly?

A: Go to https://app.peer5.com/analytics and under “+Add Filter" select dimensions.platform.name and then enter 'Contains' and then "Android". After correct integration you should be seeing traffic there. Traffic may take several minutes to start appearing in the dashboard.

Q: How can I gradually deploy P2P with the SDK?

A: You can change the amount of traffic you’d like to go through peer-to-peer from your Peer5 dashboard at https://app.peer5.com/deployment - note that this change can be made even after your have deployed your app.

Q: How can I change how Peer5 runs on cellular networks?

A: You can change the behavior of Peer5 for users who are connected via cellular or WiFi from your Peer5 dashboard at https://app.peer5.com/deployment

Q: Is the SDK stable? Should I expect any performance difference in my app?

A: Peer5’s Android SDK is battle tested both in real world applications and contains an extensive test suite that runs on each version. Integrating the SDK should have no performance impact on your application. Users, on the other hand, will enjoy higher quality streaming with the SDK.

Q: How does Peer5 work?

A: Please refer to https://www.peer5.com/faq#how-does-peer5-work

Q: Is Android TV supported?

A: Yes, Android TV is a supported platform for the SDK. However, if you intend to integrate the SDK into a custom set-top box please let us know so we can ensure compatibility with custom versions of Android.

Q: Are encryption, DRM and https supported?

A: Yes, HTTPS, DRM and encryption are supported on newer versions of the SDK (2.1+). However if you’re concerned about your setup please contact send us an email and we'll help you make sure it's compatible.

Q: How long does integration take?

A: The code integration typically takes less than an hour. After the initial integration, Peer5 will run performance tests on your stream to optimize for P2P efficiency. We might contact you and suggest minor modifications in how your server streams HLS during this optimization process.

Please also refer to to the FAQ.

Support

If you have any questions about applying or integration do not hesitate to Chat with us or send us an email.