Skip to main content

Broadcast API Guide

What is a broadcast?​

Broadcasts enable Android applications to receive information from external sources, such as a backend server or CI/CD system. The Mason platform offers seamless integration for sending broadcasts via the Mason API.

This article details configuring an application to receive notifications and utilizing the Mason API to send them. For an example project, visit our broadcast example on GitHub.

How to configure an application to receive broadcasts​

1. Create a new project.​

Open Android Studio and create a new project.

2. Connect your device.​

Connect your device to Android Studio via USB to run the test application intended to receive notifications. Note: If you encounter issues with device detection on Windows, install the universal ADB driver or contact Mason Support.

3. Create a Broadcast Receiver.​

In Android Studio, right-click on app/java/{packageName}.

Select New -> Other -> Broadcast Receiver and name it MyReceiver.

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()
        }
    }
}

4. Configure permissions.​

Update your AndroidManifest.xml file to grant the Mason platform permission to push to your application.

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

Sending a message to a Broadcast Receiver​

Send a message via the API using the following JSON structure:

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

The $deviceID represents the device identifier found on the device details page in the Mason Console. Up to 500 identifiers can be specified in a single request.

cURL example:​

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 this example, $APIKEY is an environment variable containing a Mason Platform API Key, authenticating the API call.