Android Pluginentwicklung

Diese Anleitung erklärt, wie Plugins für die Android-App von TV-Browser geschrieben werden.

Grundlagen

Die Android-App von TV-Browser verwendet die AIDL um Plugins in die App einbinden zu können. Ein Plugin stellt dabei einen Service dar. Ein Plugin für die Android-App wird als eine Klasse geschrieben, die das Service-Interface implementiert.

Um ein Plugin schreiben zu können ist das AIDL-Paket der TV-Browser-App notwendig: TvBrowserAidlPluginPackage_v1.zip

Der Inhalt dieses Pakets muss in den src-Ordner der Plugin-App entpackt werden.

Beispiel:

package org.tvbrowser.myplugin

import android.app.Service;

public class MyPlugin extends Service {

  @Override
  public IBinder onBind(Intent intent) {
    ...
  }
  
  ...
}

Es ist empfehlenswert die Plugin-App unter dem Package org.tvbrowser einzulisten, damit diese auf Google Play™ leichter gefunden werden kann.

Die Methode onBind muss einen IBinder vom Typ org.tvbrowser.devplugin.Plugin.Stub zurückgeben. Dieser IBinder stellt die eigentliche Plugin-Funktionalität zur Verfügung.

Ein Beispiel für einen Plugin-Service kann hier eingesehen werden.

Dieser Service muss nun noch in der AndroidManifest.xml unter <application> eingetragen werden.

Beispiel:

        <service
            android:name=".MyPlugin"
            android:label="1"
            android:permission="org.tvbrowser.permission.BIND_PLUGIN"
            android:exported="true">
            <intent-filter>
                <action android:name="org.tvbrowser.intent.action.PLUGIN"/>
                <category android:name="org.tvbrowser.intent.category.MyPlugin"/>
            </intent-filter>

        </service>

Für android:label muss die Version der verwendeten Plugin-Schnittstelle eingetragen werden, damit TV-Browser weiß mit welcher Version der Plugin-Schnittstelle auf das Plugin zugegriffen werden muss. Sollen nur Applikationen mit der Berechtigung org.tvbrowser.permission.BIND_PLUGIN auf den Plugin-Service zugreifen können (also in der Regel nur die TV-Browser-App), dann muss diese Berechtigung für den Service mit android:permission eingetragen werden. Damit TV-Browser auf den Service zugreifen kann, muss dieser mit android:exported="true" nach außen geöffnet sein.

Jeder Plugin-Service muss über einen Intent-Filter verfügen, der als action android:name den Wert org.tvbrowser.intent.action.PLUGIN setzt und für category android:name den Wert org.tvbrowser.intent.category.PLUGINSERVICECLASSNAME wobei PLUGINSERVICECLASSNAME durch den Klassennamen des Plugin-Service zu ersetzen ist. Dieser muss eineindeutig sein, es darf also kein Name sein, den ein anderes Plugin verwendet.

Über den Intent-Filter findet die TV-Browser-App die verfügbaren Plugins. Ein Plugin kann entweder eine eigenständige App mit nur einem Service sein, oder aber auch ein Service der innerhalb einer App, mit eigener Funktionalität, angeboten wird. Man kann natürlich auch mehrere Plugin-Service in einer App anbieten, TV-Browser wird diese dann als eigenständige Plugins behandeln.

Methoden aus org.tvbrowser.devplugin.Plugin

Die Funktionalität des Plugins wird durch die Methode aus org.tvbrowser.devplugin.Plugin zur Verfügung gestellt. Da es sich hierbei um ein Interface handelt, muss die Implementation von org.tvbrowser.devplugin.Plugin.Stub alle Methoden überschreiben. Man muss aber nicht auf jede dieser Methoden reagieren.

Allgemeine Informationen über das Plugin

Folgende allgemeine Informationen über ein Plugin, werden mit den folgenden Methode abgefragt:

