Skip to content

Android PED Bookmark#

Step 1: Bookmark Object Initialization via Seat Pairing#

Initialize the seat pairing service between the passenger’s personal device and the in-flight entertainment (IFE) system. This pairing allows the phone (PED) to interact with the seatback monitor, including managing the media player.

a.Property Declaration

  private SeatBookmarkV1 mSeatBookmarkV1;

mSeatBookmarkV1 is declared as a property of the class. This object represents the service that manages the flow of bookmark between the PED and the IFE system.

b.Seat Pairing Initialization

The following block initializes the seat pairing service, which is necessary for enabling communication between the phone and the seatback monitor:

SeatPairingV1.initService(this,
        new IInFlightCallback() {
            @Override
            public void onInitServiceComplete(Object o, String s) {
                // If the initialization succeeds, cast the returned object into SeatPairingV1
                mSeatPairingV1 = (SeatPairingV1) o;
                if (mSeatPairingV1 != null) { // Check if mSeatPairingV1 is not null before proceeding with pairing-related operations

// Initialize mSeatBookmarkV1 to manage the transfer of bookmarks items between the Passenger Entertainment Device (PED) and the In-Flight Entertainment (IFE) system
                      mSeatBookmarkV1 = mSeatPairingV1.getSeatBookmark();
                }
            }
            @Override
            public void onInitServiceFailed(String s, InFlight.Error error) {
                // Handle initialization failure
            }
        }, new InFlight());

Step 1: Initialize SeatPairingService: Calls initService on the SeatPairingV1, passing a callback to handle successful initialization.

Step 2: Store SeatPairingService Instance: The SeatPairingV1 object is stored in a class-level property called mSeatPairingV1. This allows other parts of the app to interact with the pairing service.

Step 3: mSeatPairingV1.getSeatBookmark: The key here is the retrieval of the getSeatBookmark. This service is part of the seat pairing object and allows managing the bookmark between the phone and the seatback monitor.

At this point, the Bookmark service is now initialized and available for further actions like playing the media from elapsed time.

Step 2: Creating a Bookmark Locally on a PED#

A Bookmark object stores essential media information, including the media URI (identifier of the media), parent media URI (for TV episodes), subtitle and soundtrack codes, subtitle and soundtrack types, and most importantly, the elapsed time, which indicates how long the media has been watched.

There are two primary methods to create a bookmark locally on a Personal Electronic Device (PED) using the remote controller API or the media queue method. Below are the detailed steps for both methods.

Method 1: Using Remote Controller API

  1. Accessing Remote Controllers:

    • The remoteController is an instance of SeatMediaRemoteController.

    • You can get the list of seat media remote controllers using the getSeatMediaRemoteControllers method.

    • Example code: SeatMediaRemoteController

      ArrayList<mSeatMediaRemoteController>
      
  2. Create Current Bookmark from the Remote Controller:

    • You can create a Bookmark object by accessing the current bookmark from the selected remote controller's player information. This will create media with the object which is playing at that time.

    • Current Bookmark

      // Check if the Seat Media Remote Controller is initialized
      if (mSeatMediaRemoteController != null) {
          try {
              // Attempt to create a bookmark and add it to the bookmarks list
              boolean isAdded = mSeatBookmarkV1.add(mSeatMediaRemoteController.createBookmark());
      
          } catch (Exception e) {
              // Log the exception if an error occurs
              e.printStackTrace();
          }
      }
      

