DEV Community: Ruben

Getting started with Apple's MapKit JS

Ruben — Fri, 08 Jun 2018 19:48:15 +0000

Originally published at blog.rubeng.nl

This article mainly explains how to easily get started with MapKit JS. If you already have it set up I'd advise you to check out Apple's excellent documentation on MapKitJS.

Since I first spotted Apple Maps on the web I loved it. You could - with a lot of hassle - run it on your own site (it involved proxying Apple endpoints 🧐).

That's why I was quite happy when Apple announced their official MapKit JS library in beta last week!

The new MapKit JS library will make adding Apple Maps to your site very easy - so I thought. In their product demo and on the Developer site Apple shows the following way to add an authentication token (JWT-token) to your embed code.

mapkit.init({
    authorizationCallback: function(done) {
        var xhr = new XMLHttpRequest();
        xhr.open("GET", "/services/jwt");
        xhr.addEventListener("load", function() {
            done(this.responseText);
        });
        xhr.send();
    }
});

Just to be clear, you'll need to host this /services/jwt/ endpoint yourself. The endpoint should return a signed JWT-token which can then be used to authenticate against Apple endpoints.

Using this configuration means that every single Map instantiation would cost one call to your own servers before you can initialise the map. Apart from the extra load you'll need to create an (API-)endpoint, configure JWT libraries, etc. Especially for static websites this is quite a problem.

What's the alternative?

Luckily, Apple probably realised this wouldn't work in every situation. So, hidden in the documentation they say:

[..]. It can also be run on a development machine to generate a long-lived token to be checked directly into source-code. [...]
Apple Developer documentation

This JWT-token can be comitted into source control. No endpoints for JWT-signing required, hurray! Of course these tokens do have an expiry date, you are however free to set this expiry date to 10 years in the future.

This is exactly what we (I, at least) want. Embedding a token in the code, without extra calls, without extra hassle.

Also, comitting the token into source code doesn't mean you've lost all control. Using the Apple Developer portal you can revoke the private key you used to generate the JWT.

We've just gone from the cumbersome authentication flow above to the following:

mapkit.init({
    authorizationCallback: function(done) {
        done('Insert JWT-token here');
    }
});

But, first we'll need to generate a JWT-token.

If you're not familiar with JWT's you might want to read this excellent article by Auth0.

Generating the JWT

Before you can get started we'll need to gather some requirements.

You'll need to register a Maps ID. This is a unique identifier for your Map instance. Apple specifies that you'll want to use one Maps ID per environment (for example development and production).
In order to sign the JWT's you'll also need a private key with MapKit JS services enabled.

After creating a new private key you're provided with a PKCS #8 private key. The private key does not require a password.

Do make sure you save the key somewhere safe, Apple only provides the download once. 🔑

Now that we have all the requirements we're going to need to generate a JWT-token according to the specifications on Apple's website.

Apple uses the ES256 algorithm using Ecliptic Curve Cryptography so you'll want to have the JWT algorithm header set to ES256.

You'll also need to add your Key ID to the JWT header, using the kid parameter. You'll find this ID in the Developer portal where you also created the key.

And, as JWT specifies, you'll need to add the JWT type to the header.

Putting it all together your JWT header now looks as follows:

{
  "alg": "ES256",
  "typ": "JWT",
  "kid": "Your Key ID"
}

Next up; the JWT payload. Nothing fancy here.

Apple specifies that the iss (issuer) parameter should be set to the Team ID with which you have created the Maps ID & key.

Apple recommends - but doesn't require - using the origin parameter as well. You can specify the origin that is allowed to use the MapKit JS code. This can prevent unauthorised use of your token which would count towards your daily limit.

Also, following JWT's specification you'll need to set the exp (expiry) and iat (issued at) parameters. These values are specified in seconds since Epoch.

I'd advise you to use a long expiry time, once the token expires your map won't load anymore. You can use a value that best suits your needs.

Our payload is now complete and looks like this:

{
  "iss": "Your Team ID",
  "iat": 1528473755323,
  "exp": 1528476433723,
  "origin": "Your origin header" // Recommended, but not required.
}

Optionally, you can provide an origin parameter to restrict on which domains the code can be used. This should match the Origin header passed by your browser.

The final step is signing the first two parts of the JWT token. As I'm not a cryptography export I won't go into detail on this. There are loads of libraries that can do the signing for you.

The signature is made up of the following parts:

ECDSASHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  privateKey
)

When we put our JWT together we'll get something along the lines of:

eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IllvdXIgS2V5IElEIn0.eyJpc3MiOiJZb3VyIFRlYW0gSUQiLCJpYXQiOjE1MTYyMzkwMjIsImV4cCI6MTUyODQ3NjQzMzcyMywiV2hlbiB5b3UiOiJyZWFkIHRoaXMsIiwieW91IHJlYWxseSB0aG9yb3VnaGx5IjoicmVhZCB5b3VyIGFydGljbGVzLiJ9.yGNubQUo6tzYsArulZgeNZxv7-6anvCC57tfTV0zqK2HN5HbmwLGesIA2nfXktD1UcN3mkGhTaUqxkEnIA5xuQ

You can now use this token to authenticate the Apple endpoints.

An easier way

If you were just looking for a simple Map embed with an API-token this article might have shocked you a bit. Not to worry, there's an easier way.

I created a tool which generates the embed code (and JWT token) for you. You'll still need the requirements as listed above (and on the tool), but the rest is easy as pie.

You just enter your details and the embed code comes out, easy! Also, your details never leave your browser, so there's no compromise on security. 🔐

Check it out at mapkitjs.rubeng.nl

Issues, compliments, comments? Let me know at @rubengmrs or ruben@rubeng.nl.

Apple is a registered trademark of Apple, Inc. This article, tool and references are not owned by, or affiliated with, Apple Inc.

Also, check out blog.rubeng.nl for my other posts if you haven't already.

Teaching kids how to code

Ruben — Sat, 28 Jan 2017 18:14:48 +0000

It's a huge hype to learn how to code these days. And whilst I don't think that _every_one should learn to code I do think it can help kids to think in a logical fashion.

That's why when the Rietveld Lyceum asked me to give a guest lecture I happily said yes.

Beforehand

The Rietveld Lyceum organises guest courses of all kinds for their students. The idea is that students can get an idea of the jobs and functions that exist all around them (I really appreciate this). The assortment of lessons is extremely diverse, one can choose to get a ride with an ambulance, learn how to act, how to farm, how to start a business and much much more. The lesson I added was "Programming". I did not yet know the full program for the lessons but I was planning on teaching them how to build a (very) simple website.

I think the advantage I had with giving this course is that the students chose the subject themselves. If they weren't interested in learning how to code, they wouldn't choose to follow the course.

The course featured a series of 4 lessons in a row, every Thursday from 14:45 till 16:15. There was room for 15 students.

The first lesson

