Creating a Web App Manifest

[00:00:00]
>> Maximiliano Firtman: So this is how the manifest looks like, now we are going to write our own manifest, okay? It's not a big deal, and of course we will go property by property to understand what they are, some of them are straightforward, some of them are not. And something important is that on top of the web manifest spec, there other specs and other APIs that have appeared with time that are adding more properties.

[00:00:26]
We will mention some at the end and also on other courses available at Frontend Masters. There is one that I will point later on hardware. It's a tour of web capabilities. On that one, we mentioned some of these additions that you can add to the PWA platform, for that you need a manifest.

[00:00:48]
It's like plugins for the manifest, they're not part of the initial default spec, okay? Well, let's try to do that. So I'm going to BS Code now, I'm going to create a file. So the file can't have any name okay? But I typically would call this app.web.manifest. BS code now automatically recognizes the extension, so now you can see at the bottom.

[00:01:15]
It's turning on the JSON parser by default, so it knows where we are. And also it, lets us start writing things. So, first this is important, and actually you won't find this reference in a lot of places. You should start with with an id property. The id property was added.

[00:01:39]
It was probably three years ago, which means not every PWA developer realized that it's there. I'll never explain what happened, why it appeared in effect. But now it's used by Chrome and also it's used by Safari on the Mac and iOS. The id is just what you think, an app id.

[00:02:04]
But the idea is to put a string there that should be unique within your origin. By the way, I mentioned origin a couple of times at this point. Do you know what an origin is? Anyone know, just to be sure that we are on the same page.
>> Male Speaker: Protocol, host and port.

[00:02:22]
>> Maximiliano Firtman: It's protocol plus host plus port. So httpsblah.com, on port 80. That's an origin. So it's kind of the domain. So your domain. So I don't need to say, this is going to be called pathmasters. I don't need to do that because if I'm going to publish this on a domain, that will be my domain.

[00:02:45]
So it should be an id within my domain. So most of the time, if you will have only one PWA, sometimes it's a pattern these days to use a forward slash saying, okay, that's a PWA for that. But going back to the soda machines, it can be just soda/267.

[00:03:08]
That's the id of that soda machine. So each soda machine will have a different id. Okay, make sense? That's the idea. Let me go back and try to explain why the id exist these days. No one asked yet, but what happens when we are in a PWA on an operating system.

[00:03:28]
Are we creating an executable file in the OS? Are we compiling? Well, actually we are not doing anything. The browser is the one doing things. Browser has its own implementation, and in most cases, the browser is compiling an app or packaging an app, okay? The app does not contain our source code.

[00:03:52]
The app just contain metadata. It points to the URL, okay? But that app internally has an ID, okay? And the thing is, for years, let's open one PWA. I mean, if you like coffee, we can open Starbucks PWA. By the way, the Starbucks PWA is available on app.starbucks.com that's the URL they're using, so not star starbucks.com but app.star.com that's the PWA version of Starbucks website.

[00:04:24]
So if I open this, remember when we are talking about PWA is everything that has to do with debugging is available under application. So we go to Application, and here we have the manifest, where we can see the details of the manifest. And some they have some warnings there, but we can see some details.

[00:04:41]
And here it says Computed App ID. What happens? Why it says Computed App ID? Because Starbucks is not using the ID attribute, as I mentioned before. It wasn't there three years ago, okay? Well, they didn't use it, so Chrome had to create its own ID, and it's creating the ID based on the start URL.

[00:05:06]
It's a property that we will have right now. What's the problem with the start URL as a key? So think about database. It's a table of PWA's, okay? What's the problem of using the start URL as a key that the URL sometimes has some. What is this? utm_source does anyone know?

[00:05:24]
I'm pretty sure you have seen something similar.
>> Male Speaker: As a referrer, like where it's coming from.
>> Maximiliano Firtman: It has to do.
>> Male Speaker: Not HTTP referrer.
>> Maximiliano Firtman: It's not an HTTP header.
>> Male Speaker: But it's like words.
>> Maximiliano Firtman: It's Google Analytics. That's an argument for Google Analytics, so Google Analytics, then will treat this navigation as coming from the home screen.

[00:05:45]
That's the string. The thing is that tomorrow, maybe you wanna change this. You change the URL, and if you're using the URL as an ID, we have a problem, okay, because we change the URL, and then it thinks, it's a different PWA. Okay, you get it? So if we change the start URL, the problem is that Chrome will think it's a different PWA, and then you will end up with two installations, the old URL and the new URL.

