Working with Multiple JobServices

Posted by Isai Damier, Software Engineer, Android DA

Working with Multiple JobServices

In its continuous effort to improve user experience, the Android platform has
introduced strict limitations on background services starting in API level 26.
Basically, unless your app is running in the foreground,
the system will stop all of your app’s background services within minutes.

As a result of these restrictions on background services,
JobScheduler jobs have become the de facto solution for performing
background tasks. For people familiar with services, JobScheduler
is generally straightforward to use: except in a few cases, one of which we
shall explore presently.

Imagine you are building an Android TV app. Since channels are very important to
TV Apps, your app should be able to perform at least five different background
operations on channels: publish a channel, add programs to a channel, send logs
about a channel to your remote server, update a channel’s metadata, and delete a
channel. Prior to Android 8.0 (Oreo) each of these five operations could be
implemented within background services. Starting in API 26, however, you must be
judicious in deciding which should be plain old background Services
and which should be JobServices.

In the case of a TV app, of the five operations mentioned above, only channel
publication can be a plain old background service. For some context, channel
publication involves three steps: first the user clicks on a button to start the
process; second the app starts a background operation to create and submit the
publication; and third, the user gets a UI to confirm subscription. So as you
can see, publishing channels requires user interactions and therefore a visible
Activity. Hence, ChannelPublisherService could be an IntentService
that handles the background portion. The reason you should not use a
JobService here is because JobService will introduce a
delay in execution, whereas user interaction usually requires immediate response
from your app.

For the other four operations, however, you should use JobServices;
that’s because all of them may execute while your app is in the background. So
respectively, you should have ChannelProgramsJobService,
ChannelLoggerJobService, ChannelMetadataJobService,
and ChannelDeletionJobService.

Avoiding JobId Collisions

Since all the four JobServices above deal with Channel
objects, it should be convenient to use the channelId as the
jobId for each one of them. But because of the way
JobServices are designed in the Android Framework, you can’t. The
following is the official description of jobId

Application-provided id for this job. Subsequent calls to cancel, 
or jobs created with the same jobId, will update the pre-existing 
job with the same id. This ID must be unique across all clients 
of the same uid (not just the same package). You will want to 
make sure this is a stable id across app updates, so probably not 
based on a resource ID.

What the description is telling you is that even though you are using 4
different Java objects (i.e. -JobServices), you still cannot use the same
channelId as their jobIds. You don’t get credit for
class-level namespace.

This indeed is a real problem. You need a stable and scalable way to relate a
channelId to its set of jobIds. The last thing you
want is to have different channels overwriting each other’s operations because
of jobId collisions. Were jobId of type String instead
of Integer, the solution would be easy: jobId= "ChannelPrograms" +
channelId
for ChannelProgramsJobService, jobId= "ChannelLogs" +
channelId
for ChannelLoggerJobService, etc. But since
jobId is an Integer and not a String, you have to devise a clever
system for generating reusable jobIds for your jobs. And for that,
you can use something like the following JobIdManager.

JobIdManager is a class that you tweak according to your app’s
needs. For this present TV app, the basic idea is to use a single
channelId over all jobs dealing with Channels. To
expedite clarification: let’s first look at the code for this sample
JobIdManager class, and then we’ll discuss.

public class JobIdManager {

   public static final int JOB_TYPE_CHANNEL_PROGRAMS = 1;
   public static final int JOB_TYPE_CHANNEL_METADATA = 2;
   public static final int JOB_TYPE_CHANNEL_DELETION = 3;
   public static final int JOB_TYPE_CHANNEL_LOGGER = 4;

   public static final int JOB_TYPE_USER_PREFS = 11;
   public static final int JOB_TYPE_USER_BEHAVIOR = 21;

   @IntDef(value = {
           JOB_TYPE_CHANNEL_PROGRAMS,
           JOB_TYPE_CHANNEL_METADATA,
           JOB_TYPE_CHANNEL_DELETION,
           JOB_TYPE_CHANNEL_LOGGER,
           JOB_TYPE_USER_PREFS,
           JOB_TYPE_USER_BEHAVIOR
   })
   @Retention(RetentionPolicy.SOURCE)
   public @interface JobType {
   }

   //16-1 for short. Adjust per your needs
   private static final int JOB_TYPE_SHIFTS = 15;

   public static int getJobId(@JobType int jobType, int objectId) {
       if ( 0 < objectId && objectId < (1<< JOB_TYPE_SHIFTS) ) {
           return (jobType << JOB_TYPE_SHIFTS) + objectId;
       } else {
           String err = String.format("objectId %s must be between %s and %s",
                   objectId,0,(1<<JOB_TYPE_SHIFTS));
           throw new IllegalArgumentException(err);
       }
   }
}

As you can see, JobIdManager simply combines a prefix with a
channelId to get a jobId. This elegant simplicity,
however, is just the tip of the iceberg. Let’s consider the assumptions and
caveats beneath.

