The Better Together plugin API
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.idea
api
gradle/wrapper
.gitignore
LICENSE
README.md
build.gradle
gradle.properties
gradlew
gradlew.bat
settings.gradle

README.md

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.

compile 'ac.robinson.bettertogether:api:1.0.0'

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.

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