User API Implementation#
This document provides a comprehensive guide to the User V2 API, which is designed to retrieve a variety of passenger-specific information such as preferences, personal details, and membership data. The information is categorized into distinct groups, and the document explains how to initialize each group and access the corresponding data. It also outlines the process for synchronizing data when updates are received from the head-end.
1. Preferences#
The Preference group is used to store a wide range of passenger-specific preferences. This includes food-related preferences, such as food allergies, meal choices, and drink selections. In addition, the group captures various entertainment preferences, including preferred subtitle and soundtrack languages, interactive theme settings, and favorite genres for content such as TV series, movies, and music albums.
The group also accommodates measurement unit preferences, allowing users to specify their preferred units for distance, time format (e.g., 12-hour or 24-hour), and temperature scale (e.g., Celsius or Fahrenheit).
Furthermore, the Preference group supports wellness-related parameters, enabling the storage of personal data such as chronotype (e.g., early bird or night owl), sleep patterns, and caffeine consumption habits.
Each field within the Preference group is defined with its own specific data type to ensure accurate representation and validation of the stored information.
1.1. Initialization of Preferences#
Preferences passengerPreferences;
Preferences.initService(getApplicationContext(), new IInFlightCallback() {
@Override
public void onInitServiceComplete(Object o, String s) {
// Preferences object obtained after successful initailization of Preferences services
passengerPreferences = (Preferences)o;
}
@Override
public void onInitServiceFailed(String s, InFlight.Error error) {
// This method get invoked if any error occured during initialization Preferences services
}
}, new InFlight());
1.2. How to manage the preferences#
1.2.1 Interactive theme#
This preference item is used to store the interactive theme. The get/Set methods are available to set the interactive theme.
1.2.1.1 Set Interactive Theme#
The method used to set interactive theme preferences. The method accepts a String type as a parameter.
e.g.
In the above example, the theme is set as dark. Whenever the theme gets changed need to update this preference item.
1.2.1.2 Get Interactive theme#
This method retrieves the interactive theme preference and returns a String value. The PreferenceItem object provides the method for accessing the interactive theme. To obtain a PreferenceItem, you must first call the getPreferences() method on the Preference object.
e.g.
In the above example, the interactive theme is obtained using the PreferenceItem object.
1.2.2 Interactive language#
This preference item is used to store the interactive language. The interactive language is stored in the ISO 639-2 code.
1.2.2.1 Set interactive language#
The method is used to set the interactive language, the method accepts a string value.
e.g.
1.2.2.2 Get an interactive language#
The method is used to get interactive language, the method ISO 639-2 code if any language set in the previous flight.
e.g.
In the above example, the interactive language is obtained using the getPreference method of the Preference class.
1.2.3 Soundtrack language#
The preference item is used to store passengers' selected soundtrack that is applicable for movies, TV series, and so on. If no value is found soundtrack, then the media gets played in the default soundtrack.
1.2.3.1 Set soundtrack#
The method is used to set the soundtrack, the method accepts the ISO 639 2 language code in the parameter.
e.g.
In the above example, the soundtrack's value is set to Japanese, and “jpn” is passed in the parameter.
1.2.3.2 Get soundtrack#
The method is used to get the soundtrack from the preferences; it provides the ISO 639 2 language code in the response.
e.g.
In the example above, the method retrieves the soundtrack language in ISO 639-2 format using the PreferenceItem object. This language code can be used to set the default soundtrack when a movie or TV series is launched in the interactive.
1.2.4 Genre#
This option is used to store genres in preferences, allowing them to be saved based on different content types. This can be used to recommend content based on saved user preferences.
1.2.4.1. Set genre#
This method is used to store genres in preferences. It accepts a map where the key is the content type as a string, and the value is a list of strings representing different genres.
e.g.
Map<String,List<String>> genreMap = new HashMap<>();
List<String> movieGenreList = new ArrayList<>();
movieGenreList.add("action");
movieGenreList.add("drama");
genreMap.put("media.video.movie",movieGenreList);
preferences.setGenres(genreMap);
In the above example, the list of movie genres is stored in the preferences.
1.2.4.2 Get genre#
This method retrieves the stored genre preferences associated with a specific content type. It returns the list of genres that were previously saved for the given content type in the preferences.
e.g.
In the example above, a map containing genre information is retrieved. In this map, each key represents a content type (such as movies, TV shows, etc.), and the corresponding value is a list of genres associated with that content type. This mapping can be used to recommend media based on the user's preferred content type and genres.
1.2.5 Generic method#
The Preference class includes a generic method that allows setting and retrieving all preference data in a unified way. This method supports all key-value pairs as specified in the ICD (Interface Control Document) provided to the airline. It is designed to handle various data formats and keys defined in the ICD, ensuring consistency and flexibility. Additionally, it can be used to access or update the same preference values managed by the specific methods mentioned earlier.
1.2.5.1 Set data#
The generic method accepts a key-value pair, where the key is a String and the value is an Object. For details on the supported keys and value formats, please refer to the SDK documentation or the ICD document provided to the airline partner. In the value, it accepts different kinds of values such as boolean, String, Integer, JSON array, etc.
e.g.
JSONArray drinkPreference = new JSONArray();
drinkPreference.put("rum");
drinkPreference.put("vodka");
preferences.setField("drink_preferences",drinkPreference);
In the example above, the key used is drink_preferences, which is defined in the ICD (Interface Control Document). The corresponding value for this key is a JSON array. In this particular example, two items have been added to the drink_preferences array, representing the selected drink options.
1.2.5.2 Get data#
The generic method is available in the PreferenceItem class, which is used to get any of the preference values that are defined in the ICD document. The method accepts the String value as a key and returns the Object type that needs to be typecast to the defined type.
e.g.
In the above example, the key is drink_preferences, and it returns the JSONArray. Here, typecasting is required.
For more information about the different keys and their corresponding value formats, please refer to the Interface Control Document (ICD). It provides detailed descriptions and guidelines on how each key should be used and the expected format of its values.
2. Info#
The Info service is used to retrieve a wide range of data, including passenger details, frequent flyer information, upcoming sector flight details, demographic data, and more. It serves as a central access point for collecting key information relevant to the passenger and their travel itinerary.
2.1 Initialization of Info service#
Info info;
Info.initService(getApplicationContext(), new IInFlightCallback() {
@Override
public void onInitServiceComplete(Object o, String s) {
// The method invoked after successful initialization of Info service
info = (Info) o;
}
@Override
public void onInitServiceFailed(String s, InFlight.Error error) {
// The method invoked when any error occured during initialization
}
}, new InFlight());
2.2 How to use the Info service?#
The Info service offers a variety of methods that allow both setting and retrieving data. These methods enable interaction with different types of information, such as passenger details, travel history, and other relevant data, ensuring smooth data management and accessibility within the system.
2.2.1. Set group#
The method used to store new groups under Info. There are various groups pre-defined under Info, service, and those are
-
DEMOGRAPHIC
-
FLIGHT_INFO
-
FREQUENT_FLYER_INFO
-
PASSENGER_INFO
-
PERSONALLY_IDENTIFIABLE_INFO
-
TRAVEL_INFO
Each group contains different keys and value pairs, Please refer to the ICD document for more details.
The method takes two parameters: a String representing the key and a JSONObject representing the value. e.g.
try {
JSONObject passengerInfo = new JSONObject();
passengerInfo.put("first_name", "JON");
passengerInfo.put("middle_name", "TARGARYEN");
passengerInfo.put("last_name", "SNOW");
passengerInfo.put("title", "LORD COMMANDER");
passengerInfo.put("email_address", "6f3dcdd82e4a36f60278955977bdd499d55029e13add3d270479fc063a59e396");
info.setGroup(Info.PERSONALLY_IDENTIFIABLE_INFO,passengerInfo);
} catch (JSONException e) {
throw new RuntimeException(e);
}
In the example above, personally identifiable information is being stored using the Info service. The data is provided in the form of a JSONObject, which encapsulates the relevant information for storage
2.2.2. Get group#
This method is used to retrieve a specific group of data stored within the Info service. It accepts a String parameter representing the group name and returns the corresponding data as a JSONObject.
e.g.
In the example above, the key Info.FLIGHT_INFO is used to retrieve data, which is returned in the form of a JSONObject
2.2.3. Get all group#
This method retrieves all information groups, where each entry consists of a group name as the key and its corresponding data represented as a JSONObject.
e.g.
In the example above, the method is used to retrieve all items within the info group. If a value is not available for a specific key, the method returns null for that key.
2.3.4. Remove group#
This method removes the information group that is associated with the specified key. Once invoked, it deletes the entire data group corresponding to the given key from the Info service. The method accepts the key name as a parameter.
e.g.
In the example above, passenger-related data has been excluded from the info service.
3. Set the listener to listen to the updates#
All of the above services 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 data updates.
The Sync.SyncListener offers several callback methods to handle different synchronization events:
-
onUserDataChanged – Triggered when any service’s 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.
preferences.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()");
}
}
4. Conflict in data#
If the passenger is not logged in and either the passenger or the IFE system updates any of the above data, a conflict occurs when the passenger logs in later, and a difference is found between the PMD and the updated data.
How to resolve the conflict?#
All of the above services include the ConflcitItem class like PreferenceConflictItem includes the resolveConflict method, responsible for resolving conflicts between local and remote bookmarks.
List<? extends ConflictItem> itemList = preferences.getConflicts();
for (ConflictItem item : itemList) {
item.resolveConflict(ConflictResolution.LOCAL_CONFLICT);
}
In the example above, the list of PreferenceConflictItem objects is retrieved using the getConflicts method of the Preference class. This method provides both local and remote preferences. The PreferenceConflictItem 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.
Version 1.0