First insight: you must be able to coerce channelId into a Short,
so that when you combine channelId with a prefix you still end up
with a valid Java Integer. Now of course, strictly speaking, it does not have to
be a Short. As long as your prefix and channelId combine into a
non-overflowing Integer, it will work. But margin is essential to sound
engineering. So unless you truly have no choice, go with a Short coercion. One
way you can do this in practice, for objects with large IDs on your remote
server, is to define a key in your local database or content provider and use
that key to generate your jobIds.

Second insight: your entire app ought to have only one JobIdManager
class. That class should generate jobIds for all your app’s jobs:
whether those jobs have to do with Channels, Users, or
Cats and Dogs. The sample JobIdManager
class points this out: not all JOB_TYPEs have to do with
Channel operations. One job type has to do with user prefs and one
with user behavior. The JobIdManager accounts for them all by
assigning a different prefix to each job type.

Third insight: for each -JobService in your app, you must have a
unique and final JOB_TYPE_ prefix. Again, this must be an
exhaustive one-to-one relationship.

Using JobIdManager

The following code snippet from ChannelProgramsJobService
demonstrates how to use a JobIdManager in your project. Whenever
you need to schedule a new job, you generate the jobId using
JobIdManager.getJobId(...).

import android.app.job.JobInfo;
import android.app.job.JobParameters;
import android.app.job.JobService;
import android.content.ComponentName;
import android.content.Context;
import android.os.PersistableBundle;

public class ChannelProgramsJobService extends JobService {
  
   private static final String CHANNEL_ID = "channelId";
   . . .

   public static void schedulePeriodicJob(Context context,
                                      final int channelId,
                                      String channelName,
                                      long intervalMillis,
                                      long flexMillis)
{
   JobInfo.Builder builder = scheduleJob(context, channelId);
   builder.setPeriodic(intervalMillis, flexMillis);

   JobScheduler scheduler = 
            (JobScheduler) context.getSystemService(Context.JOB_SCHEDULER_SERVICE);
   if (JobScheduler.RESULT_SUCCESS != scheduler.schedule(builder.build())) {
       //todo what? log to server as analytics maybe?
       Log.d(TAG, "could not schedule program updates for channel " + channelName);
   }
}

private static JobInfo.Builder scheduleJob(Context context,final int channelId){
   ComponentName componentName =
           new ComponentName(context, ChannelProgramsJobService.class);
   final int jobId = JobIdManager
             .getJobId(JobIdManager.JOB_TYPE_CHANNEL_PROGRAMS, channelId);
   PersistableBundle bundle = new PersistableBundle();
   bundle.putInt(CHANNEL_ID, channelId);
   JobInfo.Builder builder = new JobInfo.Builder(jobId, componentName);
   builder.setPersisted(true);
   builder.setExtras(bundle);
   builder.setRequiredNetworkType(JobInfo.NETWORK_TYPE_ANY);
   return builder;
}

   ...
}

Footnote: Thanks to Christopher Tate and Trevor Johns for their invaluable
feedback

Video Playback with the Google Assistant on Android TV

Posted by Benjamin Baxter, Developer Programs Engineer

How to integrate the Google Assistant in a TV app

Earlier this year, we announced that the Google Assistant will be coming to Android TV and it has arrived. The Google Assistant on Android TV will allow users to discover, launch and control media content, control smart devices like light bulbs, and much more. Your Assistant also understands that you’re interacting on a TV, so you’ll get the best experience possible while watching your favorite movies and TV shows.

The Google Assistant has a built-in capability to understand commands like “Watch The Incredibles”, and media controls, like pause, fast forward, etc. This article will walk through how to integrate the Google Assistant into your application.

There are no new APIs needed to integrate with the Google Assistant. You just need to follow the pattern that the Google Assistant expects from your app. If you want to experiment and play with the APIs and the Assistant, you can download this sample from github.

Discovery

The Google Assistant has made some changes to improve finding information on Android TV.

There are a few ways to expose your content to users through the Google Assisant.

Server side integration. (Requires registration and onboarding)

You need to provide your content catalog to Google. This data is ingested and available to the Google Assistant outside of your app.

This is not specific for Google Assistant. It will also enable other Google services such as search and discovery on Google Search, Google Play, Google Home App, and Android TV.

Client side integration. (Available to all apps)

If your app is already searchable, then you only need to handle the EXTRA_START_PLAYBACK flag, which we go into more detail later. Content will auto-play if the app name is explicitly specified in the search results or if the user is already in your app.

Once your app is searchable, you can test by asking the Assistant or, if you are in a loud area, test quietly by running the following adb command:

adb shell am start -a "android.search.action.GLOBAL_SEARCH" --es query \"The Incredibles\" 

Each app that responds to the search query will have a row displaying their search results. Notice that YouTube and the sample app, Assistant Playback, each receive their own rows for content that match the search query.

For specific searches such as “Play Big Buck Bunny”, the Assistant will present a card with a button for each app that exactly matched the search query. In the screenshot below, you can see the sample app, Assistant Playback, shows up as an option to watch Big Buck Bunny.

