Android Application Developer Guide

Process

Application developers must submit their applications with all required files to the Panasonic build and validation system for testing before final release. Required files are detailed in the Applications Packaging section.

For additional information on the application submission process, please contact the Panasonic Technical Partner Management Team.

Media Database and Application

All applications and games are identified in the Panasonic media database. These applications can be self-contained with their own database and metadata and updated without ATP. To update the media database, please contact your Panasonic focal.

Development Environment

Panasonic recommends that Android application developers set up the environment as follows.

Kotlin

Panasonic recommends application developers develop applications using Kotlin.

Kotlin is the official programming language for Android application development. It's a statically-typed, modern programming language that emphasizes safety by providing strong type inference, expressiveness in its syntax and interoperability with Java. Kotlin allows cross-platform development and is well-supported in popular development environments like Android Studio.

Jetpack Compose

Panasonic recommends application developers migrate their Application UI development to Jetpack Compose.

Jetpack Compose has a declarative and component-based approach that simplifies UI development. It encourages UI component reusability and provides interoperability, state management integration, and preview and interactive UI testing. Compose is Kotlin-first and takes advantage of Kotlin's features and language capabilities.

MVVM Architecture

Panasonic recommends using Model-View-ViewModel (MVVM) architecture for UI development.

MVVM architecture separates the UI (View), the business logic and data (ViewModel), and the data source and manipulation (Model), which makes your codebase more organized, maintainable and easier to understand. MVVM also simplifies the UI updating process and makes the UI more responsive.

MVVM architecture promotes the testability of Android applications, reusability of business logic and data, and maintainability of your Android application.

Optimizations

Panasonic recommends the following optimizations for Android applications.

Performance

The following are recommended optimizations for improving the performance of Android applications:

Use release builds.
Because debug builds are inefficient, always make application releases in release mode. The Android runtime environment makes several optimizations in release mode to make the application run more quickly.
Use ProGuard or R8.
This is for code shrinking, obfuscation and optimization. Configure rules to keep only necessary code and remove unused code.
Use baseline profiles.
Baseline profiles in Android improve application startup performance. These optimize the loading of classes and methods based on an application's usage patterns.
Implement Dalvik Executable (DEX) file layout optimizations.
These refer to strategies for organizing and optimizing classes and methods within an application's DEX files. These optimizations improve the performance and efficiency of an application.
Avoid deeply nested layouts.
Deeply nested layouts can lead to complex view hierarchies and increased method counts. Simplify layouts to improve performance.
An application screen with multiple UI elements arranged in a way that creates a UI tree with large heights will cause the Android runtime to spend a substantial amount of time inflating the views. Flatten the views so that they can be drawn in less time.
Avoid application launch at bootup.
Launching applications along with the interactive at bootup causes significant impact to memory usage and memory stress on the overall system. Avoid this to minimize memory usage and system stress.
If your application must be launched at bootup, please contact Panasonic for further guidance.

OpenGl

Android applications using JavaOpenGL (JOGL) APIs may suffer from performance degradation due to Java overhead and cross platform-based solution. For the best application performance, Panasonic recommends using native OpenGL through Java Native Interface (JNI) in Android applications that are using the JOGL API.

Using native OpenGL through JNI allows you to:

Directly interact with OpenGL, which minimizes the overhead from Java. This leads to a better performance in graphics-intensive applications where performance is a critical concern.
Have full control over OpenGL calls and optimize for specific hardware and performance requirements.

Launch Time

The following are recommended optimizations for speeding up launch time of Android applications:

