How you can make a PWA for iOS?
A progressive internet utility is only a particular type of web site, that may look and behave like a local iOS app. In an effort to construct a PWA, first we’ll create a daily web site utilizing SwiftHtml. We are able to begin with a daily 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 utility framework, which can be utilized to construct server facet Swift purposes, it is a fairly wonderful software I’ve a newbie’s information publish about it.
In fact we’ll want some parts for rendering views utilizing SwiftHtml, you should utilize 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. You must 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 most important HTML doc. Since we’re utilizing a Swift DSL to jot 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 keep up 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 {
Principal {
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 through the use of the beforehand outlined template helper strategies on the Request object.
import Vapor
import SwiftHtml
var env = strive Surroundings.detect()
strive LoggingSystem.bootstrap(from: &env)
let app = Utility(env)
defer { app.shutdown() }
app.get { req -> Response in
let template = IndexTemplate(.init(title: "Whats up, World!",
message: "This web page was generated by the SwiftHtml library."))
return req.templates.renderHtml(template)
}
strive app.run()
It’s simply that simple to setup and bootstrap a completely working internet server that’s able to rendering a HTML doc utilizing the ability of Swift and the Vapor framework. If you happen to run the app you need to be capable of see a working web site by visiting the http://localhost:8080/ handle.
Turning a web site into an actual iOS PWA
Now if we need to rework our web site right into a standalone PWA, we’ve got to supply 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 type of an odd route if it involves PWA assist. They’ve fairly a historical past of “considering outdoors of the field”, this mindset applies to progressive internet apps on iOS, since they do not are likely to comply with the requirements in any respect. For Android gadgets you would create a manifest.json file with some predefined keys and you would be simply nice together with your PWA. Alternatively Apple these days prefers numerous HTML meta tags as an alternative of the online manifest format.
Personally I do not like this method, as a result of your HTML code will likely be bloated with all of the PWA associated stuff (as you will see that is going to occur if it involves launch display photographs) and I consider it is higher to separate these type of issues, however hey it is Apple, they cannot be fallacious, proper? 😅
In any case, let me present you the way to assist numerous PWA options on iOS.
Enabling standalone app mode
The very first few keys that we would like so as to add to the index template has the apple-mobile-web-app-capable title and you need to use the “sure” string as content material. This may point out that the app ought to run in full-screen mode, in any other case it will be displayed utilizing Safari identical to a daily 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 {
Principal {
Div {
H1(context.title)
P(context.message)
}
}
}
}
}
}
We must always change the hostname of the server and pay attention on the 0.0.0.0 handle, this manner in case your cellphone is on the identical native WiFi community you need to be capable of attain your internet server instantly.
import Vapor
import SwiftHtml
var env = strive Surroundings.detect()
strive LoggingSystem.bootstrap(from: &env)
let app = Utility(env)
defer { app.shutdown() }
app.http.server.configuration.hostname = "0.0.0.0"
if let hostname = Surroundings.get("SERVER_HOSTNAME") {
app.http.server.configuration.hostname = hostname
}
app.get { req -> Response in
let template = IndexTemplate(.init(title: "Whats up, World!",
message: "This web page was generated by the SwiftHtml library."))
return req.templates.renderHtml(template)
}
strive app.run()
Yow will discover out your native IP handle by typing the next command into the Terminal app.
ifconfig | grep -Eo 'inet (addr:)?([0-9]*.){3}[0-9]*' | grep -Eo '([0-9]*.){3}[0-9]*' | grep -v '127.0.0.1'
ifconfig | sed -En 's/127.0.0.1//;s/.*inet (addr:)?(([0-9]*.){3}[0-9]*).*/2/p'
Simply use that IP handle and go to the http://[ip-address]:8080/ web site utilizing your iOS gadget, then you need to be capable of add your web site to your property display as a bookmark. Simply faucet the Share icon utilizing Safari and choose the Add to Dwelling Display screen menu merchandise from the listing. On the brand new display faucet the Add button on the highest proper nook, this can create a brand new icon on your property display 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, when you contact the newly created icon it ought to open the webpage as a standalone app (with out utilizing the browser). In fact the app remains to be only a web site rendered utilizing an online view. The standing bar will not match the white background and it has no customized icon or splash display 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, happily the SwiftHtml library has predefined enums for all of the Apple associated meta names, so you do not have to kind that a lot. The icon state of affairs is a little more troublesome, since we’ve got 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("Whats up 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 {
Principal {
Div {
H1(context.title)
P(context.message)
}
}
}
}
}
}
As you’ll be able to see icons are referenced through the use of the Hyperlink tag, utilizing the Apple contact icon rel attribute. The default icon with out the sizes attribute generally is a 192×192 pixel picture, plus I am offering some smaller sizes through the use of a for loop right here. We additionally must serve these icon information through the use of Vapor, that is why we’ll alter the configuration file and allow the FileFiddleware.
import Vapor
import SwiftHtml
var env = strive Surroundings.detect()
strive LoggingSystem.bootstrap(from: &env)
let app = Utility(env)
defer { app.shutdown() }
app.middleware.use(FileMiddleware(publicDirectory: app.listing.publicDirectory))
app.http.server.configuration.hostname = "0.0.0.0"
if let hostname = Surroundings.get("SERVER_HOSTNAME") {
app.http.server.configuration.hostname = hostname
}
app.get { req -> Response in
let template = IndexTemplate(.init(title: "Whats up, 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 happy to create it and place the app icons beneath the Public/img/apple/icons folder. If you’re working the server from the command line you will be nice, however in case you are utilizing Xcode it’s a must to specify a customized working listing for Vapor, this can enable the system to lookup the general public information from the correct place.
Your customized icons will not present up in case you are utilizing a self-signed certificates.
Construct and run the server and attempt to bookmark your web page once more utilizing your cellphone. While you see the add bookmark web page you need to be capable of validate that the app now makes use of the predefined Whats up PWA title and the picture preview ought to present the customized icon file as an alternative of a screenshot of the web page.
Correct standing bar colour for iOS PWAs
Lengthy story quick, there’s a nice article on CSS-Methods about the newest model of Safari and the way it handles numerous theme colours on totally different platforms. It is a fantastic article, you need to undoubtedly learn it, however in many of the instances you will not want this a lot information, however you merely need to assist mild and darkish mode to your progressive internet app. That is what I’ll present you right here.
For mild mode we’ll use a white background colour and for darkish mode we use black. We’re additionally going to hyperlink a brand new fashion.css file so we will change the background of the positioning and the font colour based on the present colour scheme. First, the brand new meta tags to assist theme colours each for mild 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("Whats up PWA")
Meta()
.title(.colorScheme)
.content material("mild darkish")
Meta()
.title(.themeColor)
.content material("#fff")
.media(.prefersColorScheme(.mild))
Meta()
.title(.themeColor)
.content material("#000")
.media(.prefersColorScheme(.darkish))
Hyperlink(rel: .stylesheet)
.href("/css/fashion.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 {
Principal {
Div {
H1(context.title)
P(context.message)
}
}
}
}
}
}
Contained in the fashion CSS file we will use a media question to detect the popular colour scheme, identical 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 most important background. Attempt to change between darkish and light-weight mode and ensure every little thing works, there’s a cool PWA demo undertaking right here with totally different colours for every mode if you wish to double test the code. ✅
Splash display assist
Trace: it is ridiculous. Splash screens on iOS are problematic. Even native apps are likely to cache the fallacious splash display or will not render PNG information correctly, now if it involves PWAs this is not needed higher. I used to be in a position to present splash display photographs for my app, however it took me fairly some time and switching between darkish and light-weight mode is completely damaged (so far as I do know it). 😅
In an effort to cowl each single gadget display dimension, it’s a must to add a number of linked splash photographs 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,
_ top: Int,
_ ratio: Int,
_ orientation: MediaQuery.Orientation) -> Tag {
splashTag(.mild, width, top, ratio, orientation)
splashTag(.darkish, width, top, ratio, orientation)
}
func splashTag(_ mode: MediaQuery.ColorScheme,
_ width: Int,
_ top: 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, top, ratio, orientation))(mode == .mild ? "" : "_dark").png")
}
func calc(_ width: Int,
_ top: Int,
_ ratio: Int,
_ orientation: MediaQuery.Orientation) -> String {
let w = String(width * ratio)
let h = String(top * ratio)
change 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 unsure if the result’s one thing I can completely agree with. Right here, check out the top of this tutorial about splash screens, the code required to assist iOS splash screens could be very lengthy and I have not even advised you in regards to the 40 totally different picture information that you will want. Individuals are actually utilizing PWA asset mills to cut back the time wanted to generate these type of photos, as a result of it is fairly uncontrolled. 💩
I am utilizing this method in Feather CMS, so if you would like to obtain some pattern information you’ll be able to seize them from GitHub. I am not proud of splash display assist, however hey, it simply works, proper? 🤔
Secure space & the notch
A particular matter I might like to speak about is the secure space assist and the notch. I can extremely advocate to learn this text on CSS-Methods 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’ve got to vary the viewport meta tag and prolong our web page past the secure space. This may be performed through the use of the viewport-fit cowl worth. Contained in the physique of the template we’ll add a header and a footer part, these areas could have customized background colours and fill the display.
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("Whats up PWA")
Meta()
.title(.colorScheme)
.content material("mild darkish")
Meta()
.title(.themeColor)
.content material("#fff")
.media(.prefersColorScheme(.mild))
Meta()
.title(.themeColor)
.content material("#000")
.media(.prefersColorScheme(.darkish))
Hyperlink(rel: .stylesheet)
.href("/css/fashion.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")
}
Principal {
Div {
Div {
H1(context.title)
for _ in 0...42 {
P(context.message)
}
A("Refresh web page")
.href("https://theswiftdev.com/")
}
.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 movement outdoors the secure space, so we will outline a brand new CSS class and place some margins on it based mostly on the atmosphere. Additionally we can safely use the calc CSS perform if we need to add some additional worth to the atmosphere.
* {
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 would like to make use of customized types for the PWA model solely?
Detecting standalone mode
If you wish to use the show mode media question in your CSS file we’ve got 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 need to create an online manifest.json file with the next contents.
{
"show": "standalone"
}
Subsequent it’s a must to 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 utilize the display-mode selector to test if the app is working 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;
prime: 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 possibly can flip the header right into a sticky part through the use of the place: sticky attribute. I often favor to comply with the iOS fashion when the web site is introduced to the end-user as a standalone app and I preserve the unique theme colours for the online solely.
Do not forget to rebuild the backend server, earlier than you take a look at your app. Since we have made some meta adjustments you might need to delete the PWA bookmark and set up it once more to make issues work. ⚠️
