Dreams Android SDK

Requirements

• Minimum Android SDK version: 21
• Java source and target compatibility version: 1.8

Installation

Register the github maven repository by adding it to your project build.gradle.

allprojects {
    repositories {
        maven {
            name = "GitHubPackages"
            url = uri("https://maven.pkg.github.com/getdreams/dreams-android-sdk")
            credentials {
                username = project.findProperty("gpr.user") ?: System.getenv("GITHUB_USERNAME")
                password = project.findProperty("gpr.key") ?: System.getenv("GITHUB_TOKEN")
            }
        }
    }
}

Add the library to your module dependencies.

dependencies {
    implementation 'com.getdreams:android-sdk:0.7.0'
}

If you do not want to use the github repository you can download the package and put it in <module>/libs. Make sure you include AARs from the libs directory:

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
}

Github Authentication

For detailed docs see this.

You can save the username and token in your system gradle properties located in $GRADLE_USER_HOME/gradle.properties.

gpr.user=user
gpr.key=token

Or you can set the environmental variables:

GITHUB_USERNAME="user"
GITHUB_TOKEN="token"

Usage

Before using any other part of the SDK you must call Dreams.configure(). This can be done in Application.onCreate().

class ExampleApp : Application() {
    override fun onCreate() {
        super.onCreate()
        Dreams.configure(Dreams.Configuration(clientId = "clientId", baseUrl = "https://getdreams.io"))
    }
}

To show Dreams simply add DreamsView to a layout, and then call DreamsView.launch(). To handle possible errors during launch you can send a OnLaunchCompletion to DreamsView.launch() that will be invoked with the result of the launch.

<com.getdreams.views.DreamsView
    android:id="@+id/dreams"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

val dreamsView: DreamsView = findViewById<DreamsView>(R.id.dreams)
dreamsView.launch(Dreams.Credentials(idToken = "user token"), Locale.ENGLISH) { result ->
    when (result) {
        is Result.Success -> {
            // Dreams was launched successfully
        }
        is Result.Failure -> {
            when (val err = result.error) {
                is LaunchError.InvalidCredentials -> {
                    // The provided credentials were invalid
                }
                is LaunchError.HttpError -> {
                    // The server returned a HTTP error code
                }
                is LaunchError.UnexpectedError -> {
                    // Something went wrong when trying to open a connection to Dreams
                }
            }
        }
    }
}

Note as the dreams view can trigger showing the IME, e.g. a soft keyboard, it needs to be resized so the IME does not cover part of the dreams view. The easiest way to achieve this is to flag the activity as adjustResize.

<activity
    android:name=".Example"
    android:windowSoftInputMode="adjustResize"/>

Location

If you want to launch dreams at a specific location you need to send a location to DreamsView.launch.

val dreamsView: DreamsView = findViewById<DreamsView>(R.id.dreams)
dreamsView.launch(Dreams.Credentials(idToken = "user token"), Locale.ENGLISH, location = "/path/to/location") { _ -> }

When the dreams view is already active the DreamsView.navigateTo() function can be used instead.

val dreamsView: DreamsView = findViewById<DreamsView>(R.id.dreams)
dreamsView.navigateTo(location = "/path/to/location")

Events

In order to listen for events from Dreams you need to register a listener on the DreamsView.

dreamsView.registerEventListener { event ->
    when (event) {
        is Event.Telemetry -> { /* Use telemetry event */ }
    }
}

Token renewal

When a token requires renewal a CredentialsExpired event will be sent, to set a new token you need to call DreamsView.updateCredentials with the request id from the event and the new token.

dreamsView.registerEventListener { event ->
   when (event) {
       is Event.CredentialsExpired -> {
           val newToken = getValidToken()
           dreamsView.updateCredentials(requestId = event.requestId, credentials = Credentials(idToken = newToken))
       }
   }
}

Documentation

You can generate documentation by running the relevant Dokka task.

./gradlew sdk:dokkaHtml sdk:dokkaJavadoc

Testing

Unit tests

./gradlew sdk:test

Device tests

./gradlew sdk:connectedCheck

Development

Simply clone the repo and open the project in Android Studio 4.0 or later.

Preparing a Release

Simplest way is to use standard-version, with it you just need to run:

npx standard-version

Or manually update the versions in sdk/build.gradle and README.md. Then make a release tag.

Publishing

To publish the library to your local maven, simply run:

./gradlew sdk:publishToMavenLocal

This will publish aar, html-doc, javadoc, and sources to the local maven.

To publish to you need to add signing key details when running the publishing task(s).

signing.gnupg.keyName=<key>
signing.gnupg.passphrase=<pass>

To publish a new package to GitHub you can run:

./gradlew sdk:publishReleasePublicationToGitHubPackagesRepository