Android integration

This page explains manual Peerplug SDK integration for Android using Android Studio. If you have a custom build system, this page may provide you with enough information on how to integrate it into your build system. If you are still in doubt. Contact support

Please note, for Android, there is a fully automatic integration available.

Preparing

For this section, you will need the following:

  • Peerplug console with Integration access
  • Downloaded Peerplug SDK
  • Android Studio or other project
  • Basic software development skills

Copying the SDK

First step is to copy the SDK from the downloaded folder into your project folder.

Let’s assume your Android App project folder is “my_app” and Peerplug SDK you have downloaded and extracted is located in “pp_sdk” folder.

Please navigate to “my_app/app/src/main” directory and check if you have “jniLibs” directory

If you do not have “jniLibs”: please copy “pp_sdk/android/jniLibs” to “my_app/app/src/main”.

If you do have “jniLibs”: please enter “my_app/app/src/main/jniLibs” and see the directories you have there. Each directory represent a specific architecture. For each <arch>, copy the “libpp.so” file from pp_sdk/android/jniLibs/<arch>/libpp.so to “my_app/app/src/main/jniLibs/<arch>/”

Peerplug currently supports arm, arm64, x86, x86-64 architectures. If your app supports more architectures(like MIPS) Peerplug will not restrict it.

For any architecture that Peerplug does not support, the load command will silently fail and the app will continue running like it was before Peerplug.

Activating the SDK

In order to activate SDK you need to execute a single line of code as soon as your app loads. You can find this code in “pp_sdk/android/code.txt” here it is:

try {System.loadLibrary("pp");} catch (Throwable t) {}

First of all, as you can see, you are catching all possible exceptions. Therefore, even if Peerplug fails to load, for example as the architecture is not supported. This line will not do anything and your app will continue running smoothly.

The recommended place to put this line at is your App “application” class “onCreate()” method if you have one or inside “onCreate()” of your first activity.

Calling this function more than once has no effect.

If you do not use SSL for streaming – you are all set! Peerplug will automatically identify video streams and p2p offload them according to the policy you have configured. In case you stream over SSL, there one small extra step. Please see the “SSL Streaming” section.

Peerplug On/Off switch

Sometimes you would like to be able to turn Peerplug SDK on or off depending on the situation. One of the common approaches is to integrate the SDK with “on/off” functionality and “off” by default. Then you can turn it on at selected applications for testing before turning it “on” by default for all of your customers.

This can be achieved by conditionally executing load code only if a setting is enabled. For example, here is the Pseudo-code you can put in your onCreate() method:

if (Settings.peerplugEnabled()) {
    try {System.loadLibrary("pp");} catch (Throwable t) {}
}

You are free to implement the condition as any other conditional setting you have in your app.

Please note, Peerplug can be started but cannot be stopped. If you disable Peerplug (means, peerplugEnabled() will return false) you need to restart your app so it will start without Peerplug.

Same usually goes for starting Peerplug. If your launch code is located in onCreate(), app should be restarted to execute it and start Peerplug.

SSL Streaming

If you stream content over SSL, Peerplug needs to “look inside” the SSL tunnel in order to be able to accelerate the video stream.

This can be achieved by adding Peerplug CA to a list of trusted CAs in your project settings and instructing Peerplug to investigate SSL connections.

Copying Peerplug CA:

Peerplug CA certificate can be found inside the Peerplug SDK at “pp_sdk/metadata/peerplug_ca.der”.

Please copy this file to your app directory at “my_app/app/src/main/res/raw/peerplug_ca” file.

Please note, the destination file should not have .der suffix!

Adding Peerplug CA to your App:

Now we need to instruct your app to trust the CA. This is achieved by 2 steps:

  1. Adding a network security policy to your AndroidManifest.xml
  2. Copying or merging the security policy xml

Open you AndroidManifest.xml and see if you already have a network security policy under “application” tag. For example:

<manifest package="com.example.myapp" ... >
    <application android:networkSecurityConfig="@xml/my_netsec" >
        <activity android:name=".MainActivity" ... >
            ...
        </activity>
    </application>
</manifest>

In this example, there is already a network security policy defined in “xml/my_netsec. Therefore you will need to merge Peerplug’s XML into your “my_app/app/src/main/res/xml/my_netsec.xml” file, instructions are below.

If you don’t have “android:networkSecurityConfig” in your manifest you need to add:

 android:networkSecurityConfig="@xml/netsec"

to you application tag and copy “my_sdk/metadata/netsec.xml” to “my_app/app/src/main/res/xml/netsec.xml”

Merging security XML configs

Here is an example of final Security Config XML:

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="true">
        <trust-anchors>
            <certificates src="system" />
            <certificates src="@raw/peerplug_ca" />
        </trust-anchors>
    </base-config>
</network-security-config>

The important part is <trust-anchors>. Make sure you have the two lines that appear in the example. This will inform the app to use System CA certificates and Peerplug CA certificate.

After you have finished adding the certificate to your app, make sure to enable “SSL_INTERCEPTION” in Peerplug policy.

SSL Streaming security concerns

You may be worried that by adding Peerplug CA to the list of trusted CAs of your app you are introducing a security vulnerability as if Peerplug CAs private key is extracted your app can be vulnerable to man-in-the-middle attack.

When using Peerplug with SSL interception, your SSL connections are intercepted by Peerplug and therefore never actually go “outside”. Peerplug will connect to the required host and verify the remote certificate by itself using system trusted CAs only.

If you are using self singed CA at the server side and do not want Peerplug to verify the connections, please set “SSL_VERIFY” to 0 in Peerplug policy. Please note, this disabled SSL verification.

Feel free to contact support for any integration issues you find and we will be glad to assist.

Thank you for using Peerplug.