Developing the first lesson was the hardest. I had no clue of the level of the students. I chose to allow any class (VMBO, HAVO, VWO) to apply for the lesson, but I did not know if there would be a difference in programming level (I've seen better MBO programmers than HBO programmers).

The VMBO (voorbereidend middelbaar beroepsonderwijs; literally, "preparatory middle-level applied education") education lasts four years, from the age of twelve to sixteen.[5] It combines vocational training with theoretical education in languages, mathematics, history, arts and sciences.

Secondary education, which begins at the age of 12 and, as of 2008, is compulsory until the age of 18, is offered at several levels. The two programmes of general education that lead to higher education are HAVO (five years) and VWO (six years). Pupils are enrolled according to their ability, and although VWO is more rigorous, both HAVO and VWO can be characterized as selective types of secondary education.

I decided to let the first lesson be about learning a few basic HTML-tags, playing around with those and some extra material for students who picked up the simple material quicker.

I first introduced myself, what I was studying, what I was working on (eventually forgot to tell my name) and what we we're going to do during the lessons. I explained that depending on how quickly the material was picked up by the students the course could change over time.

After introducing myself briefly I started explaining why programming was important. I came up with three reasons:

Build anything you want
Learn to think in a logical fashion
Many career opportunities

I know there are many, many more reasons as to why coding is important but have you ever met a student who likes to listen to the teacher rattle on about one subject?

What I found very difficult next was to translate my own knowledge about coding to students who had never programmed in their entire lives.

How do I style a page? Just add a style-tag, create a class in CSS and append the class to the HTML-tag you want to style. Sorry. What? 🤔

I wanted to prevent the above from happening.

So, that's why I explained that HTML is nothing more than a file on your computer (or a server). This way I tried to make the, for the students vague, term "HTML" tangible. I showed an example of a very basic HTML-page and explained that when saving the file with the ".html"-extension you created your very first HTML-file.

Then, after listing a few basic rules about HTML (closing tags, what tags are, about including the HTML, head and body tag) I decided to throw the students in the deep end.

I created an empty JSFiddle where the basic rules were stated once again and asked the students to create their first HTML. My goal here was to get the students to interact with the code as soon as possible.

Of course, I could first talk about each and every HTML-tag, show half a dozen examples and then let them do it themselves. I think what I would have accomplished then was very bored students.

Results of the first lesson

You might imagine that there were a lot of questions. And this is what I really, really appreciated. The students were eager to learn how to create the next thing. Further on during the lesson I explained how to use the heading-tags (h1, h2, h3, etc), how to add text to a page (p-tag), how to add links to a page (href) and how to add images (img-tag) to the page.

What really struck me was the fact that I started the lesson with students who didn't even know what HTML was in the first place and ended the lesson with students who were Googling their way through new tags and some already started playing around with simple JavaScript-snippets.

Interested in the presentation of the first lesson? View it here.

Consecutive lessons

The second lesson started with a short repetition of the first lesson. Though, not in depth. Then, I asked the students to perform a small "test". Six questions about HTML, a few were two examples of HTML-code were shown and the students had to choose between those and a few theoretical questions. All the questions were multiple choice.

The results:

The average rating was 5/6 which translates to an 8.3.
The question most people got wrong was a question asking how to make a link open in a new window. (target="_blank").

The reason I took the test was to see if people caught on to the matter. If everyone forgot how to create the page they were (a) not interested or (b) the explanation was lacking.

Judging the from the results I can say the students did catch on. The students learned something a week ago, in 1,5 hour and still remember (almost) everything correctly.

In the third lesson I started with Bootstrap, the eventual goal of the course is to be able to create a simple website. Thus far they were able to create a simple page, but that's not a website. I chose Bootstrap because (again) it's accessible. I could have thought them how to use Flexbox but I think that would be very ambitious with 6 hours of hands-on time.

Using Bootstrap also posed some challenges. The students would have to download the framework to their computers, create an HTML file and then they could use the framework.

For this particular reason I chose to first explain how external CSS could be linked to HTML (<link href="" rel="stylesheet">) and then to provide them with a hosted Bootstrap (thanks BootstrapCDN)

At this time the students were also making the switch from standalone JSFiddle's to using an editor. I chose Atom because the UI is very straightforward and installing it is very easy. Installing on school computers, however, wasn't as easy as I hoped it to be. The computers were so slow that installing Atom would sometimes take up to 10 minutes, or the computer would stop working and a reboot was required. Eventually we did succeed to install it on all the computers.

The last lesson

Sooner than I realised the course was already over. In the last lesson I wanted to take an exam, clarify a few things about HTML and learn them how to use the Bootstrap navigation bar.

The "exam"

I decided that it would be fun for the students to have a reward for their hard work. That's why I designed an exam for the last lesson.

The exam consisted of 15 questions, the students had 15 minutes for the exam in total and the minimum score was 50%. Also, the exam was designed so that every student got a different exam. To take the exam I used ClassMarker, one of the few exam software which met my requirements. There were ~40 questions, the software picked 15 random questions and presented them to the students. When a student passed the exam they received an e-mail with the score and a certificate. If they failed, they could take the exam again (since the questions would be different and they could not see the correct answer of questions they made).

The results of the exam were consistent with what I expected. Some students scored very, very high (💯%) and some a little less. One student failed the first time but passed the second time with a 7.5 (75%). Although I designed the questions so that there was no difference in difficulty level, of course some questions were tougher.

Reflection

This was my first experience with teaching, ever. Also, it was my first experience ever with explaining HTML from start to end, I've helped other students out but they all already knew the basics. Sometimes it was difficult to talk (and keep talking) in layman's terms.

I also tried to find a balance between explaining and asking students to Google things themselves. You catch on to the matter way more quickly if you are interacting with it, by Googling your way around for example. But sometimes students would just get stuck, they tried to find a solution and just could not. In that case I was more than happy to explain it again. You do not want to become the teacher who never explains anything.

They exist 😉

Notes

I designed the course to have a lot of hands-on time, you don't learn to code by watching endlessly at slides from the teacher but by doing and researching.

Reactions from students

I think the explanation was extensive.> Just great! </answer> ;)> Would be great to have some more lessons so we could end with a real product.> I found it a very enjoyable course, it was well designed and I learned a lot.

Photos published with permission from the students.

Any remarks on this post? Please let me know! Drop me a line at ruben@rubeng.nl

Special thanks to:

ClassMarker for letting me use their great exam software 💯
Afke for the great time 🤘
The students for their commitment 🏃

First published at blog.rubeng.nl