Custom Broadcasts

Broadcasts are a way for an Android application to receive information from an outside source (such as your own backend server or CI/CD system). The Mason platform provides out-of-the-box support for sending broadcasts through the Mason API. This article covers how to setup an application to receive notifications and how to use the Mason API to send them. To see a working example please visit: https://github.com/MasonAmerica/broadcast-example.

Configurating an application to receive broadcasts

For our example app, we’ll start by creating a new project in Android Studio. Next, connect your device to Android Studio over USB. This will allow you to run the test application that you wish to send notifications to.

NOTE: If you run into trouble with Android Studio detecting your device on Windows, please install the universal ADB driver or contact Mason Support.

First we’ll need to create a Broadcast Receiver in our application. To do this in Android Studio right click on app/java/{packageName}, select New -> Other -> Broadcast Receiver. We’ll call our Broadcast Receiver MyReceiver.

Once you’ve added the broadcast receiver, you’ll need to go into your AndroidManifest.xml file and add permission for the Mason platform to push to your application. Here is an example:

AndroidManifest.xml

<receiver
    android:name=".MyReceiver"
    android:enabled="true"
    android:exported="true"
    android:permission="com.bymason.platform.core.permission.RECEIVE_PUSH">
    <intent-filter>
        <!-- Do not modify this -->
        <action android:name="com.bymason.platform.core.action.PUSH_RECEIVE"/>
    </intent-filter>
</receiver>

Now you add your custom logic to how you want to manage incoming broadcasts. In the example below, we will log and raise a toast for the incoming broadcast command.

class MyReceiver : BroadcastReceiver() {
    val ACTION_PUSH_RECEIVE = "com.bymason.platform.core.action.PUSH_RECEIVE"
    val EXTRA_PUSH_COMMAND = "com.bymason.platform.core.extra.PUSH_COMMAND"
    val EXTRA_PUSH_ARGUMENTS = "com.bymason.platform.core.extra.PUSH_ARGS"
    val TAG = "MYAPP"

    override fun onReceive(context: Context, intent: Intent) {
        // This method is called when the BroadcastReceiver is receiving an Intent broadcast.
        if (intent.action.equals(ACTION_PUSH_RECEIVE)) {
            val command = intent.getStringExtra(EXTRA_PUSH_COMMAND)
            var args = intent.getStringArrayExtra(EXTRA_PUSH_ARGUMENTS)
            args = args ?: arrayOf()
            // Add the logic to handle the received push notification here (such as starting
            // another activity)
            Log.i(
                TAG,
                String.format("Got a PUSH message, command(%s), %d args ", command, args.size)
            )
            Toast.makeText(context.applicationContext,command,Toast.LENGTH_LONG).show()
        }
    }
}

Sending a message

To send a message via the API, use the following JSON structure:

{
  "devices": [
    "$deviceID"
  ],
  "targetApps": [
    "com.example.myapplication"
  ],
  "command": "First message",
  "args": [ "arg1", "arg2" ]
}

Sending the above data via the API will send the message "First message" and the two arguments "arg1" and "arg2" to the device represented by the $deviceID above.

NOTE: The device identifier is the Mason id found in the device details page on the Mason Console.

Here is an example of using cURL to send the above message to the device in question via the broadcast API/endpoint:

# $APIKEY contains the Mason Platform API Key 
curl -i -H "Authorization: basic $APIKEY" \
    -d '{"devices":["$deviceID"],"targetApps":["com.example.myapplication"],"command":"First message","args":["arg1","arg2"]}' \
    https://api.bymason.com/v1/default/device/broadcast

NOTE: In the above example, $APIKEY is an environment variable that contains a Mason Platform API Key tied to your account to authenticate the API call