Offload work to background threads.
Perform time-consuming tasks on background threads to avoid blocking the main UI thread.
Utilize lazy initialization.
Delay initialization of components that are not immediately needed to improve startup time.
Use a splash screen.
Implement a splash screen with minimal UI and branding to give the impression of a faster startup.
Avoid heavy computations.
Refrain from performing computationally intensive operations in onCreate(). If heavy operations are necessary, schedule them on background threads.
Reduce object creation.
Minimize object instantiation within onCreate(). Consider using object pooling or reusing objects to reduce memory allocation overhead.
Optimize layout inflation.
Use techniques like View Recycling and ConstraintLayout to optimize layout inflation, especially for complex layouts.
Reduce dependencies.
Minimize initialization of external dependencies in onCreate() and, if possible, load them lazily or asynchronously.
Implement Data Binding or View Binding.
Implement Data Binding or View Binding to simplify interactions with UI elements. Improve performance by reducing findViewById() calls.
Utilize caching and preloading.
Cache frequently used data and preload data that will be displayed immediately on startup.
Optimize image loading.
Use image loading libraries, such as Glide or Picasso, for efficient image loading, caching and resizing.
Remove unnecessary code.
Regularly review and remove unnecessary code from onCreate() to keep your code clean and efficient.
Implement modularization.
Split your application into modules to load only necessary components during startup. This reduces initial application size and improves startup time.
Optimize resource loading.
Efficiently load resources like fonts, drawables and layouts. Use resource qualifiers and formats to minimize loading overhead.

After implementing optimizations, test and profile your application by doing the following:

Test and benchmark.
Test and benchmark startup times on different devices and Android versions to identify areas for improvement.
Profile and optimize.
Continuously profile and monitor application performance to focus optimization efforts on critical areas.
Use profiling tools.
Utilize Android Profiler or third-party profiling tools to identify performance bottlenecks and optimize the onCreate() method.

Performance Metrics

The following are guidelines for assessing how well an Android application runs to create a smooth and reliable user experience.

Application Launch Time

A good application launch time indicates that an application is providing a fast and responsive experience for users.

Specific target times can vary depending on the complexity of the application and the device it runs on.

The following launch times are guidelines for assessing good application launch time:

Under 2 seconds — Optimal
This gives users the perception of a fast and responsive application.
2 to 4 seconds — Good
This can cause users to notice a slight delay, but it is unlikely for users to find this frustrating.
4 to 6 seconds — Fair
This may start to frustrate users. It may be acceptable for more complex applications, such as games or multimedia applications, but optimizing for faster loading, if possible, is recommended.
Over 6 seconds — Poor
This may lead to user frustration and result in users abandoning an application.

Responsiveness

Good application responsiveness is crucial for providing a smooth and enjoyable user experience. Responsiveness refers to how quickly an application responds to user input and interactions, such as taps, swipes and button presses.

The following response times are guidelines for assessing good application responsiveness:

Under 100 milliseconds — Optimal
This can result in a near-instantaneous response and will give users the feeling of an application being highly responsive and directly connected to their actions.
Under 200 milliseconds — Good
This should be the target for most user interactions. Users will perceive an application as responsive and smooth.
Under 500 milliseconds — Acceptable
This is considered acceptable for most interactions, but users may notice a slight delay.
Over 500 milliseconds — Poor
This can lead to a perceived lack of responsiveness and can frustrate users.

Memory Usage

Good application memory usage depends on how efficiently an application utilizes the device's RAM.

Efficient memory management is essential for ensuring an application runs smoothly, does not crash due to memory-related issues, and does not consume an excessive amount of memory. An application consuming too much memory can impact and slow device performance or even result in application termination.

The following memory usages are guidelines for assessing good application memory usage:

Low memory footprint — Optimal
This is when an application is using as little RAM as possible to accomplish tasks. Aim to keep an application's memory usage to a minimum to provide a rich user experience.
Under 100 MB — Good
For most applications, this is a good target. Please note that memory requirements can vary depending on an application's complexity and functionality.
100 to 200 MB — Acceptable
For applications with more complexity, such as games and multimedia applications, memory usage in this range may be acceptable, but optimize memory usage wherever possible.
Over 200 MB — Poor
This can lead to performance issues, including application crashes and reduced device responsiveness, and can result in a poor user experience.

CPU Usage

Good application CPU usage depends on various factors, such as the complexity of an application, the device's hardware capabilities and the application's intended functionality.