• String getVersion() {
• String getName() {
• String getDescription() {
• String getAuthor() {
• String getLicense() {

getVersion()

Mit der Methode getVersion() wird ein String zurückgegeben, der die Version des Plugins definiert. Wie diese Version aussieht bleibt dem Plugin-Entwickler überlassen.

getName()

Mit der Methode getName() wird ein String zurückgegeben, der den Namen des Plugins enthält. Es ist sinnvoll hier lokalisierte Namen zurückzugeben.

getDescription()

Mit der Methode getDescription() wird ein String zurückgegeben, der eine Beschreibung der Funktion des Plugins enthält. Es ist sinnvoll hier lokalisierte Beschreibungen zurückzugeben.

getDescription()

Mit der Methode getAuthor() wird ein String zurückgegeben, der den Namen des Autors enthält.

getLicense()

Mit der Methode getLicense() wird ein String zurückgegeben, der die Lizenz des Plugins enthält. Es ist sinnvoll hier eine lokalisierte Lizenz zurückzugeben.

Aktivierung des Plugins

Bei der Aktivierung eines Plugins wird TV-Browser bestimmte Methoden aufrufen, diese Methoden werden ausschließlich bei der Aktivierung aufgerufen. Eine Aktivierung wird entweder ausgelöst, wenn TV-Browser gestartet wird und das Plugin in den Einstellungen von TV-Browser aktiviert ist oder wenn es in den Einstellungen von TV-Browser aktiviert wird. Die entsprechenden Methoden sind:

• void onActivation() {
• void handleFirstKnownProgramId(long programId) {
• long[] getMarkedPrograms() {

void onActivation()

Diese Methode wird aufgerufen, damit ein Plugin Aktionen ausführen kann, wie z.B. das Laden von Einstellungen.

void handleFirstKnownProgramId(long programId)

Mit dieser Methode wird das Plugin über die kleinste bekannte Sendungs-ID informiert. Sollte das Plugin Informationen über Sendungen mit kleinerer Sendungs-ID gespeichert haben, dann sollten diese hier gelöscht werden, da sie nicht mehr aktuell sind, da Sendungen mit kleinerer Sendungs-ID nicht mehr existieren. (ZUR ZEIT NOCH NICHT IN TV-BROWSER IMPLEMENTIERT)

long[] getMarkedPrograms()

Hier kann ein Plugin ein Array mit Sendungs-IDs zurückgeben, die in TV-Browser markiert werden sollen. (ZUR ZEIT NOCH NICHT IN TV-BROWSER IMPLEMENTIERT)

Deaktivierung des Plugins

Wird das Plugin deaktiviert (weil der Nutzer es deaktiviert hat oder TV-Browser beendet wurde), dann wird die Methode void onDeactivation() { aufgerufen. Hier sollte das Plugin spätestens alle Einstellungen speichern.

Einstellungen des Plugins

Ein Plugin kann eigene Einstellungen anbieten, um die Funktionalität zu konfigurieren. Dazu existieren folgende Methoden:

• boolean hasPreferences() {
• void openPreferences(List<Channel> subscribedChannels) {

boolean hasPreferences()

Mit dieser Methode wird abgefragt, ob ein Plugin eigene Einstellungen anbietet. Es muss true zurückgegeben werden, wenn das Plugin eigene Einstellungen anbietet oder false zurückgegeben werden, falls nicht.

void openPreferences(List<Channel> subscribedChannels)

Hat ein Plugin bei der Abfrage durch boolean hasPreferences() true zurückgegeben, kann der Aufruf dieser Methode durch den Benutzer ausgelöst werden. Wie die Einstellungen auf Seite des Plugins konfiguriert sind ist nicht festgelegt. Es kann eine eigene simple Activity zur Einstellung verwendet werden oder, was der bevorzugte Weg ist, eine PreferencesActivity mit PreferencesHeaders verwendet werden. Der Methode werden als Parameter eine Liste mit den Sender übergeben, die der Benutzer in der TV-Browser-App abonniert hat.

Funktionen zu Sendungen von TV-Browser

Die Funktionen für Sendungen von TV-Browser werden über ein Kontextmenü angeboten, Plugins können eigene Funktionen für das Kontextmenü von TV-Browser bereitstellen. Dazu werden die folgenden Methoden verwendet:

• PluginMenu[] getContextMenuActionsForProgram(Program program) {
• boolean onProgramContextMenuSelected(Program program, PluginMenu pluginMenu) {
• byte[] getMarkIcon() {

PluginMenu[] getContextMenuActionsForProgram(Program program)

Wenn der Benutzer das Kontextmenü zu einer Sendung auslöst, wird TV-Browser diese Methode für alle aktiven Plugins aufrufen. Das Plugin kann nun die Sendung program prüfen und für diese spezifische PluginMenus erstellen, die dann zurückgegeben werden. Das PluginMenu muss dafür eine eindeutige ID enthalten, die dieses PluginMenu identifiziert und den Titel des Eintrags für das Kontextmenu. Soll keine Funktion für die übergebene Sendung angeboten werden, muss null zurückgegeben werden.

boolean onProgramContextMenuSelected(Program program, PluginMenu pluginMenu)

Wurde ein Kontextmenueintrag des Plugins von Benutzer ausgewählt wird diese Methode aufgerufen, dieser wird die Sendung program und das ausgewählte Plugin-Menü pluginMenu übergeben. Das Plugin kann jetzt das Plugin-Menü auf die gewählte Funktion prüfen und diese ausführen. Soll die Sendung von TV-Browser markiert werden, muss true zurückgegeben werden, falls nicht, muss false zurückgegeben werden. (DIE MARKIERUNGSFUNKTION FÜR PLUGINS IST ZUR ZEIT NOCH NICHT IN TV-BROWSER IMPLEMENTIERT.)

byte[] getMarkIcon()

Soll die Markierung einer Sendung mit einem Icon hervorgehoben werden, müssen hier die Daten dieses Icons als byte-Array zurückgegeben werden. (ZUR ZEIT NOCH NICHT IN TV-BROWSER IMPLEMENTIERT)