Method 2: Using Media Queue Method

  1. Create Current Bookmark from the Media Queue Service:

    • You can create a Bookmark object by accessing the current bookmark from the mSeatRemoteMediaQueue.
    • The current media item is accessed from mSeatRemoteMediaQueue.getCurrentQueueItem().getMediaUri().
    • A Bookmark object is created using mSeatRemoteMediaQueue.createBookmark().
    • The bookmark should be saved at a specific path within the application's directory.
    • Current Bookmark
      // Create a bookmark for the current media item
      String fullPath = getBookmarkFilePath(mSeatRemoteMediaQueue.getCurrentQueueItem().getMediaUri());
      SeatBookmarkV1.Bookmark bookmark = mSeatRemoteMediaQueue.createBookmark();
      // Save the bookmark at some path eg. relative path within your application's directory structure
      bookmark.saveBookmark(fullpath);
      
  2. For example: Logic to retrieve full path

  3. The getBookmarkFilePath(String mediaUri) method generates a path to store the bookmark file.
  4. The directory /bookmarks is created if it doesn’t exist.
  5. The bookmark file is named using "bookmark_" + mediaUri.

    private String getBookmarkFilePath(String mediaUri) {
        String path = getFilesDir().getAbsolutePath() + "/bookmarks";
        File f = new File(path);
        if (!f.exists()) {
            f.mkdir();
        }
        String bookmarkFileName = "bookmark";
        String result = path + "/" + bookmarkFileName + "_" + mediaUri;
        Log.d(TAG, "getBookmarkFilePath=" + result);
        return result;
    }
    
  6. A saved bookmark can be loaded using SeatBookmarkV1.Bookmark(getBookmarkPath(mediaUri)), which fetches the previously stored bookmark for the given media. new SeatBookmarkV1.Bookmark(getBookmarkPath(mediaUri))

  7. Accessing Media Queue Service:

  8. The mSeatRemoteMediaQueue should be declared as a property of type SeatRemoteMediaQueueV1:
    private SeatRemoteMediaQueueV1 mSeatRemoteMediaQueue;
    

Note: The recommended approach for creating a bookmark in the application is to do so when the onSeatMediaRemoteControllerInfoChanged object indicates a pause or stop state. Developers should avoid creating a bookmark for every onSeatMediaRemoteControllerInfoChanged received, as this notification is triggered every 30 seconds on the PED side. Detailed instructions on observing this notification can be found in the Android PED Remote Control Developer guide. Additionally, it is advised to check the media's elapsed time, as bookmarks should generally not be created if the media has been watched beyond 95%. These are best practices but not strict requirements.

Step 3: Pushing the Bookmark to the Seat#

Once you have created the Bookmark object, you can push the bookmark to the seat using the sendPushBookmarksToSeatcmd API.

  • Push Bookmark
// Load the locally saved bookmarks into a list
List<SeatBookmarkV1.Bookmark> bookmarks = loadSavedBookmaks();

// Send the loaded bookmarks to the seat system
// bookmarks - List of bookmarks to be pushed
//extras - Object of JSONObject class, Provide instructions to the head-end on how to handle the bookmark list transmitted from the PED to the seat.

mSeatBookmarkV1.sendPushBookmarksToSeatCmd( bookmarks, extras, new SeatBookmarkV1.OnBookmarksPushListener() {
        @Override
        public void onSeatBookmarkCommandSendSuccess() {
            // Log a success message when bookmarks are pushed successfully
            }
        @Override
        public void onSeatBookmarkCommandSendError(Error error) {
            // Log an error message if pushing bookmarks fails
        }
    }
);

Parameters:

  • bookmarks: List of bookmarks to be transmitted from the PED to the seat.

  • extras : Object of JSONObject class, Provide instructions to the head-end on how to handle the bookmark list transmitted from the PED to the seat.

e.g. JSONObject jsonObject = new JSONObject();

jsonObject.put("append", true);

if append as true - It updates the bookmark on the seat

if append as false - It clears the existing bookmark and add the bookmark in the seat

  • onBookmarksPushListener: SeatBookmarkV1.OnBookmarksPushListener invoked upon completion.

Using the Bookmark While Playing Media from the PED#

  • Bookmarks can also be utilized while playing media from the PED.

  • Bookmark details can be sent along with media playback requests.

    Summary

  • Method 1: Create a bookmark using the remote controller API.

  • Method 2: Create a bookmark using the media queue method.

  • Pushing Bookmarks: Use sendPushBookmarksToSeatcmd API to push the bookmark to the seat.

  • Media Playback: Utilize bookmarks while playing media from the PED, with details provided in the media queue documentation.

Step 4: Retrieving the Bookmark from the Seat#

Method: sendRetrieveBookmarksFromSeatCmd

This method sends a request to retrieve all bookmarks from the seatback unit. It allows the Companion Application to access the list of media bookmarks saved on the seat.

Pull Bookmark

// Initiate the process to retrieve bookmarks from the seat system
mSeatBookmarkV1.sendRetrieveBookmarksFromSeatCmd(null, new SeatBookmarkV1.OnBookmarksRetrieveListener() {
    @Override
    public void onBookmarksRetrieveSuccess(List<SeatBookmarkV1.Bookmark> bookmarkList) {
        // Log a message indicating successful retrieval of bookmarks
        Log.d(TAG, "Implicit bookmarks received successfully: " + bookmarkList);
        // Iterate through the retrieved bookmarks list
        for (SeatBookmarkV1.Bookmark b : bookmarkList) {
            // Save each bookmark to a file using its media URI
            b.saveBookmark(getBookmarkFilePath(b.getMediaUri()));
        }
        //Update the UI or internal state to reflect the retrieved bookmarks
    }

    @Override
    public void onSeatBookmarkCommandSendError(Error error) {
        // Log an error message if retrieving bookmarks fails
    }
});