CPU usage is a critical performance metric. Aim to balance between providing the intended functionality and avoiding overloading the device's CPU. If CPU usage is high, it can lead to a poor user experience and excessive power consumption.

The following CPU usages are guidelines for assessing good application CPU usage:

Under 10% — Optimal
An optimal application keeps CPU usage under 10% when an application is idle or during light application usage. This ensures that the device remains responsive and conserves power.
Under 30% — Good
For most applications, keeping CPU usage under 30% during active use is considered good. This gives users a smooth user experience while keeping an application resource efficient.
30% to 50% — Acceptable
It is recommended that applications optimize CPU usage wherever possible. However, CPU usage between 30% to 50% is acceptable for applications with more intensive computational or graphic tasks, such as games or multimedia applications.
Over 50% — Poor
Consistently high CPU usage of over 50% is generally considered poor performance. This can lead to the device feeling sluggish, overheating and consuming excessive power, which can result in a poor user experience.

Crash Rate

A good application crash rate is typically as close to zero as possible. An application with few or no crashes has minimal impact on the user experience.

However, achieving a completely crash-free application can be challenging due to the diversity of devices, operating system versions and user interactions.

The following crash rates are guidelines for assessing a good application crash rate:

Zero crashes — Optimal
This indicates that users can use an application without encountering any errors or unexpected application closures.
Less than 1% — Good
This indicates that on average, for every 100 application sessions, an application experiences one or fewer crashes.
1 to 2% — Acceptable
This is generally acceptable, especially for more complex applications such as games or multimedia applications, but it is recommended to aim for continuous improvement and reduce crash rates when possible.
Over 2% — Poor
An application having a crash rate of over 2% of the time is generally considered poor and can lead to user frustration.

Render Time

Application render time refers to the time it takes to render frames of an application's UI. The render time directly impacts the user's perceived smoothness and responsiveness of an application.

A lower render time indicates that the UI is updating quickly and efficiently and results in a smoother user experience. The specific target render time can vary depending on an application's complexity and the device's capabilities.

The following render times are guidelines for assessing good application render time:

Under 16 milliseconds — Optimal
This corresponds to 60 frames per second (FPS). Achieving this frame rate ensures a smooth and responsive UI.
16 to 32 milliseconds — Good
This corresponds to a frame rate between 30 to 60 FPS, which results in most users not noticing any lag or stutter.
32 to 50 milliseconds — Acceptable
This corresponds to a frame rate between 20 to 30 FPS. This may result in a slightly less smooth UI experience, especially for animations or fast UI interactions.
Over 50 milliseconds — Poor
This corresponds to a frame rate below 20 FPS. This can lead to noticeable UI lag, stuttering and an overall less enjoyable user experience.

Application Not Responding (ANR) Rate

The ANR rate refers to when an application becomes unresponsive to user input for a significant amount of time. ANRs can result in a poor user experience and are typically caused by long-running operations on the main UI thread.

A good ANR rate for applications is as close to zero as possible, which indicates that an application rarely or never becomes unresponsive.

The following rates are guidelines for assessing a good ANR rate:

Zero ANRs — Optimal
This indicates that an application always remains responsive to user input and does not freeze or become unresponsive.
Rare ANRs — Good
A good application experiences ANRs infrequently. When rare ANRs occur, this is due to unpredictable circumstances. These rare ANRs should be isolated incidents rather than a common occurrence.
Under 1% — Acceptable
This indicates that, for every 100 application sessions or interactions, on average, there is one or fewer ANRs. ANRs should not significantly impact the user experience.
Over 1% — Poor
This indicates that an application's responsiveness is a concern and may negatively impact the user experience.

Platforms

Android Software

The Panasonic IFE system supports 5.1/API level 22. The NEXT IFE platform supports Android 7.1/API level 25 and Android 8.1/API level 27.

Monitor and Handset Software

For specifications on Android supported seatback monitors and handsets, refer to the Android Monitor and Handset Guide.

