Parental Control Android#
The Seat Rating API is integrated within the Seat-Pairing module of the Companion App's SDK. The pairing between the companion app and the seat is essential for the seat rating functionality. This API allows passengers to set or reset parental ratings through the Companion App. Based on the configured rating and the associated seat, the content displayed is filtered accordingly to ensure age-appropriate viewing. Additionally, the API listens for any changes to the parental rating settings; when a rating is updated, the content presented within the Companion App dynamically adjusts to reflect the new rating level.
The rating API’s are accessible exclusively when the PED is operating in Air Mode. This means that the API functionality is limited to in-flight scenarios and is not available during ground operations.
1. Initialisation of Seat Rating#
To utilize the SeatRating functionality, it is crucial to first initialize the SeatPairing module. This module is responsible for providing the SeatRatingV1 object, which serves as the primary interface for all seat rating operations. Through the SeatRatingV1 object, you can perform various actions, such as retrieving the list of seat ratings, setting a specific rating for a seat, resetting existing ratings, and more.
// Declare property
private SeatRatingV1 mSeatRatingV1;
SeatPairingV1.initService(this, new IInFlightCallback() {
@Override
public void onInitServiceComplete(Object o, String s) {
Log.v(tag, "onInitServiceComplete() " + s);
// Seat Pairing module initialization completed successfully
mSeatPairingV1 = (SeatPairingV1) o;
// Getting SeatRatingV1 object from the SeatPairingV1 object
// The SeatRatingV1 contains the various method those are required for the SeatRating operation
mSeatRatingV1 = mSeatPairingV1.getSeatRating();
}
@Override
public void onInitServiceFailed(String s, InFlight.Error error) {
Log.e(tag, "onInitServiceFailed() " + InFlight.Error.getErrorMessage(error));
}
}, new InFlight());
In the example above, the SeatPairing module is initialized. Upon successful initialization, it returns a SeatPairingV1 object. This object, in turn, provides access to the SeatRatingV1 object, which is used to perform further seat rating operations.
2. Get the list of parental ratings#
This method retrieves the list of available parental ratings. It does not require the Personal Electronic Device (PED) to be paired with a seat to work. The method takes an instance of SeatRatingV1.OnRatingListReceivedListener as a parameter. When the method is called successfully, the onRatingObtained callback is triggered, returning a list of ParentalRating objects. Each item in the list includes a ratingCode and a ratingValue. The rating code from this list is later needed when calling setSeatRating to apply a specific rating to a seat.
e.g.
mSeatRatingV1.getParentalRatingList(new SeatRatingV1.OnRatingListReceivedListener() {
@Override
public void onRatingObtained(List<ParentalRating> list) {
if (list != null) {
// Rating list obtained successfully
}
}
@Override
public void onSeatRatingError(SeatRatingV1.Error error) {
// Any error occcured during the API call
}
});
In the example above, the getParentalRatingList API is called. This method accepts only a SeatRatingV1.OnRatingListReceivedListener object as its parameter. Upon a successful response, it returns the list of available parental ratings through the provided listener.
3. How to retrieve the Pre-Set Rating?#
Suppose a rating was already applied to a seat before the Personal Electronic Device (PED) was paired with it. In that case, the setSeatRatingEventListener method will not capture this information, as it only listens for changes after the listener is registered. In such cases, to retrieve the existing rating after the PED has been successfully paired, you can use the getPairingStatusInfo() method provided by the SeatPairingV1 class. This method allows you to access the current pairing status along with the rating information already set on the seat.
This getPairingStatusInfo() is called in various scenarios, such as when there is a change in the seat pairing status or when the pairing process is completed. It can be triggered through both the pairing status change listener and the pairing completion listener, ensuring that updated information is made available whenever the pairing state of the Personal Electronic Device (PED) changes
mSeatPairingV1.setSeatPairingStatusChangedListener(() -> {
if (mSeatPairingV1.getPairingStatusInfo().getmPairStatus() == SeatPairingV1.PairStatus.PAIRED) {
SeatPairingV1.PairingStatusInfo pairStatus = mSeatPairingV1.getPairingStatusInfo();
// Here applied seat rating is obtained
String seatRating = pairStatus.getSeatRating();
} else {
// PED is not paired with Seat
}
});
In the example above, the first step is to check if the PED is paired with the seat. If the pairing is successful, the code gets a PairingStatusInfo object that includes the seat's rating. The PED should then display metadata based on that rating. For example, if the seat has a PG-13 rating, the PED should show PG-13 content.
4. When & how to refresh the media content in the Companion App?#
Whenever the content rating is updated on the seatback system—whether the change is initiated by the crew through their terminal or by the passenger using their electronic device—the media content displayed on the passenger's device must be reloaded to reflect the new rating that has been applied.
In the Metadata module of the Companion app SDK, all media content is represented using the MediaItem class. This class includes important details about each media item, such as the title, description, available soundtracks, subtitles, and more. It also includes the rating ID and rating description. App developers should use the rating field in the MediaItem class to filter and display media content appropriately based on the rating that is applied to the seat. Whenever the content rating is changed, regardless of the source, the media content should be refreshed only within the app. In this scenario, there is no need to make an additional call to the Metadata API.
For example, the Comparison App retrieves data based on a specific category or content type, such as movies. The fetched dataset includes a list of movies, each tagged with a particular rating like G, PG, PG-13, R, etc. The developers of the Comparison App (CA) are required to implement filtering logic that allows movies to be filtered based on their rating.
Now, suppose a seat has a content rating set to PG-13. The filtering logic must accommodate two possible conditions:
-
Strict Match: Display only the movies that are rated exactly PG-13.
-
Inclusive Match: Display all movies with a rating that is less than or equal to PG-13 in the rating hierarchy (i.e., include G, PG, and PG-13).
This filtering mechanism ensures that the content shown to users complies with their allowed rating level, either by enforcing a strict match or by allowing more flexible inclusion of less restrictive content.
5. Set Seat rating#
This method assigns a parental rating to a specific seat from a Personal Electronic Device (PED). For the rating to be successfully applied, the PED must first be paired with the corresponding seat. The list of available parental ratings that can be applied to a seat is retrieved using the getParentalRatingList API. To apply a selected rating, the setSeatRating method is used, which takes two parameters: the desired rating code and a ratingSetListener object. Upon a successful call, the onRatingSet callback method of the listener is invoked. If the operation fails, the onSeatRatingError method is triggered instead, providing appropriate error handling.
e.g.
mSeatRatingV1.setSeatRating("PG-13", new SeatRatingV1.OnRatingSetListener() {
@Override
public void onRatingSet() {
// Rating API called succesfully
// The SeatRatingEventListener event is triggered after the rating is successfully applied to the seat.
}
@Override
public void onSeatRatingError(SeatRatingV1.Error error) {
// Error during calling the set rating API
}
});
In the example above, the seat rating is set to PG-13. Additionally, the SeatRatingV1.OnRatingSetListener object is passed to the method, which enables the application to receive callbacks for various events related to the seat rating process.
6. Reset Seat rating#
This method is used to remove any previously applied parental rating from a seat. To execute this operation, the Personal Electronic Device (PED) must be paired with the corresponding seat. This method accepts a single parameter: an instance of the onRatingResetListener interface. When the API call is successful and the seat rating is reset, the onRatingReset callback method is triggered to confirm the operation. In the event of an error during the execution of the method, the onSeatRatingError callback is invoked, providing the relevant error details for proper handling.
e.g.
mSeatRatingV1.resetSeatRating(new SeatRatingV1.OnRatingResetListener() {
@Override
public void onRatingReset() {
// Rating reset API called successfully
// The SeatRatingEventListener event is triggered after the rating is successfully applied to the seat.
}
@Override
public void onSeatRatingError(SeatRatingV1.Error error) {
// Error during resetting the rating
}
});
In the example above, a rating reset operation is performed. The method accepts only a SeatRatingV1.OnRatingResetListener object as its parameter. If the reset request is successfully sent, the onRatingReset callback is invoked. Otherwise, if an error occurs, the onRatingError callback is triggered.
7. Rating change events#
Since the rating can also be set or reset from the crew terminal, it needs to be updated on the personal electronic device (PED) as well. To handle this, the SDK provides a listener that detects when a rating is changed or reset so the PED can stay in sync.
The SetRatingV1 class offers a method named setSeatRatingEventListener, which accepts an instance of SeatRatingV1.SeatRatingEventListener as its parameter. This listener is responsible for handling events related to seat rating changes and resets. Specifically, the onSeatRatingChanged callback is triggered when a seat's rating is updated, and it provides key details such as the seat number, the new rating code, and the corresponding rating number. In contrast, the onSeatRatingReset callback is invoked when a seat rating is cleared or reset; it does not carry any additional data but serves as a notification to the Personal Electronic Device (PED) that a reset has occurred.
e.g.
mSeatRatingV1.setSeatRatingEventListener(new SeatRatingV1.SeatRatingEventListener() {
@Override
public void onSeatRatingChanged(String seatNumber, String rating, int ratingNumber) {
// Refresh the media based on rating
}
@Override
public void onSeatRatingReset() {
// Refresh the media with no parental rating
}
});
In the example above, the system subscribes to seat rating events by registering a listener. This listener includes two callback methods that are triggered when relevant events are received from the server. Once an event is received, the PED (Passenger Entertainment Device) is responsible for updating the media content in the companion app accordingly. The media should be adjusted based on the rating that has been applied to the seat, ensuring that the content displayed aligns with the current parental rating settings. For more information, please refer to Section 4 of this document, which provides additional details on the topic.
Version 1.0