Tracking Google Wallet Pass Usage with API Callbacks

Key Concepts

• Google Wallet API callbacks
• HTTPS endpoint setup
• Digital signature verification using Google Tink library
• Pass class and object definitions
• Event types: SAVE and DELETE
• Nonce for deduplication of messages
• Google Cloud Run for deployment

1. Introduction

The Google Wallet live stream discusses how to track Google Wallet pass usage using API callbacks. The speaker is live from San Francisco, California, where the Google Wallet team is having an in-person meeting. The session covers setting up API callbacks to receive notifications when users add or remove passes from their Google Wallets.

2. Google Wallet Developer Documentation

• The canonical source of information is the Google Wallet developer website: developers.google.com/wallet.
• The "Events" tab lists past and upcoming live streams.
• Upcoming Google I/O event in May will feature announcements about new Google Wallet features.

3. API Callbacks Explained

• API callbacks allow developers to receive notifications when users add or remove passes.
• Requires setting up an HTTPS endpoint that accepts POST requests.
• The Google Wallet API sends a POST request to the specified endpoint with information about the pass event.
• This allows developers to gather analytics on pass usage.

4. Prerequisites and Setup

• An HTTPS endpoint is required.
• SSL certificate is necessary for the web server.
• The endpoint URL must be added to the pass class definition.
• Optional but recommended: Use the Google Tink library to verify the digital signature of the message.

5. Code Implementation (Java Example)

• A small Java project with a single endpoint (/callback) is used as an example.
• Any technology can be used (servlets, Spring, Java EE, Quarkus).
• The endpoint receives a POST request and processes it.
• The code prints the entire signed message and the decoded/verified message.
• The issue ID from the Google Wallet business console is required.
• The Tink library is used to verify the digital signature and extract the serialized JSON message.
• The code should be extended to update a database with pass addition/removal events.

6. Deployment to Google Cloud Run

• The Java application is containerized and published to the Google Cloud Artifact Registry.
• Google Cloud Run is used to deploy the container.
• Cloud Run allows scaling to zero, minimizing costs.
• The deployed endpoint URL is used in the pass class definition.

7. Creating a Pass using the Pass Builder

• The Pass Builder tool in the developer documentation is used to create a pass.
• An event ticket is created as an example.
• The class definition and object definition are copied from the Pass Builder.
• The class ID and event date/time are updated in the code.
• The callbackOptions property is added to the event ticket class definition.
• The URL of the deployed endpoint is set in the callbackOptions.

8. Testing the API Callback

• The "Add to Google Wallet" button is used to add the pass to the user's Google account.
• The pass appears in the Google Wallet app on the user's phone.
• The API callback is triggered, and the server logs show the received messages.
• The logs contain the signed message and the serialized message.

9. Analyzing the Callback Message

• The serialized message is a JSON object containing:
  • classId: The class ID of the pass.
  • objectId: The object ID of the pass.
  • eventType: SAVE (pass added) or DELETE (pass removed).
  • time: Timestamp in milliseconds.
  • count: Always 1.
  • nonce: Unique value for deduplication.
• The nonce property is crucial for preventing duplicate processing of messages.

10. Handling Pass Deletion

• Removing the pass from the Google Wallet app triggers a DELETE event.
• The callback message for the DELETE event contains the same classId and objectId but with eventType set to DELETE.

11. Security Considerations

• Verifying the digital signature is crucial to ensure the authenticity of the callback message.
• Without verification, the endpoint is vulnerable to attacks and counterfeit data.

12. Q&A

• Question: What kind of usage events can be tracked?
  • Answer: SAVE (pass added) and DELETE (pass removed).
• Question: What authorization is required apart from the digital signature?
  • Answer: No authorization is required for the callback endpoint itself. The Google Wallet API sends the POST request directly. Authorization is required during the onboarding process to create and issue passes.

13. Conclusion

The Google Wallet API callbacks provide a mechanism for developers to track pass usage. By setting up an HTTPS endpoint, verifying digital signatures, and processing the callback messages, developers can gain valuable insights into how users are interacting with their passes. The nonce property ensures that messages are not processed multiple times, maintaining data integrity.