System Events Handling

Android applications must follow Android life cycle events and coding standards.

Applications receive notification of critical Panasonic system events, such as passenger announcements (PAs), open and close flight, and entertainment on and off through Android life cycle events.

Applications must manage passenger persisted data, such as passenger seat swap and passenger offloading.

Applications failing to comply with Android life cycle events may impact system behavior and can be blocked from launching.

For additional information on Android life cycle events and coding standards, refer to the Android Developer Guides and Android Activity Reference.

Sample Life Cycle Event

Input Validation and Sanitization

Applications that receive data should perform range checking and input validation. In addition, applications receiving data should prevent command injection, such as SQL injection in the user input.

Android System Bars Policy and Guidelines

Android Immersive Mode

In Android Immersive mode, Android system bars do not display while an application is running. It is recommended that non-native Android applications implement Android Immersive mode.

If you need to allow passengers to access certain interactive features like interactive settings while an application is running, then the interactive should use a system window to draw an overlay button on top of applications. When a passenger selects the button, the interactive should launch a transparent activity. When PAs are displayed, the interactive should hide this button.

The interactive should handle implementing this overlay button and require no additional implementation from third party applications. However, adding this feature will result in the following:

Handset D-pad focus navigation will not work for the overlay button.
The overlay button may cover important areas of some applications and prevent passengers from properly using those applications.

Application Exit

Applications must provide a way in the UI for the user to return to the interactive home screen, such as Home or Exit buttons.

Keeping the Screen On

In situations where the interactive should keep the screen on, such as when a movie is playing, set the FLAG_KEEP_SCREEN_ON flag:

mWindow.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)

However, if the screen is turned off manually, Android implicitly clears that flag. When the screen is turned back on and the interactive receives the onResume lifecycle event, the interactive can continue keeping the screen on by clearing and re-adding the flag:

mWindow.clearFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON);
mWindow.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON);

Screensaver

We recommend that you use the built-in Android screensaver for the interactive instead of implementing a custom screensaver. Screensaver logic becomes complicated when input comes from both touch and key events.

To implement custom behavior while a screensaver is displaying, use the DreamService class.

If it is necessary to implement a custom screensaver for the interactive, be sure to implement wake lock properly.

One common mistake is for the interactive to only acquire a wake lock once and expect wake lock to persist indefinitely. However, after the interactive wakes up from sleep, wake lock can be lost intermittently. To prevent this from happening, release wake lock after the onStop() event and obtain a new brightness wake lock after the onResume() event.

Application Validation

Application developers can validate their applications before submitting to Panasonic for the final release by following the guidelines below.

Validation Environment

Android Emulation Test

Test applications on any smartphone or tablet that is preloading with an Android PC emulator at the proper API level.

Panasonic Handset Compatibility Test

Test handset key events using an Android key event emulator. For handset key mapping, refer to Handset Key Mapping and Key Code Events.

IFE Aware Applications Validation

IFE aware applications are applications that either interface with the Panasonic IFE SDK, have server components, or both.

Depending on the IFE SDK usage, an application can be subject to Panasonic recommended validations. Panasonic teams will work with application developers to review change impact analysis and will recommend specific validations needed to make the changes.

These validations can be conducted at either Panasonic test racks or simulators, based on validation types. Please contact your Airline focal or the Vendor Management team for recommended validations.

Compliance Reports

Panasonic may request proof of the following compliance reports:

Content Compliance Report
This is for ensuring that content Android Expansion file (OBB) releases contain only Panasonic defined content types.
Security Vulnerability Scanning Report
This is for ensuring that applications are not vulnerable to security breaches.
Life Cycle Events Compliance Test Report
This is for ensuring that applications are following Android life cycle events standards.
Allocated Storage Size Compliance Report
This is for ensuring storage size of content is compliant.
Monitor Resolution Compliance Report
This is for ensuring that applications follow Panasonic specified monitor resolutions and aspect ratios.

Applications Packaging

Application APKs and assets are packaged according to the following Panasonic loadable creation standards.

