Create your digital business card using PassKit

Recently, I decided to organize a little bit better the recourses and blog posts I kept all these years. One very interesting blog post I kept was from 2014 and described how to create a business card using PassKit(It was called Passbook back then). That blog post was written by Tom Harrington and it can be found here. I thought about it and actually, this is a cool, tech-savvy and eco-friendly way to create a business card, so I decided to give it a shot. I have to be honest, I was impressed by the result! During the process, however, I found out that a few things have changed in the last 4 years so I decided to write my own blog post about it explaining everything in more detail. If you follow this tutorial, then you will create a business card that will look like this.

IMG_0943-1

Prerequisites

To follow this tutorial, you will need:

  • A Mac computer running macOS 10.7 or later so that you can create the business card
  • A paid Apple developer account in order to create a Pass Type ID Certificate
  • A free Amazon S3 bucket so that you can share your business card with others.
  • Optional - A VCF file with your contact details only if you want to allow the recipient of your card to add your contact details to their contacts list. I'll explain how you can do that below.
Create a Pass Type ID Certificate

The first thing you have to do is to create a Pass Type ID Certificate from the Apple Developer Portal. Head over there and create a new pass certificate. Be sure to use a reverse domain name style for the identifier. (i.e pass.zarzonis.BussinessCard). Find a name identifier that you'd like to use. Think the name wisely because you can't delete pass certificates. They have to expire in order to be removed from your developer portal. Once created, download the certificate and double-click it in order to install it in the Keychain. Now that you have your certificate ready, we're ready to move to the next section.

Screen-Shot-2018-04-08-at-8.56.27-PM

Download the Signpass tool

The next step is to download the necessary executable file that will be used to generate and sign the pass you'll create. Apple provides an Xcode project that you could compile and generate this executable file on your own but I already did that for you so you can download it from here. For now, just unzip this file. If you still want to generate this file on your own, head to this link and follow the instructions on how to get the signpass tool.

Pass explanation and template

As you can see at the Wallet Developer Guide, and specifically at table 4-1, there are 5 pass styles. One of them is the Generic style which is what we'll use in this tutorial. We could create a new pass from scratch, but I think it's better if we use an existing pass as a template. For that reason, you can download my pass from here. After you download it, unzip the file and feel free to browse its contents. You may have noticed that the folder that was created has a .pass extension. This is required. So if you would like to name your pass as MyOwnPass, the folder with the pass files should be named MyOwnPass.pass. You should also know that the files inside that folder must have exactly the same names with the ones I have on my own pass. Keep that in mind when you replace the files with your own. Especially for the thumbnail, the images must also have the same sizes. Specifically the sizes are 90x90px, 180x180px and 360x360px for the 1x, 2x and 3x versions respectively. The following photo shows you the file structure your pass should have.

Screen-Shot-2018-04-08-at-11.46.11-PM

Pass distribution and Amazon S3

Before we move to the actual implementation of the pass, it's necessary to talk about the distribution of your pass. As you probably saw at the beginning of this tutorials, passes have a QR code. In our case, this QR code will be used to share the pass. Every time you'll want to share your business card with someone in person, then all she has to do in order to get your business card is to open the camera app on her iOS device and scan the QR code. On the other hand, if you want to share your business card online, you can use the URL where your pass is stored. Then the other person simply opens this URL from an iOS device and the pass is stored automatically on her device. In order to do that, you obviously need to store the pass on a server. For that, we'll use Amazon S3 because it's free for our use case and it also has the necessary security that it's needed in order to distribute a pass. The alternative would be to have your own server with SSL and host the file there. To be honest, I distribute my pass using my own server that hosts this very blog, but I don't expect from everyone to have their own server, so for this tutorial, we'll use Amazon S3. In order to proceed, head to the Amazon S3. If you have an Amazon account, then you can simply log in, otherwise, you'll have to create a new account. After you have your account ready, log in to Amazon S3 and create a new bucket. Just use the default settings. That's what you need to do for now. We'll come back later when we are ready to upload the pass itself.

Implement and customize the pass

Create a new folder for your pass including the .pass extension mentioned above and copy all the files from my template inside that folder. Just make sure that the folder you created has the same file structure with the picture from the Pass explanation and template section. Open the pass.json file with your favorite text editor. There are 3 values that you need to change right away. The teamIdentifier, the serialNumber and the passTypeIdentifier. You can find your Team ID at the Apple Developer Portal under the Membership tab. The serial number is a unique string that you have to use. In my case, I used zarzonis-businesscard-2018-2 so you could use something similar. This serial number identifies the pass, so as long as the pass has the same serial number, we're talking about the same pass. It's similar to an App ID for an iOS application. Finally, you'll have to supply the identifier you used when you created your certificate on the first section as the value of the passTypeIdentifier key.

