Android SDK Overview - PhenixRTS Docs

Android SDK Overview

The Android SDK APIs are split into two main categories: Express and Low-Level. We recommend that you start with the Express API as this:

  1. Simplifies integration
  2. Automatically recovers from stream failures
  3. Handles edge cases such as network reconnects

For more information see the Express API.

If you find that the Express API doesn't work for you, take a look at our Lower Level API.

The current release of the Phenix Android SDK supports a token-based workflow and a wide variety of other features.

Setup

The Phenix SDK is provided as a standard Android library module in form of an .aar file. Please see our public Github repository for details. Review the list of packages and select the one you want (e.g., the latest official release or a beta release).

Please also see our guide on how to integrate the Phenix SDK into a new Kotlin DSL project.

Extended feature support

(Optional) For extended live streaming support (DASH), you also need to add ExoPlayer as a dependency to your project:

Minimum SDK Requirements

The Phenix SDK supports Android version 6.

Depending on required features, the minimum supported Android API levels are as follows:

General

All Phenix SDK objects provide a dispose method, which allows for instant release of all its resources. To force release resources held on to by any object, just call dispose.

Note: Once an object has been disposed, it should no longer be accessed or else it will throw an IllegalStateException

Refer to this article for details on managing state transitions.

App Store

Google supports a split Android Bundle format as the replacement for the old APK format. We highly recommend using this new format, as it significantly minimizes user app download size without any additional configuration.

If you are using the APK app format, you can optimize your app by deploying multiple APKs, each specific to an ABI (i.e. processor architecture) by updating your Gradle configuration file.

// build.gradle
android {
  ...
  splits {
    // Configures multiple APKs based on ABI.
    abi {
      // Enables building multiple APKs per ABI.
      enable true

// Resets the list of ABIs that Gradle should create APKs for to none.
      reset()

// Specifies a list of ABIs that Gradle should create APKs for.
      include "armeabi-v7a", "arm64-v8a", "x86", "x86_64"

// Specifies that we do not want to also generate a universal APK that includes all ABIs.
      universalApk false
    }
  }
}

With this approach, the end user will automatically download the correct version for their device when installing the app from the Play Store. Their downloaded APK will only have the Phenix SDK version that their architecture requires, making the download size smaller.

In general, when using multiple APKs, you will want to make sure that they conform to the requirements described in the Google Android Developer documentation

Observable

Observe value changes. Similar to the ReactiveX Behavior Subject.

Important differences for Phenix SDK observables:

  1. There is always an initial value (which can be null for some objects)
  2. Only if observed value changes will subscribers get notified

Point 1 means that when subscribing, you will always get notified immediately with the current value. This is guaranteed atomic, meaning that you do not have to worry about missing any observable updates.

Observable

Name Signature Returns Description
subscribe (onChanged) Disposable See Subscribe to an Observable
getValue () varies See Get Observable Value
setValue (value) void See Set Observable Value

Subscribe to an Observable

Receive a notification every time the observable value changes.

import com.phenixrts.common.Disposable;
import com.phenixrts.common.Observable;

Observable<String> observable = ...;  // previously obtained

Disposable subscription = observable.subscribe((change) -> {
  String newStringValue = (String)change;
  // Do something with newStringValue
});

// Disposing of the subscription will cancel it:
subscription.dispose();

Parameters

Name Type Description
onChangedHandler (required) Observable.OnChangedHandler Handler to call when value changes

Disposable

Has no methods, but does inherit from JavaObject. This allows canceling of subscription by calling dispose.

Get Observable Value

Synchronous method allowing retrieval of currently set value. Thread safe.

import com.phenixrts.common.Observable;
import com.phenixrts.room.Member;
import com.phenixrts.room.MemberRole;

Observable<MemberRole> roleObservable = ...;  // previously obtained
MemberRole role = roleObservable.getValue();

Observable<Member[]> membersObservable = ...;  // previously obtained
Member[] members = membersObservable.getValue();

Set Observable Value

Change the observable value. This will trigger notifications on all subscribers.

import com.phenixrts.common.Observable;
import com.phenixrts.room.MemberRole;

Observable<MemberRole> roleObservable = ...;  // previously obtained
roleObservable.setValue(MemberRole.PRESENTER);

Debugging

You can retrieve the Phenix SDK logs programmatically using the collectLogMessages PCast™ API.

import com.phenixrts.pcast.PCast;
import com.phenixrts.pcast.RequestStatus;

// Previously initialized
PCast pcast = ...;

pcast.collectLogMessages(
    new PCast.LogMessageCollectionCallback() {
        @Override
        public void onEvent(
            PCast pcast,
            RequestStatus requestStatus,
            String messages) {
          if (requestStatus != RequestStatus.OK) {
            // Handle error
            return;
          }
          String messagesArray[]= messages.split("\n");
          for (String message: messagesArray) {
            // Do something with 'message'
          }
        }
    });

Notes:

Known issues

Build crash: java.io.IOException: Failed to find byte code for …

Android Studio issue: Google Issue 76403146

Solution:

  1. Upgrade : gradle-wrapper.properties - gradle-4.6-all.zip or later
  2. Upgrade gradle plugin in project build.gradle - 'com.android.tools.build:gradle: 3.2.+' or later

Or Disable instant run - Android Studio -> Settings -> Search Instant run -> Disable

IDE error: .GroovyFileImpl because: different providers: SingleRootFileViewProvider

Android Studio issue: Google Issue 77939622

Solution:

If directory for module was created (e.g. /phenix-sdk), just add direcory name to settings.gradle file.

include ':app', ':phenix-sdk', ':phenix-utils', ':phenix-ui'