Parameters:

  • extras: A dictionary of extra parameters to be passed to the seat. This can be used to provide additional context or options for the request. This parameter is optional and can be null.

  • onBookmarksRetrieveListener -: A completion handler that will be called when the request ends. This handler will provide feedback on whether the request was successful or if an error occurred.

Step 5. Bookmark Syncing and Conflict Resolution#

To ensure a seamless passenger experience, bookmark synchronization allows media playback progress to be updated between the PED (Personal Electronic Device) and the seatback In-Flight Entertainment (IFE) system. This ensures that passengers can resume their media from the last watched position, regardless of the device.

However, conflicts may arise when the same media exists on both PED and IFE with different elapsed times. In such cases, conflict resolution is required before synchronization can proceed.

Syncronization is handled using the Bookmarks class from the User Module.

5.1. Synchronizing Bookmarks

To sync the bookmark object, we need to initialize Bookmarks and call the synchronize API.

private Bookmarks bookmarks;
Bookmarks.initService(this,new

    IInFlightCallback() {
        @Override
        public void onInitServiceComplete (Object o, String s){
            bookmarks = (Bookmarks) o;
            if (bookmarks != null) {
                Log.v(TAG, "initialize bookmarks succeed.");
                bookmarks.setSyncListener(new Sync.SyncListener() {
                    @Override
                    public void onUserDataChanged() {
                        Log.v(TAG, "onUserDataChanged()");
                    }

                    @Override
                    public void onConflict(List<? extends ConflictItem> list) {
                        Log.v(TAG, "onConflict(): " + list);
                    }

                    @Override
                    public void onSyncFinished(Date date) {
                        Log.v(TAG, "onSyncFinished()");
                    }

                    @Override
                    public void onSyncFailed(SyncError syncError) {
                        Log.v(TAG, "onSyncFailed()");
                    }
                }
                else{
                    Log.e(TAG, "initialize bookmarks failed.");
                }
            }
            @Override
            public void onInitServiceFailed (String s, InFlight.Error error){
                Log.e(TAG, "initialize bookmarks failed.");
            }
        },new InFlight());

The Bookmarks class includes a method called setSyncListener, which is used to register a listener of type Sync.SyncListener. This listener is responsible for providing real-time updates whenever a passenger adds a bookmark through a Passenger Electronic Device (PED) or any other In-Flight Entertainment (IFE) component.

The Sync.SyncListener offers several callback methods to handle different synchronization events:

  • onUserDataChanged – Triggered when a user's bookmark data is modified.

  • onConflict – Invoked when a synchronization conflict occurs, requiring resolution.

  • onSyncFinished – The method is invoked upon the successful completion of the synchronization process and returns a Date object that represents the timestamp of the last synchronization.

  • onSyncFailed – Executed if the synchronization process encounters an error.

bookmarks.setSyncListener(new Sync.SyncListener() {
            @Override
            public void onUserDataChanged() {
                Log.v(TAG, "onUserDataChanged()");
            }
            @Override
            public void onConflict(List<? extends ConflictItem> list) {
                Log.v(TAG, "onConflict(): "+list);
            }
            @Override
            public void onSyncFinished(Date date) {
                Log.v(TAG, "onSyncFinished()");
            }
            @Override
            public void onSyncFailed(SyncError syncError) {
                Log.v(TAG, "onSyncFailed()");
            }

5.2 Bookmark conflicts and resolving methods

5.2.1 Set conflict strategy

This method is used to define the conflict strategy, during synchronization between the Passenger Entertainment Device (PED) and the seatback monitor. When both devices attempt to update bookmark data simultaneously, inconsistencies may arise due to differences in stored playback positions. The In-Flight Entertainment (IFE) system resolves conflicts according to the chosen conflict resolution strategy. There are two distinct types of conflict resolution strategies,

  • KEEP_LATEST - If application developers prefer the SDK to manage conflicts automatically, they can specify the KEEP_LATEST option. When this option is enabled, the SDK resolves conflicts by selecting the most recently updated data. As a result, conflicts within the specified dataset are handled internally by the SDK, ensuring that the latest changes are retained without triggering any conflict notifications in the application.

Scenario : Automatic Resolution (KEEP_LATEST Resolution Strategy)

In this case, the system resolves the conflict automatically by keeping the bookmark with the longer elapsed time, assuming that the passenger has watched more of the media.

Example Conflict:

A movie named Spider-Man exists on both PED and IFE:

  • PED Bookmark: The elapsed time is 20 minutes.

  • IFE Bookmark: The elapsed time is 40 minutes.

Resolution:

The system detects the conflict and resolves it automatically:

Conflict detected for "Spider-Man". Automatically resolved: Keeping IFE bookmark (elapsed time 40:00).
The PED bookmark list is updated to match the IFE bookmark.

  • USER_DEFINED - If application developers prefer to manage conflicts manually, they can specify the USER_DEFINED option. With this setting, the SDK triggers the onConflict(List) method, providing a list of conflicts within the application for the specified dataset. Developers must then manually resolve each conflict by invoking the resolve() method on individual conflict items. Once all conflicts have been addressed, the SDK proceeds with synchronization. The available conflict resolution strategies define how these conflicts can be managed effectively.
public void setConflictStrategy(ConflictStrategy strategy)

5.2.2 Get a List of conflicts

public List<BookmarkConflictItem> getConflicts()

This method is responsible for retrieving a list of conflicts that arise during the synchronization of bookmarks. It returns a list of BookmarkConflictItem objects, where each item represents an individual conflict.

Each BookmarkConflictItem contains:

  • A Map that holds both the Local Bookmark (the bookmark stored on the current device) and the Remote Bookmark (the bookmark received from the IFE server).

  • A method that allows the resolution of conflicts using user-defined techniques.

There are two available conflict resolution methods, each providing a different approach to handling discrepancies between the local and remote bookmark data.

These two conflict resolution strategies are defined using the ConflictResolution enumeration, and they are

  • LOCAL_CONFLICT - Select the locally stored item to resolve the conflict.

  • REMOTE_CONFLICT - Select the remotely stored item to resolve the conflict.

5.2.3 Resolve Conflict

The BookmarkConflictItem class includes the resolveConflict method, responsible for resolving conflicts between local and remote bookmarks.

List<BookmarkConflictItem> bookmarkConflictItemList = bookmarks.getConflicts();
for (BookmarkConflictItem item : bookmarkConflictItemList) {
    Map<String,List<Bookmark>> localBookmarks = item.getLocalBookmarks();
    Map<String,List<Bookmark>> remoteBookmark = item.getRemoteBookmarks();
    item.resolveConflict(ConflictResolution.LOCAL_CONFLICT);
}

In the example above, the list of BookmarkConflictItem objects is retrieved using the getConflicts method of the Bookmarks class. This method provides both the local and remote bookmarks. The BookmarkConflictItem class also includes the resolveConflict method, which resolves conflicts using the specified conflict resolution option. In this case, LOCAL_CONFLICT is selected to resolve the conflict.

Scenario : User Choice to Resolve Conflict (USER_DEFINED Resolution Strategy)

In this approach, the passenger manually selects which bookmark to retain.

Example Conflict:

A movie named Spider-Man exists on both PED and IFE:

  • PED Bookmark: The elapsed time is 20 minutes.

  • IFE Bookmark: The elapsed time is 40 minutes.

Resolution Process:

The PED prompts the passenger to choose:

A conflict was detected for "Spider-Man".
- PED bookmark: Resume from 20:00.
- IFE bookmark: Resume from 40:00.
Choose an option:
[Keep PED Bookmark] [Keep IFE Bookmark]

5.2.4 Synchronize Method

After resolving conflicts, use mBookmarks.synchronize() method to sync the PED and IFE bookmarklist.

Map<String, List<Bookmark>> bookmarks = loadSavedBookmaks();
Log.d(TAG, "Loading saved bookmarks with # items: " + bookmarks.size());
mBookmarks.synchronize();

Important Considerations#

  • Sync Engine Requirement: Synchronization is only possible if the IFE system includes the Sync Engine component. Otherwise, bookmark synchronization must be handled at the application level.

  • Passenger Experience: By resolving conflicts efficiently, passengers can enjoy an uninterrupted media experience across devices.

Version 1.0