[00:06:12]
Well, to solve the problem, we now have the id. So you can have your own start URL and in this start_url, you can add as many parameters and arguments you want and you can change those arguments like from. You can change those arguments in the future without any problem knowing you have an id and the id is not changing.

[00:06:35]
Because remember, different IDs will trigger different PWA installations. Okay, make sense? Why do we need a Start URL? That's the next question. Think about this. Let's go back to a Starbucks PWA. I'm in order. I'm in, let's go to a hot teas and I select a Chai Tea Latte.

[00:06:57]
So what happens if I install the app. In fact, you can see this here. If I install the app here, do I wanna install the Chai Tea Latte as my homepage? No, right, so I wanna install the whole app, not the current URL. So that's why, no matter where you are, when you start a PWA, you define the URL that you wanna use as your start URL, not bother from where it was installed.

[00:07:29]
Okay, so now I have my PWA. I can select a store, and by the way, you can see I'm using the Geolocation API. Look at the bottom. I have the icon here with the permission in the title bar, in the standalone title bar that looks really cool with the green, with the Starbucks green color there, okay?

[00:07:49]
So that's why we need a start URL. If you don't provide the start URL, you will have problems cuz the browser will pick the current URL when the user installs the app as the initial URL of the app, we don't want that. Another important thing is a scope.

[00:08:06]
Most of the time, scope, id, and start-url they start as the same value. What's the scope? The idea is that everything the scope is a path within your origin. Everything that, if you make a link, if you open another page, another HTML, if it's out of the scope, it will trigger an in-app browser.

[00:08:30]
We will see that in a second in action. If it's within the scope, it will treat it as part of your app, so it will be rendered there. Let me show you this. So we are here at Starbucks, okay? So if we change URLs, I'm still in the app, okay?

[00:08:46]
But there will be a point we can try to find one. If not, I can fake it here. I can click on Spotify. So of course, that's out of the scope. It's a link out of the scope. So if I click here, just Spotify. Look what happens. So I'm still in the app, the Starbucks app, but where I have this bar, this new bar here, okay, this one that is not really a full browser, okay?

[00:09:16]
But this is known as an inner browser, so I'm still in a Starbucks app, but Chrome is rendering a tab say, well, it's a Starbucks app. But you are just seeing here is in a different URL, and you can see the domain and the title. Why is that appearing to reduce phishing?

[00:09:35]
Because, let's say you have your bank account. You open your bank, your home banking, and someone is checking some JavaScript, and it's changing the URL of the current navigation. You want to know that now you're on the different URL. Okay, it makes sense. So that's why that happens.

[00:09:53]
So that's why it's important to add the scope. If you don't define the scope, it will take the current folder that, yeah, it's everything is there in the root, it will work anyway. But it's important to specify explicitly, yeah, I do have a scope. Then the other important two are name and short_name.

[00:10:11]
By the way, in this session, we will always use underscore as a way to separate words. The name is the name of your app. It can be a long name for example, I can call this is the CodepadMasters, the best notepad for your device. So what's the problem with that name?

[00:10:32]
It's too long for an icon, for the name that appears in the icon. But it might be okay for the alt-tab, for the tag switcher, when you're searching the app, okay? But not for the icon. So that's why we have a short name where we can say, I don't know, CodeMaster, maybe even CodepadMaster doesn't fit.

[00:10:54]
So, it depends on the device. It's difficult to give you one rule. But typically, 11 characters is safe anywhere. Also, it depends on the font size of the user but 11 characters is okay. More than 11 characters, it might not fit. But you can say, I don't know, CM or CodePadM or whatever you pick your option, okay?

[00:11:17]
So if I just say this, I'm still not the progressive web app because there is one more property that is the most important property that I have to set that says display. And I said choose, I need to set the value as standalone. In a couple of minutes, we will see all the possible values for that thing.

[00:11:39]
But that's the one that says, hey, I wanna be in a standalone app, okay? I don't just wanna be a website. I wanna be a standalone app. So if you save this, now, for example, if I go to the iOS simulator and I refresh. I still don't see any difference, but if I add to the home screen share, add to the home screen, nothing happens.

