Writing to myself

Escribiendo para mi mismo

Create & Share a Business Card in Passbook

While in the #WWDC2015, meeting new developers, recruters, media is imperative, reason why, you will be finding yourself sharing business cards.

I met one developer, who had an unusual way to share his card, and that way was using Passbook, I inmediately asked him to share how he did it and in my time in the conferences, beside putting attention to them, I was working on my own digital card.

Unfortunately, I found myself checking other sources to complete the task, so I decided to compile the information and share it here.

First and most importantly, you will need an apple developer account (this should be no issue anymore due on #WWDC2015, it was announced that there will be no cost to get one). Go a head a create one, then come back.

Passbook technology works around a file which its format is .pkpass, when either the mail or mobile safari detects this file, it will render the pass correctly, once you click on it, it will handle the rest for you (presenting the view to add it into the pass library).

Creating .pkpass file

Before doing anything, lets create a new directory to put all the things we will be creating.

Having said the above. The following image describes the skeleton of the pass.

image

As you may already saw, we can localize passes creating the appropiated directory structure, but that is something we wont do now. There are 2 files missing on that image, they are the manifest.json file and the actual signature file (which we will create soon).

Now, how is this translated to the actual pass? The following image describes that.

image

The actual content information resides inside the .json file.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

{
  "formatVersion"         : 1,
  "passTypeIdentifier"    : "<INSERT_PASS_IDENTIFIER>",
  "serialNumber"      : "0",
  "teamIdentifier"        : "<INSERT_TEAM_IDENTIFIER>",
  "barcode" : 
  {
  "message"   : "<INSERT_BARCODE_MESSAGE>",
  "format"    : "PKBarcodeFormatAztec",
  "messageEncoding"   : "iso-8859-1"
  },
  "organizationName"  : "<INSERT_ORGANIZATION_NAME>",
  "description"       : "<INSERT_DESCRIPTION>",
  "logoText"          : "<INSERT_TEXT_THAT_GOES_NEXT_TO_LOGO>",
  "foregroundColor"   : "rgb(1, 0, 0)",
  "backgroundColor"   : "rgb(0, 0, 1)",
  "generic"   : 
  {
  "primaryFields" : 
  [
    {
      "key"       : "name",
      "label"     : "NAME",
      "value"     : "<INSERT_VALUE>"
    }
  ],
  "secondaryFields" : 
  [
    {
      "key"       : "position",
      "label"     : "POSITION",
      "value"     : "<INSERT_VALUE>"
    }
  ],
  "auxiliaryFields" : 
  [
    {
      "key"       : "email",
      "label"     : "EMAIL",
      "value"     : "<INSERT_VALUE>"
    },
    {
      "key"       : "twitter",
      "label"     : "TWITTER",
      "value"     : "<INSERT_VALUE>"
    }
  ],
  "backFields" : 
  [
    {
      "label"     : "EMAIL",
      "key"       : "emailBack",
      "value"     : "<INSERT_VALUE>"
    },
    {
      "label"     : "TWITTER",
      "key"       : "twitterBack",
      "value"     : "<INSERT_VALUE>"
    },
    {
      "label"     : "GITHUB",
      "key"       : "githubBack",
      "value"     : "<INSERT_VALUE>"
    },
    {
      "label"     : "WEB",
      "key"       : "webBack",
      "value"     : "<INSERT_VALUE>"
    }
  ]
  }
}

Remember I mentioned you need an Apple Developer Account, the .json file requires “passTypeIdentifier” & “teamIdentifier”. You can get the second one under Account Information area in the developer portal. The first one will be the next thing to do.

Feel free to play with the values on the .json file, you can change it entirely with the ones you have in mind. Now lest put this on hold and create all the boring stuff we need from the dev portal.

Head to the Developer Portal

Go to Certificates, Identifiers & Profiles in the dev center and click on Pass Type IDs, now add a new one - you should see something like this.

image

For this example be sure to use the following format “pass.com.yourdomain.appname” as the website mentions. Go a head an register the pass. Once created, go back to the pass.json file and update the “passTypeIdentifier” value with the one you just added.

Click on the recently created ID and you will have the option to edit. Then you will create the certificate to be used. In order to do that, follow the instructions from the dev center. Once you are done, download the certificate and add it into the passbook folder we created at the beginning and do not forget to add it into the keychain too.

image

Going back to the Pass directory

Early, I did mention we needed to create a manifest.json file, the purpose of this file is to describe what is inside the pass package. Below you will find and example of it.

1
2
3
4
5
6
7
8
9
{
 "thumbnail.png":"2a25d4de25819de588c42fb3f49888e94b6e83b9",
 "thumbnail@2x.png":"e29426fdd44a8e0c50eb4e38daefc607c773ec9e",
 "logo.png":"e7710517855699946da011df94f78264fdf20e57",
 "logo@2x.png":"8b6b2d7ce29d014a6ea36d452fbc3695b77c0ca7",
 "icon.png":"e7710517855699946da011df94f78264fdf20e57",
 "icon@2x.png":"8b6b2d7ce29d014a6ea36d452fbc3695b77c0ca7",
 "pass.json":"6c5791fc47b132fe627c6b5a168b57f22bc1c3a7"
}

Where did those weird characters come from? Those characters are their checksums, you can get them using Terminal using the following command (head to the passbook directory using terminal).

1
openssl sha1 pass.json

The result will be something like this:

1
SHA1(pass.json)= 6c5791fc47b132fe627c6b5a168b57f22bc1c3a7

Create the file and put it next to the pass.json file. Its obvious you have to do the same with the rest of the files/assets.

IMPORTANT: If you happen to update either the assets or the pass.json file. You need to update the manifest.son file. Do not forget about this.

The other file we need to create is the actual signature. Why do we need a signature? Ask Apple!

In order to do it, we will need the certificate we created before on the dev center. Open KeyChain Access, find the certificate you created following the format “pass.com.yourdomain.appname” and export it as a .p12 file - for this example, I named it pass.p12 - (you will be prompted to add a password - we will use it in a few seconds).

Next, go back to Terminal app and type the following command:

1
openssl pkcs12 -in pass.p12 -clcerts -nokeys -out passcertificate.pem -passin pass:<INSERT_PASSWORD_HERE>

The result of this command will be a file named passcertificate.pem. Now, lets export the key using the next command and the result will be passkey.pem:

1
openssl pkcs12 -in pass.p12 -nocerts -out passkey.pem -passin pass: -passout pass:<INSERT_PASSWORD_HERE>

We are almost done, we need one more certificate, this time its WWDR certificate, head to KeyChain Access and look for “Apple Worldwide Developer Relations Certification Authority” and export it as a .pem file - for this example I choose the name WWDR.pem - finally, we have all needed to create the signature file. Head back to the Terminal App and type the following command:

1
openssl smime -binary -sign -certfile WWDR.pem -signer passcertificate.pem -inkey passkey.pem -in manifest.json -out signature -outform DER -passin pass:<INSERT_PASSWORD_HERE>

This will create a signature file. From here, we just need to zip the files, but lets make sure we have everything, the following image describe what should be on the package.

image

Simply, select all those files and compress them, replace the .zip file extension to be .pkpass and you will have your pass ready to share.

Sharing your Business Card Pass

There are 2 ways to share your pass, for the sake of this example we will use the email approach. As I mentioned at the beginning, iOS will handle everything if you use Mail or Mobile Safari.

Simply, send you an email to your self or any other people attaching the .pkpass file and if successfull, the apps will render the pass properly. You should see something like this.

image

Now, you can go even further and use the barcode message to be the URL were people can download the pass when they scanned, you will be resposible to create the endpoint and endup with something like this.

image

Javier Azuara