Using the Android SDK

  • Updated on Feb 3, 2025
  • Published on May 30, 2023
  • 10 minute(s) read
Prev Next

Set Your Region

When the SDK loads, it gets its station configuration from our provisioning servers. To speed up the process, we have provisioning servers in several regions including North America, Europe, and Asia. For best results, use the provisioning servers that are closest to your stations.

The default provisioning region is North America; to use one of the other regions, specify it as seen in the example below, where "AP" (Asia) is used.

// Create the player settings.
Bundle settings = new Bundle();
settings.putString(TritonPlayer.SETTINGS_STATION_BROADCASTER, "Triton Digital");
settings.putString(TritonPlayer.SETTINGS_STATION_NAME,        "MOBILEFM");
settings.putString(TritonPlayer.SETTINGS_STATION_MOUNT,       "MOBILEFM_AACV2");
settings.putString(TritonPlayer.SettingsPlayerServicesRegion, "AP"); // AP = Asia | EU = Europe | Omit this configuration option for North America

// Create the player.
TritonPlayer player = new TritonPlayer(this, settings);
player.play();


Auto-play

For measurement reasons, as well as user experience, the use of auto-play is strongly discouraged. Autoplay is defined as the station/stream playing without any user interaction to initiate the play. If you do implement an auto-play strategy, you need to add the autoplay = 1 value to the targetingParams object when calling the play function on the SDK.

// Create the player settings.
Bundle settings = new Bundle();
settings.putString(TritonPlayer.SETTINGS_STATION_BROADCASTER, "Triton Digital");
settings.putString(TritonPlayer.SETTINGS_STATION_NAME,        "MOBILEFM");
settings.putString(TritonPlayer.SETTINGS_STATION_MOUNT,       "MOBILEFM_AACV2");
settings.putString(TritonPlayer.SettingsPlayerServicesRegion, "AP"); // AP = Asia | EU = Europe | Omit this configuration option for North America

// Create the player.
TritonPlayer player = new TritonPlayer(this, settings);
player.play();

Audio Focus

Use TritonPlayer.SETTINGS_HANDLE_AUDIO_FOCUS to enable or disable the automatic handling of the device audio focus. In case you want to control the audio focus manually, you can set this option to false. The default is true.

Required: No.

Options (Boolean):

  • Automatic (TritonPlayer will handle any audio focus change automatically): true

  • Manual (TritonPlayer will ignore audio focus changes): false

// Create the player settings.

Bundle settings = new Bundle();
settings.putString(TritonPlayer.SETTINGS_STATION_BROADCASTER, "Triton Digital");
settings.putString(TritonPlayer.SETTINGS_STATION_NAME,        "MOBILEFM");
settings.putString(TritonPlayer.SETTINGS_STATION_MOUNT,       "MOBILEFM_AACV2");
settings.putBoolean(TritonPlayer.SETTINGS_HANDLE_AUDIO_FOCUS, false); // Audio Focus handled manually

// Create the player.

TritonPlayer player = new TritonPlayer(this, settings);
player.play();


Play a Station

// Create the player settings.
Bundle settings = new Bundle();
settings.putString(TritonPlayer.SETTINGS_STATION_BROADCASTER, "Triton Digital");
settings.putString(TritonPlayer.SETTINGS_STATION_NAME,        "MOBILEFM");
settings.putString(TritonPlayer.SETTINGS_STATION_MOUNT,       "MOBILEFM_AACV2"); 

// Create the player.

TritonPlayer player = new TritonPlayer(this, settings);
player.play();


Play a Specific HLS Mount

// Create the player settings.
Bundle settings = new Bundle();
settings.putString(TritonPlayer.SETTINGS_STATION_BROADCASTER, "Triton Digital");
settings.putString(TritonPlayer.SETTINGS_STATION_NAME,        "HLS_PLAYERS");
settings.putString(TritonPlayer.SETTINGS_STATION_MOUNT,       "HLS_PLAYERSAAC");
settings.putString(TritonPlayer.SETTINGS_TRANSPORT,           TritonPlayer.TRANSPORT_HLS);

// Create the player.
TritonPlayer player = new TritonPlayer(this, settings);
player.play();


Change the Station