[00:12:03]
I was expecting to see my title here why? I set the name. I don't have an icon yet. Yeah, that's true. But I set the name. Why is not taking my name? Does anyone know? Does anyone knows why? There is one important step that we are missing. And I'm pushing your brains because we have already seen that step.

[00:12:30]
How does the browser knows that's my manifest?
>> Male Speaker: You have to link it from the HTML.
>> Maximiliano Firtman: Exactly how to link it from the HTML. If not, it's not gonna work. So I need to go to my HTML and typically in the hell, you don't need to, but typically it goes there.

[00:12:46]
We are going to add the rel manifest pointing to that file. If not, it's not gonna work, okay? It's not like the fob icon that it looks by default for a file with a name, no. So you have to link it explicitly. So after doing that, let's go back here.

[00:13:07]
I need to refresh, reload, so it should get it. And I can try again, add to the home screen. And now you can see a difference. I see CodepadM, so it's kind of reading my manifest. I don't have an icon, so by default these days, iOS is just using your theme color.

[00:13:29]
And because I don't have a theme color, it's just black by default, and a letter with the initial of your title, of the app's name, okay? Before, that was two years ago, it was taking a screenshot. That's actually pretty cool to see the screenshot, but they changed it, [LAUGH] anyway.

[00:13:45]
So if I add it, I have an icon. You say, yeah, but that's a bookmark to your website. But if I open this, now I'm in full screen. So I'm my own app. So, just that? Yeah, I kind of like that. Trying to pull this over, okay. So I have my own app on iOS.

[00:14:10]
Yeah, congratulations, you have just created your first, iOS application. Now it looks like an app. We can still make it better, nicer, okay? But just having this manifest with just some properties, we have an app. We are not passing the criteria completely. We don't have an icon for example, that was mandatory and some other properties.

[00:14:37]
Something else that I can add for now is the theme color, theme_color. I can set any CSS color will work, but stay with the CSS3 colors, even CSS2 colors that are just the name colors Or RGV. So, don't use transparencies, the new CSS colors that we can define not in the RGV space, but in the P3 space.

[00:15:06]
Don't use that because it may work on some platform, but it's not like compatible, and you don't need to get into that, okay? So for example, in our case, if I go to style CSS, I have a couple of CSS variables here. So I can take one of these colors, I know this one, or you can try with your own color, if you want, doesn't matter, and I paste the CSS color here.

[00:15:29]
And what's gonna be the change? First once and it's important I change the manifest, should I see the change in the install app? I'm seeing a face of a clear no, but actually the answer is, it depends on the platform. On iOS, the answer is, no, yeah, you were right, but on iOS.

[00:15:51]
So on iOS, if I change the manifest, it's not gonna change the icons that were already installed. On Android and next desktop, it will update the metadata and the icon not immediately, it will take some time. There is an update process. I mean, in an advanced workshop we can get there.

[00:16:09]
Hey, but there is a whole algorithm actually, if you go to web.devlearnpwa, that's the book that I author. I have all the explanation and the algorithm, and it's too complex to take time right now for that. But just to say that if you change and publish a new manifest with new data, some browsers will pick that change and your users will get an update.

[00:16:33]
IOS, no, so in IOS, I should delete the icon or just install another one, wherever you want, okay? So I can go here, refresh, install another one. And now there is a difference. I don't see the black background. And now you see that color is actually my theme color, so you can see I'm matching the color.

[00:16:59]
So now the status bar also has that color. That's the same color when you define the theme color in JSON, that's all.
>> Female Speaker: This is only for the manifest in terms of having to re download the app for updates.
>> Maximiliano Firtman: Yeah, so, the thing that I set for updates is for the manifest, for the metadata.

[00:17:20]
So, if you wanna change the colors, you wanna change the icon, you wanna change the app, same, the contents of the app has a completely different lifecycle. And, yeah, you will be able to update the contents of your iOS, okay? So I was just talking about the metadata and the icon that is installed.

[00:17:39]
That's the basic of a web app manifest. And before actually seeing more about the contents of that file, it's important to say that there is no standard way to make our content available for example in different languages using just the manifest. So there is no way to use the JavaScript internationalization, API or things like that.

[00:18:02]
So the only way in case you want your icon or the name of your app to be in Chinese, in Russian, in English, in Spanish and and so on, is to create different manifest first and then change the link or serve the manifest dynamically. So server-side, using server-side mappings or your server-side language to detect the language and then change the response on the JSON.