Better Together API

Better Together is a platform for flexibly connecting multiple smartphones together to separate common tasks. This project is the API to help develop your own plugins.

A documented sample plugin is also available, showing the basic steps for setting up your own plugin.

Developing a plugin is the simplest way to create services using the Better Together framework. However, if you'd prefer deeper integration, it is possible to add its connectivity to your own app. See, for example, swarachakra keyboard, which enables remote text input in Indic scripts.

Adding to your project

To add Better Together to your project, add it as a dependency to your build.gradle.

implementation 'ac.robinson.bettertogether:api:1.0.3'

The project has not yet been migrated away from the now-discontinued BinTray platform, so you may also need to update the allprojects section of your project-level build.gradle file:

allprojects {
    repositories {
        google()
        mavenCentral()

        // required to import the Better Together API (version 1.0.3 and older)
        jcenter() {
            content {
                // allow only this module, ensuring other libraries are still retrieved from current repositories
                includeModule('ac.robinson.bettertogether', 'api')
            }
        }

    }
}

Sending and receiving messages

Message are sent to and received from other devices using PluginConnectionDelegate. The simplest way to incorporate this into your project is to extend BasePluginActivity or BasePluginFragment.

The sendMessage and onMessageReceived methods handle all communication beteen devices. The onMessageReceived method is called whenever a message is received, with a BroadcastMessage parameter containing the message itself. To send a new message, first create a new BroadcastMessage object:

new BroadcastMessage(1, "Hi - this is my message");

The constructor for BroadcastMessage takes a message type and message contents (int and String). There is also an optional int extra field – set this using setIntExtra. All of these parameters can be retrieved using getType, getMessage and getIntExtra, respectively.

Use the message type field to differentiate between messages when they are received, or to filter commands. If you do not need custom message types, BroadcastMessage.TYPE_DEFAULT and BroadcastMessage.TYPE_ERROR are available. For an example of more detailed message type use, see the video and shopping plugins, which are built into the Better Together host app.

Your new message can be sent using sendMessage, and will be received in the onMessageReceived method of the currently open plugin activity on all connected devices.

Adding your plugin to Better Together

To allow your plugin to be discovered by the Better Together host app, add the following intent-filter to the Activity instances in your AndroidManifest.xml that you would like to use with Better Together.

<intent-filter>
    <action android:name="ac.robinson.bettertogether.intent.action.LAUNCH_PLUGIN"/>
</intent-filter>

Required manifest elements

In order to be displayed as a plugin, the application element of your AndroidManifest.xml must have both an android:icon and an android:label parameter.

In order for an individual Activity to be displayed, it must have the parameter android:exported="true". It must also have both an android:icon and an android:label parameter.

Plugins that do not declare all of these attributes will not be displayed in the Better Together host app. If your plugin does not display, check logcat to find the reason in an error message.

For a fully documented example of the configuration options available (including themes and connection configuration), see the sample plugin's AndroidManifest.xml.

Development tips

Plugins are loaded and unloaded dynamically, so you do not need to restart the Better Together host app (or disconnect from other devices) when developing or deploying updates. For this to work well with Android Studio without a launcher Activity, you may need to go to Run > Edit Configurations… and set the Launch Options for your plugin's configuration to launch Nothing (rather than Default Activity).

If your plugin does not provide a launcher Activity, you can import the default activity from the plugin API for a better experience when installing plugins from Google Play. When launched, DefaultActivity will open Better Together if it is installed. If not, it will open Google Play to the Better Together app's page.

License

Apache 2.0