To play a new station, you must create a new player.

// Release the current player instance.
if (player != null)
{
    player.release();
}

// Recreate the player with the next station settings.
player = new TritonPlayer(this, nextStationSettings);
player.play();

Target Audio Ads

In this example, location tracking is enabled. The postal code will only be used if the user has disabled the location access in the O.S. See StreamUrlBuilder in the API reference for more targeting options.

AndroidManifest.xml

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

// Create the targeting parameters
HashMap<String, String> targetingParams = new HashMap();
targetingParams.put(StreamUrlBuilder.COUNTRY_CODE,  "US");
targetingParams.put(StreamUrlBuilder.POSTAL_CODE,   "12345");
targetingParams.put(StreamUrlBuilder.GENDER,        "m");
targetingParams.put(StreamUrlBuilder.YEAR_OF_BIRTH, "1990"); 

// Create the player settings.
Bundle settings = new Bundle();
settings.putBoolean(TritonPlayer.SETTINGS_TARGETING_LOCATION_TRACKING_ENABLED, true);
settings.putSerializable(TritonPlayer.SETTINGS_TARGETING_PARAMS, targetingParams);
settings.putString(TritonPlayer.SETTINGS_STATION_BROADCASTER,    "Triton Digital");
settings.putString(TritonPlayer.SETTINGS_STATION_NAME,           "MOBILEFM");
settings.putString(TritonPlayer.SETTINGS_STATION_MOUNT,          "MOBILEFM_AACV2");

// Create the player.
TritonPlayer player = new TritonPlayer(this, settings);
player.play();

Example using DMP Segments:

//Add DMP SEGMENTS
HashMap<String, List<Integer>> dmpSegments = new HashMap();
dmpSegments.put("permutive", Arrays.asList(1234,5769));
dmpSegments.put("adobe", Arrays.asList(4321,8765));

// Create the player settings.
Bundle settings = new Bundle();
settings.putBoolean(TritonPlayer.SETTINGS_TARGETING_LOCATION_TRACKING_ENABLED, true);
settings.putSerializable(TritonPlayer.SETTINGS_TARGETING_PARAMS, targetingParams);
settings.putSerializable(TritonPlayer.SETTINGS_DMP_SEGMENTS, dmpSegments);
settings.putString(TritonPlayer.SETTINGS_STATION_BROADCASTER,    "Triton Digital");
settings.putString(TritonPlayer.SETTINGS_STATION_NAME,           "MOBILEFM");
settings.putString(TritonPlayer.SETTINGS_STATION_MOUNT,          "MOBILEFM_AACV2");

// Create the player.
TritonPlayer player = new TritonPlayer(this, settings);
player.play();


Change Podcast Playback Speed

To change the playback speed of a podcast, use changeSpeed with a float value as the speed argument. Example:

tritonPlayer.changeSpeed(1.5f)

...would change the playback to 1.5 times the original speed.


Token Authorization (self-signed)

In order for re-creation of the tokens on reconnect to work, either of the following parameters are required:

  • TritonPlayer.SETTINGS_AUTH_SECRET_KEY

  • TritonPlayer.SETTINGS_AUTH_KEY_ID

If all of the parameters are filled in, then you don't have to generate the token yourself (although you can if you want to).

// Create the targeting parameters
HashMap<String, String> targetingParams = new HashMap();
targetingParams.put(StreamUrlBuilder.COUNTRY_CODE,  "US");
targetingParams.put(StreamUrlBuilder.POSTAL_CODE,   "12345");
targetingParams.put(StreamUrlBuilder.GENDER,        "m");
targetingParams.put(StreamUrlBuilder.YEAR_OF_BIRTH, "1990");

// Create the authorization token
String token = AuthUtil.createJwtToken("MySecretKey", "MySecretKeyId", true, "foo@bar.com", targetingParams); 

