Controlling Shield App Settings from the Companion App

Overview

Apps that you write for the Shield can have user settings. Your app will typically have a mechanism for users to change those settings. You can also allow users to change app settings from within the companion app. Information about available settings and changes to those settings are communicated via a set of broadcasts between your app and the companion app.

When a user views details for your app on the companion app’s Apps tab, the companion app will query your app via an ordered broadcast for details about your app settings. If your app does not respond, no settings will be displayed other than app version information. If your app responds with information about settings, further broadcasts will be used to communicate changes to settings. The broadcasts used are described below.

Broadcasts

Your app’s manifest should define a broadcast receiver with an intent filter that listens for two actions:

• com.vuzix.action.GET_SETTINGS

• com.vuzix.action.PUT_SETTING

These broadcast actions are described in the following sections.

com.vuzix.action.GET_SETTINGS

The GET_SETTINGS ordered broadcast is sent from the companion app to your app for the purpose of querying information about settings in your app. If you wish to provide settings back to the companion app, they can be communicated through a broadcast result extra named “items”. The “items” extra is a Bundle array. Each Bundle in the array describes a single setting in your app. For example, if your app exposed 3 settings for display in the companion app, the “items” Bundle array would have 3 items. Each Bundle has properties that describe a setting. The common properties for a settings item are as follows:

• id: String containing the unique ID of the setting

• type: String containing the type of setting, will be one of: PAGE, SECTION, READONLY, TOGGLE, LIST, SLIDER, STRINGLIST, BUTTON

• displayName: String containing the display name of the setting

Then depending on the type of setting, additional properties are available. Each type of setting and available properties for each are described below.

The PAGE and SECTION types are used to group settings together. PAGE types display a group of settings on a new page while SECTION types group settings together under a header on the current page. Both types have the following additional property:

• items: Bundle array containing child settings

The READONLY type is used to display a setting name and value to the user. The following additional property is available:

• value: String containing the value of the setting

The TOGGLE type is used to display a setting that can be either on or off. The following additional property is available:

• on: boolean specifying if the setting is on

The LIST type displays a setting with a list of possible choices. The following additional properties are available:

• choices: String array containing the choices available to the user

• selected: int containing the zero-based choice that is currently selected

The SLIDER type displays a slider that can change a setting value between a min and max value. The following additional properties are available:

• min: int containing the minimum allowed value

• max: int containing the maximum allowed value

• step: int containing the difference in value between steps on the slider

• value: int containing the current setting value

The STRINGLIST type displays an editable list of strings the user can edit. Strings can be added, removed and reordered and their values can be changed. The following additional properties are available:

• max: int containing the maximum number of strings allowed to be created by the user

• values: String array containing the list of strings

• readonly: boolean indicating if the list should be used for display only and cannot be edited, if missing assume false

The BUTTON type displays a button to the user that can be tapped. Optionally, a confirmation message can be displayed with Yes/No choices when the button is tapped. Buttons are useful for trigger actions over on the Shield, logging out of an app for example. The following additional property is available:

• confirmation: String containing the confirmation to display, if any

com.vuzix.action.PUT_SETTING

The PUT_SETTING broadcast is used to communicate a change in a setting value. The companion app will send this broadcast to your app when the user makes a change to a setting. When you receive this broadcast, you should update your local setting. If the user is also looking at your app settings on the Shield, it’s good user experience to make sure your user interface is updated to show the new setting value.

You can also send this broadcast from your app to the companion app when the user changes a setting in your app. This is not typically required but can be used to ensure a responsive UI if the user is looking at settings in both your app and the companion app at the same time.

The following intent extras will be present for the PUT_SETTING broadcast:

• id: String containing the original id you specified during GET_SETTINGS

• value: the new value of the setting, will be typed differently depending on the original type specified during GET_SETTINGS

• values: String array representing the new values after user modifications are complete, only used with STRINGLIST type

com.vuzix.apps.action.UPDATE_SETTINGS

If your app ever changes the structure of its settings, you can use the UPDATE_SETTINGS broadcast to notify the companion app that all settings are invalid, and a new list should be requested immediately. To do this, you’ll need to use the Connectivity SDK to send a remote broadcast to the companion app. For example:

Intent updateSettings = new Intent("com.vuzix.apps.action.UPDATE_SETTINGS"); 
updateSettings.setPackage("com.vuzix.companion"); 
Connectivity.get(context).sendBroadcast(updateSettings);

Notice that you should specify the package so that only the companion app receives the broadcast. When the companion app receives the broadcast, it will know the message came from your app and a settings refresh will be initiated.

Companion Settings Library

While responding to the GET_SETTINGS intent, you can manually build a Bundle array which describes your app’s settings. You can also use the companion settings library to assist you in building the necessary Bundle array.

Setup and Installation

If you haven’t already, point your project to Jitpack where we host our libraries by add the following to your build.gradle file:

grallprojects {
	repositories {
		google()
		jcenter()
		maven { url "https://jitpack.io" }
	}
}

If you set up the Connectivity SDK previously, the above step is probably already done.

Finally, add Companion Settings as a dependency in your app’s build.gradle file:

dependencies {
	implementation 'com.vuzix:companion-settings:master-SNAPSHOT'
}

The latest version is:

Usage

In your BroadcastReceiver’s onReceive() method, you can use the companion settings library to generate the result value for the GET_SETTINGS broadcast:

@Override public void onReceive(Context context, Intent intent) {
	if ("com.vuzix.action.GET_SETTINGS".equals(intent.getAction())) {
		Settings settings = new Settings();
		settings.addSetting(new Toggle(“toggle”, "My Toggle", false));
		settings.addSetting(new Slider(“slider”, "My Slider", 0, 100, 1, 0));
		setResultExtras(settings.toBundle());
	}
}

Sample Project

A sample application for Android Studio demonstrating the Companion Settings Library is available here.