Mason Docs

What is a Broadcast?

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 an example project instead, visit: https://github.com/MasonAmerica/broadcast-example.

Configuring an application to receive broadcasts

You can follow along with this guide using Android Studio.

  1. Start by creating a new project in Android Studio.

  2. 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.

    If you run into trouble with Android Studio detecting your device on Windows, please install the universal ADB driver or contact Mason Support - support@bymason.com.

  3. Next, 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.

  4. 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:

    <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>
    
  5. 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 a Broadcast Receiver

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

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

Visit our documentation for sending a Broadcast via our Mason Platform API

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.

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:

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

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

Support