SmartPass links offer a simple yet powerful way to distribute mobile passes for Apple Wallet and Google Pay, bypassing the need for complex API integrations. This feature allows you to pre-generate unique URLs containing encrypted data at no extra cost, making it ideal for large-scale distributions, targeted campaigns, and situations where real-time API calls aren't feasible.
What are SmartPass links?
SmartPass links are unique URLs containing encrypted data that, when clicked, generate a personalized mobile pass. Crucially, these links are generated before a pass record exists in your PassKit account. This means you can create an unlimited number of links without impacting your pass volume subscription—SmartPass link generation is completely free. Think of SmartPass as a "pay-as-you-go" system for pass creation. The pass is only created when the link is clicked.
How SmartPass Links Work
Link Generation
After designing your pass template, you generate SmartPass links using one of three methods: CSV upload, API, or command-line tool. PassKit then emails you a CSV file. This file contains the data you provided and a new column with the corresponding unique SmartPass URL for each record.
Secure Storage
PassKit does not store these SmartPass links. You are responsible for securely storing this CSV file, as it contains all your generated SmartPass links.
You are responsible for securely storing SmartPass Links
Why PassKit Doesn't Store SmartPass Links (and Why It's a Good Thing)
The key to understanding this lies in how SmartPass links work and the importance of security. While it might seem counterintuitive that PassKit doesn't store the links, it's a deliberate design choice that enhances both security and flexibility.
Here's the breakdown:
Encryption: The SmartPass links themselves contain all the personalized data needed to create the pass (e.g., name, membership number, etc.). However, this data is encrypted within the URL. Think of it like a locked box.
The Key: PassKit does store the "key" to unlock and decrypt the data within the SmartPass link. This key is essential for PassKit to create the pass when the link is clicked.
Decentralized Storage: The actual SmartPass Links (the locked boxes) are not stored by PassKit. Instead, they are given to you in the CSV file. This decentralized storage model offers several advantages:
Scalability: Imagine PassKit storing billions of individual SmartPass links. This would be a massive storage burden and would incur costs for PassKit and for you.
Flexibility: You have complete control over how you distribute and manage these links. You can use your own email system, CRM, or any other method that suits your needs.
Security (Enhanced): While the links are encrypted, distributing the storage of the links means that a compromise of PassKit's servers would not give access to the links themselves. It's a form of defense in depth.
On-Demand Pass Creation: Because PassKit has the decryption key, it doesn't need to store the link. When someone clicks a SmartPass link, that's when PassKit uses the key to decrypt the data within the link and create the pass. This on-demand approach is efficient and cost-effective.
In simple terms: PassKit gives you the instructions (the encrypted link) and the key (the ability to decrypt it). You are responsible for keeping the instructions safe and giving them to the right people. PassKit only uses the key when someone follows the instructions (clicks the link). This way, PassKit doesn't need to keep track of all the individual instructions.
This explanation should help clarify why PassKit doesn't store the SmartPass links themselves and why this design is beneficial for both PassKit and you. It emphasizes the encryption aspect and the on-demand nature of pass creation, which are the core concepts that often cause confusion.
Distribution
You distribute the appropriate SmartPass link to each intended recipient (e.g., via email, SMS, QR code).
Pass Creation
When a recipient clicks their unique SmartPass link, the encrypted data within the link is used to generate their personalized mobile pass, which they can then add to their Apple Wallet or Google Wallet.
Encrypted vs. Hashed Links
SmartPass links are available in two formats:
Encrypted Links
These links contain data that is fully encrypted and only decryptable by PassKit's systems. This offers the highest level of security, as the underlying data is not visible. We strongly recommend using encrypted links whenever possible.
Hashed Links
These links include a digital signature that verifies the integrity of the data. While they provide some security, they are less secure than encrypted links as the data itself is not encrypted.
Generating SmartPass Links
PassKit offers several flexible methods for generating SmartPass links.
CSV Upload
Ideal for bulk generation. Prepare a CSV file containing recipient data (e.g., name, email, membership number) and upload it to PassKit.
API
For programmatic generation and integration with your systems.
Command-Line Tool
Useful for developers and advanced users.
Important Considerations
SmartPass links are generated based on the current state of your pass template. This means that any changes you make to the template after generating SmartPass links can lead to problems.
The Problem
If you generate SmartPass links when your template only includes "first name," and you later add "last name" or "mobile number" to the template, the existing SmartPass links will not contain this new information. When someone clicks an older SmartPass link (generated before the change), the pass creation process will encounter one of these scenarios:
Missing Data: The pass may be created, but the new fields (last name, mobile number) will be blank because the SmartPass link doesn't contain that data.
Pass Creation Failure: In some cases, the pass creation might fail entirely because the template now requires fields that are not present in the SmartPass link's data.
Best Practices to Avoid Issues
Plan Your Template: Carefully plan your pass template before generating SmartPass links. Ensure you include all the necessary fields you anticipate needing.
Template Versioning: If you need to make changes to your template after generating links, consider creating a new version of the template. This way, existing links will continue to work based on the original template, and you can generate new links for the updated template.
Regenerate Links: If you absolutely must change the template and have already distributed links, the safest approach is to regenerate all SmartPass links after making the template change. This ensures all links are consistent with the current template.
Data Mapping (Advanced): If you are using a CRM or other system to manage your data, ensure that the data fields you are sending in the CSV or via the API matches the fields in your Pass template. If you have a field in your CRM that is not in the template, then the data cannot be displayed on the pass.
Summary
Be mindful of the timing of template changes relative to SmartPass link generation. Always prioritize planning and consider regenerating links if you modify your template after distribution. This will prevent data mismatches and ensure a smooth user experience.
Key takeaway
SmartPass links streamline mobile pass distribution, offering a cost-effective and efficient way to deliver personalized passes. Remember that you are responsible for the secure storage and distribution of the generated SmartPass links. The actual pass creation is deferred until the link is clicked, ensuring you only pay for passes when a customer clicks on a SmartPass link.