Files Required for Each Application

To successfully install an Android application on the Panasonic IFE system, submit the following:

Android application package — APK
If the file size is less than 100MB, include both the software and content or assets.
If the file size exceeds 100MB, package the content or assets as OBB files.
Application configuration file — CFG
This is required for the Panasonic Application Packaging Process.
Android expansion files — OBB
This is required if the application has a large amount of external content.
Resource APK
Applications with less than 100MB of content or assets can package the content as a resource APK.

APK Naming Convention

Use the following naming conventions for Android application packages:

Android application package — APK
Format: vendor_appName.apk
Example: pacgames_pong.apk
Package
Format: com.vendor.type.packageName
Example: com.pacgames.games.pong
Application configuration file
Format: vendor_appName.cfg
Example: pacgames_pong.cfg

Application Configuration File Contents

Application configuration files contain the following fields:

apk — required
Represents the APK name.
launchintent — required
Represents the launch intent.
class_name — optional
For supporting packages with multiple applications.
obb — optional
This is an array to reference OBB files, if available.
pacinfobundle — optional
Android applications can use the PAC Information Bundle to gather information about the system and the device where the application is running.
For additional information, refer to the PAC Information Bundle reference.
receiver_name — optional
Required for applications that need to run in the background as a service. This represents the BroadcastReceiver that is listening for the action specified in receiver_action.
Format: packageName/receiverName
Example: aero.pac.simpletestapp3/aero.pac.simpletestapp3.MyReceiver
receiver_action — optional
Required for applications that need to run in the background as a service. This is the name of the action that the application's BroadcastReceiver is listening for.

OBB Naming Standards

The following are naming standards and scenarios for OBB files:

If an application requires an OBB file, identify where the OBB file belongs by adding the application prefix.
Example: pacgames_pong_resources.obb
For generic OBB files used by multiple applications, include the vendor name in the filename to specify the owner of the OBB file.
Example: pacgames_graphicsassets.obb
The Android OBB naming standard is also supported:
Format: main|patch.expansionVersion.packageName.obb
Example: main.12345.com.pacgames.games.pong.obb

Media Database Entry

Application information must be entered into the Media database using Panasonic Media tools. The application entry must match the application that is to be installed onto the system.

File name
Configuration file name withou the .cfg extension.
Example: pacgames_pong
launchlru
Identifies the type of hardware the application requires to launch.
Example: launchlru=Seat
For companion applications, identify all types of hardware that the application requires to launch.
Example: launchlru=Seat,VHS

File Configurations

Example file configuration with more than one OBB configuration:

{
    "apk": "pacgames_pong",
    "launchintent": "com.pacgames.games.pong",
    "obb": [
        "pacgames_pong_resources.obb",
        "pacgames_graphicassets.obb"
    ],
    "pacinfobundle": 1
}

Example file configuration with no OBB configurations:

{
    "apk": "pacgames_pong",
    "launchintent": "com.pacgames.games.pong", 
    "pacinfobundle": 1
}

Example file configuration where the application is to be installed on bootup:

{
    "apk": "pacgames_pong",
    "launchintent": "com.pacgames.games.pong",
    "receiver_action": "aero.panasonic.intent.action.test",
    "receiver_name": "aero.pac.simpletestapp3/aero.pac.simpletestapp3
        .MyReceiver",
    "obb": [
        "pacgames_pong_resources.obb",
        "pacgames_graphicassets.obb"
    ],
    "pacinfobundle": 1
}

System Resource Usage

RAM system memory in seatback monitors that support Android varies from 2 GB to 4 GB. For 1 GB RAM seatback monitors, maximum runtime memory usage in applications must not exceed 512 MB. For 2GB RAM seatback monitors, maximum runtime memory usage must not exceed 1 GB.

Memory usage must not exceed 25% of the allocated RAM for ten consecutive seconds. Exceeding this limit may impact the application and core system software performance, which can cause the Android memory manager or the Panasonic resource monitor to kill the application.