// Create the player settings.
Bundle settings = new Bundle();
settings.putSerializable(TritonPlayer.SETTINGS_TARGETING_PARAMS, targetingParams);
settings.putString(TritonPlayer.SETTINGS_AUTH_TOKEN,             token);
settings.putString(TritonPlayer.SETTINGS_STATION_BROADCASTER,    "Triton Digital");
settings.putString(TritonPlayer.SETTINGS_STATION_NAME,           "MOBILEFM");
settings.putString(TritonPlayer.SETTINGS_STATION_MOUNT,          "MOBILEFM_AACV2");
settings.putString(TritonPlayer.SETTINGS_AUTH_SECRET_KEY,        "1234566");
settings.putString(TritonPlayer.SETTINGS_AUTH_KEY_ID,            "ABCDEF");
settings.putBoolean(TritonPlayer.SETTINGS_AUTH_REGISTERED_USER,  true/false);
settings.putString(TritonPlayer.SETTINGS_AUTH_USER_ID,           null);

// Create the player.
TritonPlayer player = new TritonPlayer(this, settings);
player.play();


Receive Cue Points

// Create a cue point listener.
OnCuePointReceivedListener listener = new OnCuePointReceivedListener() {
    @Override
    public void onCuePointReceived(MediaPlayer player, Bundle cuePoint) {
        // Handle the cue points here.
    }
};

// Create the player.
TritonPlayer player = new TritonPlayer(this, settings);
player.setOnCuePointReceivedListener(listener);
player.play();


Display Sync Banners

private SyncBannerView mSyncBannerView; 

@Override
protected void onPause() {
    mSyncBannerView.onPause();
    super.onPause();
} 

@Override
protected void onResume() {
    super.onResume();
    mSyncBannerView.onResume();
} 

@Override
protected void onDestroy() {
    mSyncBannerView.release();
    super.onDestroy();
} 

@Override
public void onCuePointReceived(MediaPlayer player, Bundle cuePoint) {
    // Update the banner. See previous example on how to get cue points.
    mSyncBannerView.loadCuePoint(cuePoint);
} 

private void initBanner() {
    // Get the banner from the layout and set its size.
    mSyncBannerView = (SyncBannerView)findViewById(mySyncBannerId);
    mSyncBannerView.setBannerSize(320, 50);
}


Play an On-Demand Stream

// Create the player settings.
Bundle settings = new Bundle();
settings.putString(TritonPlayer.SETTINGS_STREAM_URL, "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3"); 

// Create the player.
TritonPlayer player = new TritonPlayer(this, settings);
player.play();


Play on Google Cast Devices

The Triton Digital Mobile SDK supports Google Cast devices for both live and on-demand streams, but not on-demand advertising. There are a few devices supporting the Google Cast protocol, such as the Chromecast player and Nexus player.

Basic Media Receiver

The sample app in the ZIP file shows how to do a basic implementation.

Styled Media Receiver

More complex to implement than the Basic Media Receiver.

Useful links:


Get the Station's Song History

public class SongHistoryExample extends Activity implements CuePointHistory.CuePointHistoryListener
{
    private CuePointHistory mCuePointHistory;
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
 
        // Init the cue point history object
        mCuePointHistory = new CuePointHistory();
        mCuePointHistory.setListener(this);
        mCuePointHistory.setCueTypeFilter(CuePoint.CUE_TYPE_VALUE_TRACK);
        mCuePointHistory.setMaxItems(10);
        mCuePointHistory.setMount("MOBILEFM");
 
        // Request the track history
        mCuePointHistory.request();
    }
 
    @Override
    public void onCuePointHistoryReceived(CuePointHistory src, List<Bundle> cuePoints) {
        // Handle history here
    }
 
    @Override
    public void onCuePointHistoryFailed(CuePointHistory src, int errorCode) {
        // Handle errors here
    }
}


Display On-Demand Ads Over the App

Interstitials can either be video or audio ads.

AndroidManifest.xml

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
 
<activity
    android:name="com.tritondigital.ads.InterstitialActivity"
    android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|uiMode|screenSize|smallestScreenSize" />

MyActivity.java

AdRequestBuilder adRequestBuilder = new AdRequestBuilder(this)
        .enableLocationTracking(true)
        .setHost("http://cmod209.live.streamtheworld.com/ondemand/ars")
        .addQueryParameter(AdRequestBuilder.YEAR_OF_BIRTH, 1990)
        .addQueryParameter(AdRequestBuilder.GENDER, 'm')
        .addQueryParameter(AdRequestBuilder.STATION_ID, "23193");
 
