Skip to content

Design Document: Apple Wallet Ticket Generation

kvn edited this page Sep 21, 2022 · 1 revision

References:

SocialPass allows users to generate tickets if they are able to prove ownership of certain required digital assets (such as NFTs) set by the event organizers. One useful feature after proving ownership and generating the ticket is saving the ticket to the user’s Apple Wallet. This page is meant to document the required interactions with the Apple in order to allow users to accomplish the above stated goal

Overview

Steps must be followed to generate and deliver Apple Wallet Passes, all steps are related to creating .pkpass files. These .pkpass files are zipped files with the information needed to build and distribute apple wallet passes. the steps are as follows:

  1. Generate apple certificates and pass type identifiers.
  2. Install passbook Python package.
  3. Generate a .pkpass file.
  4. Save the pass in the user's Apple Wallet.

The first step is to create the certificates needed to generate Apple Wallet Passes. The second is to install a Python package that allows us to create .pkpass files. The third step is to build the .pkpass file using simple Python code. The last step is to hand over the pass.

Steps in detail

The above steps are documented in detail in the following sections.

Generate apple certificates

To generate the certificates and the pass type identifier, you need a Mac PC with access to Keychain.

  1. Create a pass type identifier in the Certificates.
    1. Click on this link, select Identifiers and then click Add (+).
    2. On the next screen, choose Pass Type IDs and click Continue
    3. Enter a description and the reverse DNS string to create the identifier
    4. Click Register
  2. Generate a signing certificate (Detailed steps here).
    1. Select Certificates, and then click Add (+).
    2. On the next screen, choose Pass Type ID Certificate and click Continue.
    3. Enter a name for the certificate and select the pass type ID from the dropdown menu.
    4. Click continue and upload the certificate signing request (CSR).
    5. Download the certificate file from your pass type identifier
  3. Download the pass type ID certificate
    1. Double-click the pass type ID certificate file you downloaded to install it to your keychain
  4. Export the pass certificate as a p12 file:
    1. Open Keychain Access
    2. Locate the pass certificate -- it should be under the login keychain, Certificates category.
    3. Right-click the pass and choose Export
    4. Make sure the File Format is set to Personal Information Exchange (.p12) and export to a convenient location.
  5. Generate the necessary certificate and key .pem files
    1. Open Terminal and navigate to the folder where you exported the p12 file.
    2. Generate the pass pem file: openssl pkcs12 -in "Certificates.p12" -clcerts -nokeys -out certificate.pem
    3. Generate the key pem file: Note you must set a password for the key pem file or you'll get errors when attempting to generate the pkpass file. openssl pkcs12 -in "Certificates.p12" -nocerts -out key.pem
  6. Generate WWDR certificate as .pem file
    1. Generate the .pem file for the Apple WWDR certificate (available from http://developer.apple.com/certificationauthority/AppleWWDRCA.cer ). When clicked it will be downloaded a .cer file, following the same steps as above (using Keychain) it will be able to export the WWRD file as a .pem file
  7. Move all the .pem files into your project

Install passbook package fork

passbook is a Python package that allows you to generate .pkpass files containing needed information for generating a pass for an apple wallet. NFTY will fork https://github.com/shivaRamdeen/passbook and modify the necessary files to make the passbook package work the way we need it.

Install the package in Python using the following command:

pip install git+https://github.com/shivaRamdeen/passbook.git

Once that’s done, it is possible to generate .pkpass files.

Generate a .pkpass file

The code snippet below creates a .pkpass file ready to be uploaded: NOTE: the code snippet is regarding passbook package fork.

#!/usr/bin/env python
import uuid
from passbook.models import Barcode, BarcodeFormat, EventTicket, Location, Pass
from django.conf import settings


def generate_pass(ticket: Ticket):
    """
    generate .pkpass file
    """

    event = ticket.event

    eventInfo = EventTicket()
    eventInfo.addPrimaryField("name", event.title, "EVENT")
    eventInfo.addSecondaryField("where", event.location, "WHERE")

    # QR code
    barcode = Barcode(message=ticket.embed_code, format=BarcodeFormat.QR)

    # EVENT LOCATION
    location = None
    if event.lat and event.long:
        location = Location(latitude=event.lat, longitude=event.long)

    # print(location.json_dict())

    passfile = Pass(
        passInformation=eventInfo,
        passTypeIdentifier=settings.APPLE_WALLET_PASS_TYPE_ID,
        teamIdentifier=settings.APPLE_WALLET_TEAM_ID,
        organizationName="Hashed Inc.",
        backgroundColor="rgb(239,124,78)",
        foregroundColor="rgb(255,255,255)",
        labelColor="rgb(0,0,0)",
        serialNumber=ticket.public_id,
        description=event.description,
        barcode=barcode,
        locations=[location] if location else None,
    )

    # Including the icon and logo is necessary for the passbook to be valid.
    passfile.addFile("icon.png", open("socialpass-white.png", "rb"))
    passfile.addFile("logo.png", open("socialpass-white.png", "rb"))

    # generate ticket
    passfile.create(
        settings.APPLE_WALLET_CERTIFICATE,
        settings.APPLE_WALLET_KEY,
        settings.APPLE_WALLET_WWDR_CERTIFICATE,
        settings.APPLE_WALLET_PASSWORD,
        f"Event-{ticket.public_id}.pkpass",
    )

Changing pass TypeIdentifier, teamIdentifier and the certificates variables names, is possible to build a valid .pkpass file. The .pkpass file is a compressed file with a manifest.json, icons.png, pass.json and signatures. All these files are required to generate a valid Apple Wallet Pass.

Save the pass in user’s Apple Wallet

To save the pass to Apple Wallet, simply send a pass as an attachment in an email, click on the .pkpass file, and click add to Apple Wallet.

Example