# Android SDK Overview

The Android SDK APIs are split into two main categories: [Express](/content/docs/sdk_ref/android/express/index.html) and [Low-Level](/content/docs/sdk_ref/android/low-level/index.html). 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](/content/docs/sdk_ref/android/express/index.html).

If you find that the Express API doesn't work for you, take a look at our [Lower Level API](/content/docs/sdk_ref/android/low-level/index.html).

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](https://github.com/PhenixRTS/AndroidSDK) for details. Review the [list of packages](https://github.com/orgs/PhenixRTS/packages?repo_name=AndroidSDK) and select the one you want (e.g., the latest official release or a beta release).

Please also see our [guide](/content/docs/sdk_ref/android/android-studio-integration/index.html) 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:

- `implementation 'com.google.android.exoplayer:exoplayer-dash:2.6.1'`
- `implementation 'com.google.android.exoplayer:exoplayer-core:2.6.1'`

### Minimum SDK Requirements

The Phenix SDK supports Android version 6.

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

- API Level 15: Real-time streaming
- API Level 19: ExoPlayer with DRM support
- API Level 21: Screen sharing

## 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](/content/docs/knowledge-base/how-to/state-transitions/index.html) for details on managing state transitions.

## App Store

Google supports a split [Android Bundle format](https://developer.android.com/studio/build/configure-apk-splits) 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.

```java
// 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](https://developer.android.com/google/play/publishing/multiple-apks)

## Observable

Observe value changes. Similar to the ReactiveX [Behavior Subject](http://reactivex.io/documentation/subject.html).

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](/content/docs/sdk_ref/android/overview/#disposable/index.html) | See [Subscribe to an Observable](/content/docs/sdk_ref/android/overview/#subscribe-to-an-observable/index.html) |
| getValue | () _varies_ | See [Get Observable Value](/content/docs/sdk_ref/android/overview/#get-observable-value/index.html) |  |
| setValue | (value) | void | See [Set Observable Value](/content/docs/sdk_ref/android/overview/#set-observable-value/index.html) |

### Subscribe to an Observable

Receive a notification every time the observable value changes.

```java
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.

```java
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.

```java
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.

```java
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:

- `messages` string contains the most recent as well as initial logs (since your app started)
- Each log entry in the string is separated by a newline
- Log entries are stored chronologically, newest logs last

## Known issues

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

Android Studio issue: [Google Issue 76403146](https://issuetracker.google.com/issues/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](https://issuetracker.google.com/issues/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'`