// Create the interstitial instance
Interstitial interstitial = new Interstitial(this);
 
//Optional if you want to display the ad countdown timer:
interstitial.setEnableCountDownDisplay(true);
 
// Display an interstitial ad
interstitial.showAd(adRequestBuilder);
 
// When exiting your activity
interstitial.release();


Display On-Demand Ads with Custom UI

This is much more complex than using the Interstitial class. There is an example in the sample application in the ZIP file.


Custom TTags – Player

Custom TTags (e.g., mobile:ford) can be applied to streaming URLs by adding an array to the settings parameter SETTINGS_TTAGS.

Custom TTags – Player Example

// Create the player settings.
Bundle settings = new Bundle();
settings.putString(TritonPlayer.SETTINGS_STATION_BROADCASTER,    "Triton Digital");
settings.putString(TritonPlayer.SETTINGS_STATION_NAME,           "MOBILEFM");
settings.putString(TritonPlayer.SETTINGS_STATION_MOUNT,          "MOBILEFM_AACV2");
 
String[] tTags = {"mobile:android","cola:diet"};
settings.putStringArray(TritonPlayer.SETTINGS_TTAGS,tTags);
// Create the player.
TritonPlayer player = new TritonPlayer(this, settings);
player.play();


Custom TTags – On Demand Ads

Custom TTags (e.g., mobile:ford) can be applied to On Demand URLs by calling addTTags( String[] ) on AdRequestBuilder.

Custom TTags – On Demand Ads Example

// Optional Custom TTags
String[] tTags = { "mobile:android", "car:suv" };
 
AdRequestBuilder adRequestBuilder = new AdRequestBuilder(this)
        .enableLocationTracking(true)
        .setHost("http://cmod209.live.streamtheworld.com/ondemand/ars")
        .addQueryParameter(AdRequestBuilder.YEAR_OF_BIRTH, 1990)
        .addQueryParameter(AdRequestBuilder.GENDER, 'm')
        .addQueryParameter(AdRequestBuilder.STATION_ID, "23193")
        .addTtags(tTags);
 
// Create the interstitial instance
Interstitial interstitial = new Interstitial(this);
 
// Display an interstitial ad
interstitial.showAd(adRequestBuilder);
 
// When exiting your activity
interstitial.release();


Multi-listener ID

Provides a way to send multiple user or device identifiers, in addition to the main listener ID (lsid parameter). The latter is still used by Triton for frequency capping, measurement etc., while the other IDs can be provided to third-party demand platforms in order to improve monetization.

The values for the LISTENER_ID_TYPE are:

  • ListenerIdType.PPID

  • ListenerIdType.IDFA

  • ListenerIdType.GAID

  • ListenerIdType.APP

Example:

Bundle settings = new Bundle();
settings.putString(TritonPlayer.SETTINGS_STATION_BROADCASTER, "Triton Digital");
settings.putString(TritonPlayer.SETTINGS_STATION_NAME,        "MOBILEFM");
settings.putString(TritonPlayer.SETTINGS_STATION_MOUNT,       "MOBILEFM_AACV2");

// Add the targeting parameters
HashMap<String, String> targetingParams = new HashMap();
targetingParams.put(StreamUrlBuilder.DIST, "triton-dist-param");
targetingParams.put(StreamUrlBuilder.LISTENER_ID_TYPE, StreamUrlBuilder.ListenerIdType.PPID.getListenerIdType());
targetingParams.put(StreamUrlBuilder.LISTENER_ID_VALUE, "550e8400-e29b-41d4-a716-446655443658");

settings.putSerializable(TritonPlayer.SETTINGS_TARGETING_PARAMS, targetingParams);
// Create the player.
TritonPlayer player = new TritonPlayer(this, settings);
player.play();


Low Delay and Adaptive Buffering

When set to -1 / AUTO MODE the SDK uses a small (two second) buffer window on initial connection, reducing the amount of delay between playback and real-time.  (This is useful for sporting events, live contests, etc.)

Because the connection has a small buffer window, if there is network congestion or low bandwidth the buffer will increase by a factor of two if the device cannot maintain proper connection.

When set to a value greater than zero (>0) the SDK will buffer that many seconds of audio before beginning playback.

