Skip to main content

PassKit SmartPass links

How to generate millions of personalised passes without using the PassKit API.

Paul Tomes avatar
Written by Paul Tomes
Updated today

Introduction

Ready to supercharge your SmartPass link creation? While the PassKit portal offers a convenient option for smaller CSV files, this article dives into the power and efficiency of our command-line tool. Learn how to leverage this robust method to generate encrypted SmartPass links at scale.

Requirements:

How to use

  • Download any of the pre-compiled executables from the bin folder for your Operating System (you may need to set the right system permissions to run it).

  • Get your Project URL: copy from Distribution >> SmartPass Settings in PassKit Portal

  • Get your Project Encryption Key: copy from Distribution >> SmartPass Settings in PassKit IO Portal

  • Create your CSV file (you can find samples in the examples folder; just delete the columns that you don't need).

  • Ensure the CSV file contains the correct headers (otherwise we won't be able to map it to the correct pass field).

  • Run the tool from the command-line: ./encrypted-link-generator-osx -in in.csv -out out.csv -url https://pskt.io/c/wrsynr -key 11122233344455590000aaabbbccc(replace values with your own).

  • Open up out.csv, test and distribute your links.

Performance

The tool can generate 1M pass links in under 10 seconds.

Command Parameters

  • -in: the path to your CSV file.

  • -out: the file that the tool outputs to (if the file exists it will be overwritten).

  • -url: your Project URL: copy from Distribution >> SmartPass Settings in PassKit IO Portal.

  • -key: your Project encryption key: copy from Distribution >> SmartPass Settings in PassKit IO Portal.

Available Field Names

The following fields are currently supported. These are the field names to use as headers in your CSV. For additional details check the documentation.

You only need to provide the fields that are applicable to your project. All fields are optional, unless set as required in project.

Generic Fields

  • universal.optIn: true -or false.

  • universal.expiryDate: expiry date in valid ISO-8601 format (2020-06-22T00:00:00-05:00).

Person Fields

  • person.surname: surname / family name.

  • person.forename: forename / given name.

  • person.otherNames: other names.

  • person.salutation: salutation or title.

  • person.suffix: suffix. For multiple suffixes, separate with spaces.

  • person.displayName: if required, a string representing the user's preferred designation.

  • person.gender: gender, as per government issued id. Possible values: 0 (Not known), 1 (Male) or 2 (Female)

  • person.dateOfBirth: valid date in yyyy-mm-dd format (1980-06-22).

  • person.emailAddress: valid email address.

  • person.mobileNumber: valid telephone number.

  • person.externalId: external ID for the person. Used for some of the native PassKit integrations.

Member Specific Fields

  • members.tier.id: the tier ID to enrol the member into.

  • members.member.externalId: sets the 'external' ID of the member (i.e. the member ID as it's being used in your system). If provided then this can be used to query & update members. This field will be treated as unique within the program, and cannot be updated at a later stage.

  • members.member.points: primary points balance of the member.

  • members.member.tierPoints: tier points for the member.

  • members.member.secondaryPoints: secondary points balance of the member.

  • members.member.groupingIdentifier: used to group members under the same membership (i.e. couple).

  • members.member.profileImage: for Membership Programs that require a profile image on the pass. Can either be an image URL or base64 image string.

Coupon Specific Fields

  • singleUseCoupons.coupon.externalId: sets the 'external' ID of the coupon (i.e. the unique coupon code as it's being used in your system). If provided then this can be used to query & update coupon. This field will be treated as unique within the campaign, and cannot be updated at a later stage.

  • singleUseCoupons.coupon.sku: sku of the coupon. Can be used in the barcode by setting ${singleUseCoupons.coupon.sku} in the Pass Template Design barcode settings.

Meta Fields

  • meta.*: any custom fields you have defined in your project.

UTM Tracking Parameters

  • utm_source: used to identify where the request is coming from. Defaults to Unknown.

  • utm_medium: used to identify a medium such as email, app, or cost-per-click advertising.

  • utm_name: used for keyword analysis. Use campaign to identify a specific product promotion or strategic campaign.

  • utm_term: used for paid search. Use term to note the keywords for the ad that led to the pass.

  • utm_content: used for A/B testing and content-targeted ads. Use content to differentiate ads or links that point to the same URL.

Location Parameters

Used to embed locations on a pass level. Each unique pass can have upto 10 different locations embedded in it.

LOCATION_NUMBER needs to be 1-10:

  • location[LOCATION_NUMBER].lat: a valid float for the location latitude, for example 51.507351.

  • location[LOCATION_NUMBER].lon: a valid float for the location longitude, for example 1.507351.

  • location[LOCATION_NUMBER].lockScreenMessage: the message to trigger on the lock-screen when someone is within range of the lat/lon.

  • location[LOCATION_NUMBER].alt: a valid integer for the location altitude, for example 647 (optional).

  • location[LOCATION_NUMBER].name: an internal name for the location in the PassKit database (optional).

  • location[LOCATION_NUMBER].position: the position of the location in the locations array (optional).

When using the above, lat, lon & lock-screen message are mandatory: all 3 need to be provided for each location.

Beacon Parameters

Used to embed beacons on a pass level (Apple Wallet only). Each unique pass can have upto 10 different beacons embedded in it.

BEACON_NUMBER needs to be 1-10:

  • beacon[BEACON_NUMBER].uuid: a valid UUID string for the beacon.

  • beacon[BEACON_NUMBER].major: a valid integer for beacon major. Range between 0-65535.

  • beacon[BEACON_NUMBER].minor: a valid integer for beacon minor. Range between 0-65535.

  • beacon[BEACON_NUMBER].lockScreenMessage: the message to trigger on the lock-screen when someone is within range of the beacon.

  • beacon[BEACON_NUMBER].name: an internal name for the beacon in the PassKit database (optional).

  • beacon[BEACON_NUMBER].position: the position of the beacon in the beacons array (optional).

When using the above, uuid, major, minor & lock-screen message are mandatory: all 4 need to be provided for each beacon.

Color Parameters

Used to override colours on a pass level.

  • colors.backgroundColor: pass background color.

  • colors.labelColor: label text color (Apple Wallet only).

  • colors.textColor: value text color (Apple Wallet only).

  • colors.stripColor: text over Strip Image color (Apple Wallet only).

Image Parameters

Used to override images on a pass level. Need to contain a valid [https://docs.passkit.io/common/images/#operation/createImages](PassKit 22 character image ID).

  • images.icon

  • images.logo

  • images.appleLogo

  • images.hero

  • images.eventStrip

  • images.strip

  • images.thumbnail

  • images.background

  • images.footer

  • images.security

  • images.thumbnail

  • images.privilige

  • images.airlineAlliance

  • images.personalization

  • images.banner

  • images.message

  • images.profile

  • images.appImage

Examples

Example CSV files with all supported field names are found in the examples folder in this repo; just delete the columns that you don't need.

Access the Encrypted SmartPass Link Generator

Related Articles
PassReader: The PassKit Scanning App
Introduction to SmartPass links
Uploading your Coupon SmartPass link CSV
Saving SmartPass links
Did this answer your question?