Examples of performance impact:

Images may render slowly, or the application may respond slowly to user input.
The system may be adversely impacted during video passenger announcements (VPAs). Video rendering will be jittery and cause degrading system behavior.

CPU utilization must not exceed 90% of the allocated RAM for more than ten consecutive seconds.

Disk utilization must be within the allocated disk space for each application in the seat monitor and the headend server. For default allocations, please contact your Panasonic focal.

Applications that require storing runtime data can use external storage. Application specific external cache can be accessed using the getExternalCacheDir() method. For implementation details, refer to the Data and File Storage Overview guide.

If an application crashes multiple times during flight, the application can be disabled from launching.

Developers must follow the Android application memory management guidelines. For additional information, refer to the Manage Your App's Memory guide.

Android Expansion Files (OBB)

Android Expansion files (OBB) are required if an Android application package size exceeds 100 MB. The default OBB file size is 2 GB.

An APK should package extra content in a main file and a patch OBB file. If more expansion files are needed, vendors can request support for additional OBB files.

Main OBB files are recommended for applications that do not update assets frequently.
Patch OBB files are recommended for applications with frequent updates.

For expansion file handling in applications, refer to the APK Expansion Files guide.

Handset Key Mapping and Key Code Events

Android key code events correspond one-to-one with the individual keys on the Panasonic handsets. The following Android key codes are default configurations for Panasonic handsets. Remapping key code events requires ATP.

For additional information on Android key code events, refer to Android key code events.

VHS V1 Handset

Button	Android Key Code
	`KEYCODE_DPAD_UP`
	`KEYCODE_DPAD_RIGHT`
	`KEYCODE_DPAD_DOWN`
	`KEYCODE_DPAD_LEFT`
	`KEYCODE_BUTTON_X`
	`KEYCODE_BUTTON_Y`
	`KEYCODE_BUTTON_A`
	`KEYCODE_BUTTON_B`
	`KEYCODE_BUTTON_L1`
	`KEYCODE_BUTTON_R1`

VHS V2 Handset

Button	Android Key Code
	`KEYCODE_DPAD_UP`
	`KEYCODE_DPAD_RIGHT`
	`KEYCODE_DPAD_DOWN`
	`KEYCODE_DPAD_LEFT`
	`KEYCODE_BUTTON_X`
	`KEYCODE_BUTTON_Y`
	`KEYCODE_BUTTON_A`
	`KEYCODE_BUTTON_B`
	`KEYCODE_ENTER`
	`KEYCODE_NOTIFICATION`
	`KEYCODE_BUTTON_L1`
	`KEYCODE_BUTTON_R1`

Standard Touchpad Handset

Front

Button	Android Key Code
	`KEYCODE_DPAD_UP`
	`KEYCODE_DPAD_RIGHT`
	`KEYCODE_DPAD_DOWN`
	`KEYCODE_DPAD_LEFT`
	`KEYCODE_BUTTON_X`
	`KEYCODE_BUTTON_Y`
	`KEYCODE_BUTTON_A`
	`KEYCODE_BUTTON_B`
	`KEYCODE_BACK`
	`KEYCODE_ENTER`
	`KEYCODE_NOTIFICATION`
	`KEYCODE_BUTTON_L1`
	`KEYCODE_BUTTON_R1`

Back

Button	Android Key Code
	`KEYCODE_A`, `KEYCODE_B`, ... `KEYCODE_Z`
	`KEYCODE_0`, `KEYCODE_1`, ... `KEYCODE_9`
	`KEYCODE_ENTER`
	`KEYCODE_DEL`
	`KEYCODE_SPACE`
	`KEYCODE_SHIFT_LEFT`
	`KEYCODE_SHIFT_LEFT`
	`KEYCODE_UNKNOWN`
	`KEYCODE_DPAD_UP`
	`KEYCODE_DPAD_RIGHT`
	`KEYCODE_DPAD_DOWN`
	`KEYCODE_DPAD_LEFT`