Use SettingsLowDelayKey with an NSNumber object for this feature. Valid values: -1 (AUTO mode), 0 (Disabled) , 2 to 60 seconds.

By default the feature is disabled ( 0 ).

Android Low Delay Example

// Create the player settings.
Bundle settings = new Bundle();
Integer lowDelayValue = 2;
settings.putString(TritonPlayer.SETTINGS_STATION_BROADCASTER,   "Triton Digital");
settings.putString(TritonPlayer.SETTINGS_STATION_NAME,          "MOBILEFM");
settings.putString(TritonPlayer.SETTINGS_STATION_MOUNT,         "MOBILEFM_AACV2");
settings.putInt(TritonPlayer.SETTINGS_LOW_DELAY,                lowDelayValue);
 
// Create the player.
TritonPlayer player = new TritonPlayer(this, settings);
player.play();


Timeshift

For more information about Timeshift Radio, see the Streaming Specification.

In order for the Timeshift stream to work, the following property is required:

TritonPlayer.SETTINGS_STATION_MOUNT

Seek Function:

To seek forward and backward use the seek() function, which takes a value in seconds as a parameter. If the parameter is positive, you seek forward; if it is negative you seek backward. If the value is zero then you seek to the live point.

E.g.: seek(-10), seek(10), seek(0)

// Create the player settings.
Bundle settings = new Bundle();
settings.putBoolean(TritonPlayer.SETTINGS_TIMESHIFT_ENABLED, true);
settings.putString(TritonPlayer.SETTINGS_STATION_BROADCASTER,    "Triton Digital");
settings.putString(TritonPlayer.SETTINGS_STATION_NAME,           "MOBILEFM");
settings.putString(TritonPlayer.SETTINGS_STATION_MOUNT,          "MOBILEFM_AACV2");
 
// Create the player.
TritonPlayer player = new TritonPlayer(this, settings);
player.play();
 
...
player.seek(10);

Seek To Live Function:

To return to the live stream use the seekToLive() function. This will stop the Timeshift stream and connect again to the live stream.

Get Cloud Stream Function:

To get the programs associated with the station use the getCloudStreamInfo() function. When the list of programs is received, a notification is sent to the OnCloudStreamInfoReceivedListener in the MediaPlayer class.

The JSON object looks like this:

{
     "maximumRewindTimeSec": 10800,
     "programs": {
           "name": "program",
           "program_episode_id": "99999-1678715517259",
           "properties": {
                 "cue_id": "23337",
                 "cue_time_start": "1678715517259",
                 "cue_title": "ProgramStart",
                 "program_id": "99999",
                 "program_time_start": "1678715517259",
                 "program_title": "Messy Gossip with Blork",
                 "stw_cached": "false",
                 "stw_original_type": "stwcue"
           }
     }
}

Play Program (String programid) Function:

Use playProgram(String programId) to select a specific program. The programId is the program_episode_id that is in the returned JSON object.

Dist Parameter:

To use the dist parameter with Timeshift you need to add both timeshifting parameters:

StreamUrlBuilder.DIST_TIMESHIFT

StreamUrlBuilder.DIST

  • The StreamUrlBuilder.DIST parameter is used when the stream is connected in live mode.

  • The StreamUrlBuilder.DIST_TIMESHIFT parameter is used when the stream is in Timeshift mode.

Below is an example of how to add the parameters:

// Create the targeting parameters
HashMap<String, String> targetingParams = new HashMap();
targetingParams.put(StreamUrlBuilder.DIST_TIMESHIFT, "timeshift-dist-param");
targetingParams.put(StreamUrlBuilder.DIST, "triton-dist-param");

// Create the player settings.
Bundle settings = new Bundle();
settings.putSerializable(TritonPlayer.SETTINGS_TARGETING_PARAMS, targetingParams);
settings.putString(TritonPlayer.SETTINGS_STATION_BROADCASTER,    "Triton Digital");
settings.putString(TritonPlayer.SETTINGS_STATION_NAME,           "MOBILEFM");
settings.putString(TritonPlayer.SETTINGS_STATION_MOUNT,          "MOBILEFM_AACV2");

// Create the player.
TritonPlayer player = new TritonPlayer(this, settings);
player.play();