The next step is to replace the URLs to your pass and optionally your VCF file with your own. In order to do so, go again to Amazon S3 and open the bucket you created earlier. Upload any file you want to the bucket. We'll use that file in order to find the full URL of your bucket. Don't worry, you can delete that file later on. When the upload finishes, click on that file and notice the URL that appears. This is the full URL that can be used to download that particular file. If you notice the last part of that URL, it's the name of the file you uploaded. As you probably already guessed, any file you'll upload to that bucket will have the same URL except of the last part which of course will be the name of that particular file. With that in mind, you can guess the URL of your pass and the optional VCF file. If you named the folder of your pass as MyOwnPass.pass, the name of the generated pass will be MyOwnPass.pkpass. Replace the URL of my .pkpass with your own. Do the same with the optional VCF file URL. If you don't want to add your VCF file to the pass, you can delete that section altogether. An example Amazon S3 URL looks like this.
Screen-Shot-2018-04-09-at-5.17.15-PM

Moving forward, you need to replace the rest of my details with your own(Name, email address etc). Carefully browse the pass.json file and replace everything. If you don't want to include a specific section, just delete it. For example, if you don't want to include the Twitter section, delete the following lines.
{
"attributedValue" : "<a href='https:\/\/mobile.twitter.com/zarzonis/tweets'>@zarzonis<\/a>",
"label" : "Twitter",
"key" : "twitterLink",
"value" : "https:\/\/mobile.twitter.com/zarzonis/tweets",
"dataDetectorTypes" : [
"PKDataDetectorTypeLink"]
}

If you want to change the colors of the pass, you can do that by changing the foregroundColor, backgroundColor and labelColor properties.

The last step is to replace the images of the pass. For this step, you don't have to edit the pass.json file. Just replace the images inside the .pass folder with your own but be careful to use exactly the same names and sizes.

Generate the pass

Finally, you're ready to generate the actual pass. Move the signpass tool to the same folder with your .pass folder. Navigate using the terminal to the folder that stores both the .pass folder and the signpass tool and run the following command in order to generate your pass. ./signpass -p YourOwnPass.pass. Of course, you'll have to replace the name of the pass with your own. When you run the command, you'll probably be asked to enter your computer password. The signpass tool asks your password in order to use the certificate you installed earlier in the Keychain. Enter the password to continue. If everything went correctly, there will be a newly created .pkpass file which is your actual pass. You can double-click that file to open it. By clicking the Add button, this pass will be synced to all your iOS devices using iCloud. You should know that at this point you still can't share your pass with others because the pkpass file and the optional VCF file don't exist yet on the URLs that you included in the pass.json file. You'll do that in the next section. If you experienced any error, you probably made a syntax error to the pass.json file. Please check the pass.json file carefully and give it another try. If you can't fix the error, please let me know by leaving a comment in the comments section below and I'll try to help as much as I can. During the development of the pass, you'll probably make a few changes in order to achieve the perfect result. After each change, you'll have to run the above command again to generate an updated pass. You just double-click the updated pass and click the update button. The updated pass will be synced to all your devices but it will take some time in order to do so. This is normal. When you are satisfied with the result you achieved you can move to the next section.

Upload the pass to S3

You now have your final .pkpass file and you're ready to upload it to S3. Head to your Amazon S3 bucket and choose the option to upload a new file. Choose the .pkpass file and go to the second step. At the Manage public permissions section, choose the option that gives public read access. Otherwise, the pass won't be available for download from anyone else. Go to the third step which is about the file properties. There is a very important addition that we have to make here. Under the Header section, choose Content-Type. As value add application/vnd.apple.pkpass. Without this, you won't be able to install the pass to the Wallet app. Note that if you make any changes to your pass later on, you'll have to delete the pkpass file you uploaded to Amazon S3 and upload the updated one by following the steps in this section again. When you successfully upload the file, click on it and check that the URL is the same with the one you supplied in the pass.json file earlier on. If not, you won't be able to share your pass with anyone else. You'll have to supply the correct URL in the pass.json file, generate the pass once more, delete the pass you already uploaded to S3 and re-upload the newly generated pass.
Screen-Shot-2018-04-09-at-5.08.29-PM
Screen-Shot-2018-04-09-at-5.09.21-PM

Generate the VCF file

If you decided to include a VCF file to your business card, you're in luck, because the process is really easy. Open the Contacts app on your Mac and create a new contact with your own personal details. After that, right-click on your contact from the contact list and choose the Export vCard option. Export the vCard in any location you want on your computer. In the Pass implementation and customization section, you chose a name for your VCF file in order to generate the URL for that file. Go ahead and rename the exported vCard using the name you chose earlier. You are now ready to upload the file to Amazon S3. Follow the same steps as above in order to do so. The only difference is that you don't need to add the Content-Type in the third step.

Conclusion

Congratulations! If you successfully followed this tutorial, you now have a very cool and tech-savvy business card to share with the world!

For further reading, you can take a look at the Wallet Developer Guide in order to learn more about passes and what you can achieve with them. For example, you could add the functionality needed in order to update your pass remotely. This means that anyone who already has your business card will always have the latest version even if you make changes later on. You could also provide relevancy information using iBeacons, so a message would appear to the device of anyone who has your pass. These advanced functionalities are beyond the scope of this tutorial, though.

If you have any questions or you experienced any errors, feel free to let me know in comments section below. In any case, I'd love to hear your feedback and see what you managed to create.