Package com.battlelancer.seriesguide.api

Class SeriesGuideExtension

  • All Implemented Interfaces:
    ComponentCallbacks, ComponentCallbacks2
    public abstract class SeriesGuideExtension
extends JobIntentService
    Base class for a SeriesGuide extension. Extensions are a way for other apps to feed actions (represented through actions) for episodes and movies to SeriesGuide. Actions may for example launch other apps or display interesting information related to an episode or movie.

    Extensions are specialized JobIntentService classes in combination with a broadcast receiver.

    Multiple extensions may be enabled within SeriesGuide at the same time. When a SeriesGuide user chooses to enable an extension, SeriesGuide will subscribe to it prior of requesting actions. If the user disables the extension, SeriesGuide will unsubscribe from it.

    The API is designed such that other applications besides SeriesGuide can subscribe and request actions from an extension.

    Subclassing SeriesGuideExtension

    Subclasses must at least implement onRequest(int, Episode) or onRequest(int, Movie), which is called when SeriesGuide requests actions to display for an episode or movie. Do not perform long running operations here as the user will get frustrated while waiting for the action to appear.

    To publish an action, call publishAction(Action) from onRequest(int, Episode) or onRequest(int, Movie). All current subscribers will then immediately receive an update with the new action information. Under the hood, this is done with broadcast intents.

    As the subclass is a JobIntentService, it needs be declared as a <service> component in the application's AndroidManifest.xml. In addition it must be exported and given the JobService.PERMISSION_BIND permission to integrate with the platforms job scheduler.

    Registering your extension

    An extension is exposed through a broadcast receiver that SeriesGuide and other apps interact with via broadcast intents. This receiver enqueues requests from subscribers to be processed by this service. A simple receiver can be implemented by subclassing SeriesGuideExtensionReceiver.

    The receiver must be declared as a <receiver> component in the application's AndroidManifest.xml file.

    The SeriesGuide app and other potential subscribers discover available extensions using Android's Intent mechanism. Ensure that your receiver definition includes an <intent-filter> with an action of SeriesGuideExtensionReceiver.ACTION_SERIESGUIDE_EXTENSION.

    To make your extension easier to identify for users you should add the following attributes to your receiver definition:

    • android:label (optional): the name to display when displaying your extension in the user interface.
    • android:description (optional): a few words describing what your actions display or can do (e.g. "Displays interesting stat" or "Searches Google").
    • android:icon (optional): a drawable to represent the extension in the user interface.

    If you want to provide a settings activity, add the following <meta-data> element to your receiver definition:

    • settingsActivity (optional): if present, should be the qualified component name for a configuration activity in the extension's package that SeriesGuide can offer to the user for customizing the extension. This activity must be exported.

    Example

    Below is an example extension declaration in the manifest: 
     <receiver android:name=".ExampleExtensionReceiver"
     android:description="@string/extension_description"
     android:icon="@drawable/ic_extension_example"
     android:label="@string/extension_title">
     <intent-filter>
         <action android:name="com.battlelancer.seriesguide.api.SeriesGuideExtension" />
     </intent-filter>
     <!-- A settings activity is optional -->
     <meta-data android:name="settingsActivity"
         android:value=".ExampleSettingsActivity" />
 </receiver>
 <service
     android:name=".ExampleExtension"
     android:exported="true"
     android:permission="android.permission.BIND_JOB_SERVICE" />
    If a settingsActivity meta-data element is present, an activity with the given component name should be defined and exported in the application's manifest as well. SeriesGuide will set the EXTRA_FROM_SERIESGUIDE_SETTINGS extra to true in the launch intent for this activity. An example is shown below: 
     <activity android:name=".ExampleSettingsActivity"
     android:label="@string/title_settings"
     android:exported="true" />
    Finally, below are a simple example SeriesGuideExtensionReceiver and SeriesGuideExtension subclass that publishes actions for episodes performing a simple Google search: 
     public class ExampleExtensionReceiver extends SeriesGuideExtensionReceiver {
     protected int getJobId() {
         return 1000;
     }

     protected Class<? extends SeriesGuideExtension> getExtensionClass() {
         return ExampleExtension.class;
     }
 }

 public class ExampleExtension extends SeriesGuideExtension {
     protected void onRequest(int episodeIdentifier, Episode episode) {
         publishAction(new Action.Builder("Google search", episodeIdentifier)
                 .viewIntent(new Intent(Intent.ACTION_VIEW)
                          .setData(Uri.parse("https://www.google.com/#q="
                                 + episode.getTitle())))
                 .build());
     }
 }

    Based on code from Muzei, an awesome Live Wallpaper by Roman Nurik.

    • Field Detail

      • EXTRA_FROM_SERIESGUIDE_SETTINGS

        public static final String EXTRA_FROM_SERIESGUIDE_SETTINGS
        Boolean extra that will be set to true when SeriesGuide starts the extensions (optionally) declared settings activity. Check for this extra in your settings activity if you need to adjust your UI depending on whether or not the user came from SeriesGuide's settings screen.
        See Also:
        Constant Field Values

    • Constructor Detail

      • SeriesGuideExtension

        public SeriesGuideExtension​(String name)
        Call from your default constructor.
        Parameters:
        name - Gives the extension a name. This is not user-visible, but will be used to store preferences and state for the extension.

    • Method Detail

      • getSharedPreferences

        protected static SharedPreferences getSharedPreferences​(Context context,
                                                        String extensionName)
        Convenience method for accessing preferences specific to the extension (with the given name within this package. The source name must be the one provided in the SeriesGuideExtension(String) constructor. This static method is useful for exposing extension preferences to other application components such as a settings activity.
        Parameters:
        context - The context; can be an application context.
        extensionName - The source name, provided in the SeriesGuideExtension(String) constructor.

      • onAllowSubscription

        protected boolean onAllowSubscription​(ComponentName subscriber)
        Method called before a new subscriber is added that determines whether the subscription is allowed or not. The default behavior is to allow all subscriptions.
        Returns:
        true if the subscription should be allowed, false if it should be denied.

      • onSubscriberAdded

        protected void onSubscriberAdded​(ComponentName subscriber)
        Lifecycle method called when a new subscriber is added. Extensions generally don't need to override this.

      • onSubscriberRemoved

        protected void onSubscriberRemoved​(ComponentName subscriber)
        Lifecycle method called when a subscriber is removed. Extensions generally don't need to override this.

      • onEnabled

        protected void onEnabled()
        Lifecycle method called when the first subscriber is added. This will be called before onSubscriberAdded(ComponentName). Extensions generally don't need to override this.

      • onDisabled

        protected void onDisabled()
        Lifecycle method called when the last subscriber is removed. This will be called after onSubscriberRemoved(ComponentName). Extensions generally don't need to override this.

      • onRequest

        protected void onRequest​(int episodeIdentifier,
                         Episode episode)
        Called when an episode is displayed and the extension should publish the action it wants to display using publishAction(Action).
        Parameters:
        episodeIdentifier - The episode identifier the extension should submit with the action it wants to publish.

      • onRequest

        protected void onRequest​(int movieIdentifier,
                         Movie movie)
        Called when a movie is displayed and the extension should publish the action it wants to display using publishAction(Action).
        Parameters:
        movieIdentifier - The movie identifier the extension should submit with the action it wants to publish.

      • publishAction

        protected final void publishAction​(Action action)
        Publishes the provided Action. It will be sent to all current subscribers.

      • getCurrentAction

        protected final Action getCurrentAction()
        Returns the most recently published Action, or null if none was published, yet.