make a PWA for iOS?
A progressive internet software is only a particular sort of web site, that may look and behave like a local iOS app. With a view to construct a PWA, first we’ll create an everyday web site utilizing SwiftHtml. We will begin with an everyday executable Swift bundle with the next dependencies.
import PackageDescription
let bundle = Package deal(
title: "Instance",
platforms: [
.macOS(.v12)
],
dependencies: [
.package(url: "https://github.com/binarybirds/swift-html", from: "1.2.0"),
.package(url: "https://github.com/vapor/vapor", from: "4.54.0"),
],
targets: [
.executableTarget(name: "Example", dependencies: [
.product(name: "SwiftHtml", package: "swift-html"),
.product(name: "Vapor", package: "vapor"),
]),
.testTarget(title: "ExampleTests", dependencies: ["Example"]),
]
)As you’ll be able to see we’ll use the vapor Vapor library to serve our HTML website. If you do not know a lot about Vapor let’s simply say that it’s a internet software framework, which can be utilized to construct server aspect Swift purposes, it is a fairly superb device I’ve a newbie’s information put up about it.
After all we’ll want some parts for rendering views utilizing SwiftHtml, you should use the supply snippets from my earlier article, however right here it’s once more how the SwiftHtml-based template engine ought to appear to be. It is best to learn my different article if you wish to know extra about it. 🤓
import Vapor
import SwiftSgml
public protocol TemplateRepresentable {
@TagBuilder
func render(_ req: Request) -> Tag
}
public struct TemplateRenderer {
var req: Request
init(_ req: Request) {
self.req = req
}
public func renderHtml(_ template: TemplateRepresentable, minify: Bool = false, indent: Int = 4) -> Response {
let doc = Doc(.html) { template.render(req) }
let physique = DocumentRenderer(minify: minify, indent: indent).render(doc)
return Response(standing: .okay, headers: ["content-type": "text/html"], physique: .init(string: physique))
}
}
public extension Request {
var templates: TemplateRenderer { .init(self) }
}We’re additionally going to wish an index template for our major HTML doc. Since we’re utilizing a Swift DSL to write down HTML code we do not have to fret an excessive amount of about mistyping a tag, the compiler will shield us and helps to take care of a totally legitimate HTML construction.
import Vapor
import SwiftHtml
struct IndexContext {
let title: String
let message: String
}
struct IndexTemplate: TemplateRepresentable {
let context: IndexContext
init(_ context: IndexContext) {
self.context = context
}
func render(_ req: Request) -> Tag {
Html {
Head {
Title(context.title)
Meta().charset("utf-8")
Meta().title(.viewport).content material("width=device-width, initial-scale=1")
}
Physique {
Foremost {
Div {
H1(context.title)
P(context.message)
}
}
}
}
}
}Lastly we will merely render the bootstrap our Vapor server occasion, register our route handler and render the index template inside the primary entry level of our Swift bundle by utilizing the beforehand outlined template helper strategies on the Request object.
import Vapor
import SwiftHtml
var env = strive Setting.detect()
strive LoggingSystem.bootstrap(from: &env)
let app = Software(env)
defer { app.shutdown() }
app.get { req -> Response in
let template = IndexTemplate(.init(title: "Hi there, World!",
message: "This web page was generated by the SwiftHtml library."))
return req.templates.renderHtml(template)
}
strive app.run()It’s simply that straightforward to setup and bootstrap a totally working internet server that’s able to rendering a HTML doc utilizing the ability of Swift and the Vapor framework. In case you run the app it’s best to be capable to see a working web site by visiting the http://localhost:8080/ deal with.
Turning an internet site into an actual iOS PWA
Now if we wish to remodel our web site right into a standalone PWA, we now have to offer a hyperlink a particular internet app manifest file inside the pinnacle part of the index template.
Meta tags vs manifest.json
Looks like Apple follows sort of a wierd route if it involves PWA assist. They’ve fairly a historical past of “considering exterior of the field”, this mindset applies to progressive internet apps on iOS, since they do not are inclined to comply with the requirements in any respect. For Android units you may create a manifest.json file with some predefined keys and you would be simply positive along with your PWA. Alternatively Apple these days prefers varied HTML meta tags as a substitute of the net manifest format.
Personally I do not like this strategy, as a result of your HTML code can be bloated with all of the PWA associated stuff (as you will see that is going to occur if it involves launch display screen pictures) and I imagine it is higher to separate these sort of issues, however hey it is Apple, they can not be incorrect, proper? 😅
Anyhow, let me present you learn how to assist varied PWA options on iOS.
Enabling standalone app mode
The very first few keys that we might like so as to add to the index template has the apple-mobile-web-app-capable title and it’s best to use the “sure” string as content material. It will point out that the app ought to run in full-screen mode, in any other case it is going to be displayed utilizing Safari similar to an everyday website.
struct IndexTemplate: TemplateRepresentable {
let context: IndexContext
init(_ context: IndexContext) {
self.context = context
}
func render(_ req: Request) -> Tag {
Html {
Head {
Title(context.title)
Meta().charset("utf-8")
Meta().title(.viewport).content material("width=device-width, initial-scale=1")
Meta()
.title(.appleMobileWebAppCapable)
.content material("sure")
}
Physique {
Foremost {
Div {
H1(context.title)
P(context.message)
}
}
}
}
}
}We must always change the hostname of the server and hear on the 0.0.0.0 deal with, this manner in case your telephone is on the identical native WiFi community it’s best to be capable to attain your internet server straight.
import Vapor
import SwiftHtml
var env = strive Setting.detect()
strive LoggingSystem.bootstrap(from: &env)
let app = Software(env)
defer { app.shutdown() }
app.http.server.configuration.hostname = "0.0.0.0"
if let hostname = Setting.get("SERVER_HOSTNAME") {
app.http.server.configuration.hostname = hostname
}
app.get { req -> Response in
let template = IndexTemplate(.init(title: "Hi there, World!",
message: "This web page was generated by the SwiftHtml library."))
return req.templates.renderHtml(template)
}
strive app.run()You could find out your native IP deal with by typing the next command into the Terminal app.
# utilizing ifconfig & grep
ifconfig | grep -Eo 'inet (addr:)?([0-9]*.){3}[0-9]*' | grep -Eo '([0-9]*.){3}[0-9]*' | grep -v '127.0.0.1'
# utilizing ifconfig & sed
ifconfig | sed -En 's/127.0.0.1//;s/.*inet (addr:)?(([0-9]*.){3}[0-9]*).*/2/p'
Simply use that IP deal with and go to the http://[ip-address]:8080/ web site utilizing your iOS system, then it’s best to be capable to add your web site to your private home display screen as a bookmark. Simply faucet the Share icon utilizing Safari and choose the Add to Residence Display menu merchandise from the checklist. On the brand new display screen faucet the Add button on the highest proper nook, it will create a brand new icon on your private home display screen as a bookmark to your web page. Optionally, you’ll be able to present a customized title for the bookmark. ☺️
Since we have added the meta tag, should you contact the newly created icon it ought to open the webpage as a standalone app (with out utilizing the browser). After all the app continues to be only a web site rendered utilizing an internet view. The standing bar will not match the white background and it has no customized icon or splash display screen but, however we’ll repair these points proper now. 📱
Customized title and icon
To offer a customized title we simply have so as to add a brand new meta tag, luckily the SwiftHtml library has predefined enums for all of the Apple associated meta names, so you do not have to sort that a lot. The icon scenario is a little more troublesome, since we now have so as to add a bunch of dimension variants.
struct IndexTemplate: TemplateRepresentable {
let context: IndexContext
init(_ context: IndexContext) {
self.context = context
}
func render(_ req: Request) -> Tag {
Html {
Head {
Title(context.title)
Meta().charset("utf-8")
Meta().title(.viewport).content material("width=device-width, initial-scale=1")
Meta()
.title(.appleMobileWebAppCapable)
.content material("sure")
Meta()
.title(.appleMobileWebAppTitle)
.content material("Hi there PWA")
Hyperlink(rel: .appleTouchIcon)
.href("/img/apple/icons/192.png")
for dimension in [57, 72, 76, 114, 120, 144, 152, 180] {
Hyperlink(rel: .appleTouchIcon)
.sizes("(dimension)x(dimension)")
.href("/img/apple/icons/(dimension).png")
}
}
Physique {
Foremost {
Div {
H1(context.title)
P(context.message)
}
}
}
}
}
}As you’ll be able to see icons are referenced by utilizing the Hyperlink tag, utilizing the Apple contact icon rel attribute. The default icon with out the sizes attribute could be a 192×192 pixel picture, plus I am offering some smaller sizes by utilizing a for loop right here. We additionally have to serve these icon information by utilizing Vapor, that is why we’ll alter the configuration file and allow the FileFiddleware.
import Vapor
import SwiftHtml
var env = strive Setting.detect()
strive LoggingSystem.bootstrap(from: &env)
let app = Software(env)
defer { app.shutdown() }
app.middleware.use(FileMiddleware(publicDirectory: app.listing.publicDirectory))
app.http.server.configuration.hostname = "0.0.0.0"
if let hostname = Setting.get("SERVER_HOSTNAME") {
app.http.server.configuration.hostname = hostname
}
app.get { req -> Response in
let template = IndexTemplate(.init(title: "Hi there, World!",
message: "This web page was generated by the SwiftHtml library."))
return req.templates.renderHtml(template)
}
strive app.run()By including the FileMiddleware to the app with the general public listing path configuration your server app is ready to serve static information from the Public listing. Be at liberty to create it and place the app icons below the Public/img/apple/icons folder. If you’re operating the server from the command line you will be positive, however if you’re utilizing Xcode you must specify a customized working listing for Vapor, it will permit the system to lookup the general public information from the suitable place.
Your customized icons will not present up if you’re utilizing a self-signed certificates.
Construct and run the server and attempt to bookmark your web page once more utilizing your telephone. Once you see the add bookmark web page it’s best to be capable to validate that the app now makes use of the predefined Hi there PWA title and the picture preview ought to present the customized icon file as a substitute of a screenshot of the web page.
Correct standing bar colour for iOS PWAs
Lengthy story quick, there’s a nice article on CSS-Tips about the latest model of Safari and the way it handles varied theme colours on totally different platforms. It is a terrific article, it’s best to positively learn it, however in many of the instances you will not want this a lot data, however you merely wish to assist gentle and darkish mode in your progressive internet app. That is what I will present you right here.
For gentle mode we’ll use a white background colour and for darkish mode we use black. We’re additionally going to hyperlink a brand new type.css file so we will change the background of the positioning and the font colour in accordance with the present colour scheme. First, the brand new meta tags to assist theme colours each for gentle and darkish mode.
struct IndexTemplate: TemplateRepresentable {
let context: IndexContext
init(_ context: IndexContext) {
self.context = context
}
func render(_ req: Request) -> Tag {
Html {
Head {
Title(context.title)
Meta().charset("utf-8")
Meta().title(.viewport).content material("width=device-width, initial-scale=1")
Meta()
.title(.appleMobileWebAppCapable)
.content material("sure")
Meta()
.title(.appleMobileWebAppTitle)
.content material("Hi there PWA")
Meta()
.title(.colorScheme)
.content material("gentle darkish")
Meta()
.title(.themeColor)
.content material("#fff")
.media(.prefersColorScheme(.gentle))
Meta()
.title(.themeColor)
.content material("#000")
.media(.prefersColorScheme(.darkish))
Hyperlink(rel: .stylesheet)
.href("/css/type.css")
Hyperlink(rel: .appleTouchIcon)
.href("/img/apple/icons/192.png")
for dimension in [57, 72, 76, 114, 120, 144, 152, 180] {
Hyperlink(rel: .appleTouchIcon)
.sizes("(dimension)x(dimension)")
.href("/img/apple/icons/(dimension).png")
}
}
Physique {
Foremost {
Div {
H1(context.title)
P(context.message)
}
}
}
}
}
}Contained in the type CSS file we will use a media question to detect the popular colour scheme, similar to we did it for the .themeColor meta tag utilizing SwiftHtml.
physique {
background: #fff;
colour: #000;
}
@media (prefers-color-scheme: darkish) {
physique {
background: #000;
colour: #fff;
}
}
That is it, now the standing bar ought to use the identical colour as your major background. Attempt to swap between darkish and lightweight mode and ensure every thing works, there’s a cool PWA demo venture right here with totally different colours for every mode if you wish to double test the code. ✅
Splash display screen assist
Trace: it is ridiculous. Splash screens on iOS are problematic. Even native apps are inclined to cache the incorrect splash display screen or will not render PNG information correctly, now if it involves PWAs this is not essential higher. I used to be capable of present splash display screen pictures for my app, however it took me fairly some time and switching between darkish and lightweight mode is completely damaged (so far as I do know it). 😅
With a view to cowl each single system display screen dimension, you must add plenty of linked splash pictures to your markup. It is so ugly I even needed to create a bunch of extension strategies to my index template.
extension IndexTemplate {
@TagBuilder
func splashTags() -> [Tag] {
splash(320, 568, 2, .panorama)
splash(320, 568, 2, .portrait)
splash(414, 896, 3, .panorama)
splash(414, 896, 2, .panorama)
splash(375, 812, 3, .portrait)
splash(414, 896, 2, .portrait)
splash(375, 812, 3, .panorama)
splash(414, 736, 3, .portrait)
splash(414, 736, 3, .panorama)
splash(375, 667, 2, .panorama)
splash(375, 667, 2, .portrait)
splash(1024, 1366, 2, .panorama)
splash(1024, 1366, 2, .portrait)
splash(834, 1194, 2, .panorama)
splash(834, 1194, 2, .portrait)
splash(834, 1112, 2, .panorama)
splash(414, 896, 3, .portrait)
splash(834, 1112, 2, .portrait)
splash(768, 1024, 2, .portrait)
splash(768, 1024, 2, .panorama)
}
@TagBuilder
func splash(_ width: Int,
_ peak: Int,
_ ratio: Int,
_ orientation: MediaQuery.Orientation) -> Tag {
splashTag(.gentle, width, peak, ratio, orientation)
splashTag(.darkish, width, peak, ratio, orientation)
}
func splashTag(_ mode: MediaQuery.ColorScheme,
_ width: Int,
_ peak: Int,
_ ratio: Int,
_ orientation: MediaQuery.Orientation) -> Tag {
Hyperlink(rel: .appleTouchStartupImage)
.media([
.prefersColorScheme(mode),
.deviceWidth(px: width),
.deviceHeight(px: height),
.webkitDevicePixelRatio(ratio),
.orientation(orientation),
])
.href("/img/apple/splash/(calc(width, peak, ratio, orientation))(mode == .gentle ? "" : "_dark").png")
}
func calc(_ width: Int,
_ peak: Int,
_ ratio: Int,
_ orientation: MediaQuery.Orientation) -> String {
let w = String(width * ratio)
let h = String(peak * ratio)
swap orientation {
case .portrait:
return w + "x" + h
case .panorama:
return h + "x" + w
}
}
}Now I can merely add the splashTags() name into the pinnacle part, however I am undecided if the result’s one thing I can completely agree with. Right here, check out the tip of this tutorial about splash screens, the code required to assist iOS splash screens could be very lengthy and I have never even informed you concerning the 40 totally different picture information that you will want. Individuals are actually utilizing PWA asset mills to scale back the time wanted to generate these sort of photos, as a result of it is fairly uncontrolled. 💩
Secure space & the notch
A particular matter I might like to speak about is the protected space assist and the notch. I can extremely suggest to learn this text on CSS-Tips about The Notch and CSS first, however the primary trick is that we will use 4 environmental variables in CSS to set correct margin and padding values.
First we now have to alter the viewport meta tag and prolong our web page past the protected space. This may be achieved by utilizing the viewport-fit cowl worth. Contained in the physique of the template we’ll add a header and a footer part, these areas may have customized background colours and fill the display screen.
struct IndexTemplate: TemplateRepresentable {
let context: IndexContext
init(_ context: IndexContext) {
self.context = context
}
func render(_ req: Request) -> Tag {
Html {
Head {
Title(context.title)
Meta()
.charset("utf-8")
Meta()
.title(.viewport)
.content material("width=device-width, initial-scale=1, viewport-fit=cowl")
Meta()
.title(.appleMobileWebAppCapable)
.content material("sure")
Meta()
.title(.appleMobileWebAppTitle)
.content material("Hi there PWA")
Meta()
.title(.colorScheme)
.content material("gentle darkish")
Meta()
.title(.themeColor)
.content material("#fff")
.media(.prefersColorScheme(.gentle))
Meta()
.title(.themeColor)
.content material("#000")
.media(.prefersColorScheme(.darkish))
Hyperlink(rel: .stylesheet)
.href("/css/type.css")
Hyperlink(rel: .appleTouchIcon)
.href("/img/apple/icons/192.png")
for dimension in [57, 72, 76, 114, 120, 144, 152, 180] {
Hyperlink(rel: .appleTouchIcon)
.sizes("(dimension)x(dimension)")
.href("/img/apple/icons/(dimension).png")
}
splashTags()
}
Physique {
Header {
Div {
P("Header space")
}
.class("safe-area")
}
Foremost {
Div {
Div {
H1(context.title)
for _ in 0...42 {
P(context.message)
}
A("Refresh web page")
.href("/")
}
.class("wrapper")
}
.class("safe-area")
}
Footer {
Div {
P("Footer space")
}
.class("safe-area")
}
}
}
}
}Besides the background colour we do not need different content material to stream exterior the protected space, so we will outline a brand new CSS class and place some margins on it primarily based on the setting. Additionally we can safely use the calc CSS operate if we wish to add some further worth to the setting.
* {
margin: 0;
padding: 0;
}
physique {
background: #fff;
colour: #000;
}
header, footer {
padding: 1rem;
}
header {
background: #eee;
}
footer {
background: #eee;
padding-bottom: calc(1rem + env(safe-area-inset-bottom));
}
.safe-area {
margin: 0 env(safe-area-inset-right) 0 env(safe-area-inset-left);
}
.wrapper {
padding: 1rem;
}
@media (prefers-color-scheme: darkish) {
physique {
background: #000;
colour: #fff;
}
header {
background: #222;
}
footer {
background: #222;
}
}
It seems to be good, however what if we might like to make use of customized kinds for the PWA model solely?
Detecting standalone mode
If you wish to use the show mode media question in your CSS file we now have so as to add a manifest file to our PWA. Yep, that is proper, I’ve talked about earlier than that Apple prefers to make use of meta tags and hyperlinks, however if you wish to use a CSS media question to test if the app runs in a standalone mode you will should create an internet manifest.json file with the next contents.
{
"show": "standalone"
}
Subsequent you must present a hyperlink to the manifest file contained in the template file.
struct IndexTemplate: TemplateRepresentable {
func render(_ req: Request) -> Tag {
Html {
Head {
splashTags()
Hyperlink(rel: .manifest)
.href("/manifest.json")
}
Physique {
}
}
}
}Within the CSS file now you should use the display-mode selector to test if the app is operating in a standalone mode, you’ll be able to even mix these selectors and detect standalone mode and darkish mode utilizing a single question. Media queries are fairly helpful. 😍
/* ... */
@media (display-mode: standalone) {
header, footer {
background: #fff;
}
header {
place: sticky;
high: 0;
border-bottom: 1px stable #eee;
}
}
@media (display-mode: standalone) and (prefers-color-scheme: darkish) {
header, footer {
background: #000;
}
header {
border-bottom: 1px stable #333;
}
}
You may flip the header right into a sticky part by utilizing the place: sticky attribute. I often favor to comply with the iOS type when the web site is introduced to the end-user as a standalone app and I hold the unique theme colours for the net solely.
Remember to rebuild the backend server, earlier than you take a look at your app. Since we have made some meta modifications you might need to delete the PWA bookmark and set up it once more to make issues work. ⚠️
As you’ll be able to see constructing handsome progressive internet apps for iOS is sort of difficult, particularly if it involves the metadata insanity that Apple created. Anyway, I hope this tutorial will make it easier to to construct higher PWAs for the iOS platform. That is simply the tip of the iceberg, we’ve not talked about JavaScript in any respect, however possibly I will come again with that matter in a brand new tutorial in a while.