There are times when the Google Assistant will launch an app directly to start playing content. An example of when this occurs is when content is exclusive to the app; “Play the Netflix original House of Cards”.

Launching

When the user selects a video from search results, an intent is sent to your app. The priority order for the intent actions are as follows:

  1. Intent specified in the cursor returned from the search (SUGGEST_COLUMN_INTENT_ACTION).
  2. Intent specific in the searchable.xml file with the searchSuggestIntentAction value.
  3. Defaults to ACTION_VIEW.

In addition, the Assistant will also pass an extra to signal if playback should begin immediately. You app should be able to handle the intent and expect a boolean extra called EXTRA_START_PLAYBACK.

import static android.support.v4.content.IntentCompat.EXTRA_START_PLAYBACK;

public class SearchableActivity extends Activity {

   @Override
   protected void onCreate(@Nullable Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       if (getIntent() != null) {
           // Retrieve video from getIntent().getData().

           boolean startPlayback = getIntent().getBooleanExtra(EXTRA_START_PLAYBACK, false);
           Log.d(TAG, "Should start playback? " + (startPlayback ? "yes" : "no"));

           if (startPlayback) {
               // Start playback.
               startActivity(...);
           } else {
               // Show details for movie.
               startActivity(...);
           }
       }
       finish();
   }
}

You can test this by modifying and running the following adb command. If your app has a custom action, then replace android.intent.action.VIEW with the custom action. Replace the value of the -d argument with the URI you return from the Assistant’s query.

adb shell 'am start -a android.intent.action.VIEW --ez
android.intent.extra.START_PLAYBACK true -d <URI> -f 0x14000000'

The -f argument is the logical OR value from FLAG_ACTIVITY_NEW_TASK | FLAG_ACTIVITY_CLEAR_TOP. This will force your activity to be freshly launched.

For example, in the sample app, you can run the following command to launch playback of “Big Buck Bunny” as if the assistant had launched it.

adb shell 'am start -a android.intent.action.VIEW --ez
android.intent.extra.START_PLAYBACK true -d 
content://com.example.android.assistantplayback/video/2 -n
com.example.android.assistantplayback/.SearchableActivity -f 0x14000000'

The URI above is defined by the value of android:searchSuggestIntentData in searchable.xml (content://com.example.android.assistantplayback/video/) in addition to the value of SearchManager.SUGGEST_COLUMN_INTENT_DATA_ID (2) returned from the query.

Note that intents may be cached by the Google Assistant up to 7 days. Your app could receive a request to play content that is no longer available. The intent handler should be designed to be stateless and not rely on any previously knowledge to handle the deep link. Your app should gracefully handle this situation. One solution would be to show an error message and let the user land on your main activity or another relevant activity.

Playback

If your app implements MediaSession correctly, then your app should work right away with no changes.

The Google Assistant assumes that your app handles transport controls. The Assistant uses the TransportControls to send media commands to your app’s MediaSession. Video apps must support the following controls wherever possible:

  • Play/Pause/Stop
  • Previous/Next
  • Rewind/Fast Forward (implemented with seekTo())

You can easily get a hook for these controls by implementing a MediaSession.Callback. If you play videos using PlaybackTransportControlGlue, then all your callback needs to do it sync the glue and the MediaSession. Otherwise use this callback to sync your player.

public class MyMediaSessionCallback extends MediaSessionCompat.Callback {

   private final PlaybackTransportControlGlue<?> mGlue;

   public MediaSessionCallback(PlaybackTransportControlGlue<?> glue) {
       mGlue = glue;
   }

   @Override
   public void onPlay() {
       Log.d(TAG, "MediaSessionCallback: onPlay()");
       mGlue.play();
       updateMediaSessionState(...);
   }

   @Override
   public void onPause() {
       Log.d(TAG, "MediaSessionCallback: onPause()");
       mGlue.pause();
       updateMediaSessionState(...);
   }

   @Override
   public void onSeekTo(long position) {
       Log.d(TAG, "MediaSessionCallback: onSeekTo()");
       mGlue.seekTo(position);
       updateMediaSessionState(...);
   }

   @Override
   public void onStop() {
       Log.d(TAG, "MediaSessionCallback: onStop()");
       // Handle differently based on your use case.
   }

   @Override
   public void onSkipToNext() {
       Log.d(TAG, "MediaSessionCallback: onSkipToNext()");
       playAndUpdateMediaSession(...);
   }

   @Override
   public void onSkipToPrevious() {
       Log.d(TAG, "MediaSessionCallback: onSkipToPrevious()");
       playAndUpdateMediaSession(...);
   }
}

Continue learning

Check out the following articles and training documents to continue learning about MediaSession and Video apps.

To play around with the Google Assistant on Android TV, download the sample app and run it on Nvidia Shield running Android M or above.

If you would like to continue the discussion, leave a response or talk to me on Twitter.