Displaying a PhoneGap App Correctly on the iPhone X
[UPDATE Feb 2019] More than one year later, this article remains popular. For good reason — Apple has doubled down on “the notch”, appearing on all of its newest devices. This and other mobile OS (Android/iOS) updates bring new challenges to PhoneGap developers. Keeping up with the mobile ecosystem can be incredibly frustrating!
Therefore, I highly recommend pairing your PhoneGap app with a UI framework that automatically handles changes like the iPhone notch for you, such as the Ionic Framework. With its Platform Continuity feature, each UI component adapts to the platform it's running on, allowing you to focus on your app’s core features instead of frustrating hardware/platform concerns.
(Disclaimer: I joined Ionic in June 2018.)
On the heels of the original iPhone’s 10th anniversary this Fall, Apple released its latest flagship device, the iPhone X. Included in the many changes is a display that covers the entire surface area of the device, no home button, and “the notch”, a rounded black bar that houses the front-facing camera.
As PhoneGap developers, we love the fact that our apps run without any platform-specific code on iOS, Android, and more. However, with the iPhone X, we must make an exception. I know what you’re thinking: “This is just a one-off device! Why go through the effort to support it?” While we don’t know for sure, it’s a safe bet that this will be the standard iPhone design going forward. Apple has a history of making bold design choices and sticking with them, so by updating your apps now, you’ll be better positioned for future iterations.
There are four steps to updating your PhoneGap apps for the iPhone X. I’ll be using my iOS app Fitwatchr as an example. Here’s the before and after transformation:
Add a New Viewport Meta Tag Value
Before applying any changes, your app will look similar to the following: the notch is ignored and white bars are displayed at the top and bottom of the app:
To fix this, add viewport-fit=cover to the viewport meta tag in your index.html file:
<meta name=”viewport” content=”initial-scale=1, width=device-width, height=device-height, viewport-fit=cover”>
With that change applied, the white bars are removed and the app displays much like other iPhone models.
Switch to the New Storyboard Splash Screens
In order to fill the entirety of the iPhone X’s gorgeous display, we need to remove the black bars that appear at the top and bottom of the screen by switching to iOS Launch Storyboards. These are a replacement for the legacy launch splash screen images, which Apple are moving away from. Note that the official Splashscreen plugin is not required for these changes, despite the most documentation regarding these changes appearing there. For more information, see Kerri’s excellent article.
Remove the old splash screen image files and update your config.xml file to use the following. Note that unlike legacy splash images, these image filenames must match exactly! (Also note that Medium’s unfortunate formatting may cause the dimension comments to not copy/paste correctly).
You can specify either all images:
<platform name=”ios”>
<! — 1334x1334 →
<splash src=”www/splash/ios/Default@2x~iphone~anyany.png” />
<! — 750x1334 →
<splash src=”www/splash/ios/Default@2x~iphone~comany.png” />
<! — 1334x750 →
<splash src=”www/splash/ios/Default@2x~iphone~comcom.png” />
<! — 2208x2208 →
<splash src=”www/splash/ios/Default@3x~iphone~anyany.png” />
<! — 2208x1242 →
<splash src=”www/splash/ios/Default@3x~iphone~anycom.png” />
<! — 1242x2208 →
<splash src=”www/splash/ios/Default@3x~iphone~comany.png” />
<! — 2732x2732 →
<splash src=”www/splash/ios/Default@2x~ipad~anyany.png” />
<! — 1278x2732 →
<splash src=”www/splash/ios/Default@2x~ipad~comany.png” />
</platform>
Or just a single image that will be used for all dimensions:
<! — 2732x2732 →
<splash src=”www/splash/ios/Default@2x~universal~anyany.png” />
With this change applied, the entire screen display is now used.
Adjust the Status Bar
As you can see above, the notch is hiding a portion of the status bar. Fortunately, we can tell the iPhone to dynamically adjust the screen to avoid it using the new env() CSS function. Four iOS 11 Webkit variables (safe-area-inset-left, -right, -top, -bottom) define the “safe area” perimeters. Other browsers (such as Chromium on Android) will ignore these declarations. In this case, apply padding to the HTML body using “safe-area-inset-top”:
body {
padding-top: constant(safe-area-inset-top); /* iOS 11.0 */
padding-top: env(safe-area-inset-top); /* iOS 11.2 */
}
With this change applied, the header/status bar is given room to display.
Adjust the Footer
The final change may be optional for you. In my app, I display a row of buttons in the footer. As shown above, we need to push it up a bit in order to properly access them. Apply the “safe-area-inset-bottom” variable to your CSS footer class:
.yourFooterClass {
margin-bottom: constant(safe-area-inset-bottom); /* iOS 11.0 */
margin-bottom: env(safe-area-inset-bottom); /* iOS 11.2 */
}
And voilà! Ready for the iPhone X in four easy steps.
If you’d like to learn more about creating mobile apps using PhoneGap, please check out my in-depth Pluralsight course, PhoneGap Build Fundamentals.
If you’d like to make PhoneGap development a lot easier, I recommend Steve Michelotti’s course on Building Mobile Apps with Ionic, Angular, and TypeScript.
References
Stack Overflow: Cordova app not displaying correctly on iPhone X
Kerri Shotts: PhoneGap Build 7.0.1 supports iOS Launch Storyboards
Webkit blog: Designing Websites for iPhone X
