Google Wallet for a loyalty card
Google Wallet builds the card differently from Apple, and if you design only with the iPhone in mind, it looks wrong on Android. Here are both.
The fundamental difference from Apple
Before getting to the sizes, it helps to understand why you can’t just “export the same thing” to both systems:
| Apple Wallet | Google Wallet | |
|---|---|---|
| What the card is | A signed .pkpass file downloaded to the phone | An object that lives on Google’s servers; the phone receives a link |
| The images | Go inside the file | Are linked by URL: they must be published on your server |
| To update it | You send a notification and the phone downloads the new pass | You update the object through Google’s API |
| Prior permission | Apple certificate, paid yearly | Issuer account and Google review |
The two images
A Google Wallet loyalty card shows two images:
| Image | Size | Where it appears | What to use |
|---|---|---|---|
Programme logoprogramLogo |
660 × 660 px minimum, 1:1 |
At the top, next to the name, on the card detail and in the list. Cropped into a circle. | Your symbol, centred, on a square with a full-bleed background. |
Header imageheroImage |
1032 × 812 px recommended |
A band on the front of the card. Displayed at 100% of the width. | On a stamp card, the stamp slots. Otherwise, a photo of your venue. |
Both as PNG. And with the logo there’s a detail Google actually puts in writing, which ruins half of the ones that get uploaded: leave a 15% safe margin all round. Anything touching that edge gets eaten by the circular crop.
heroImage on Google. It works; it just isn’t
the ratio they recommend for a purpose-designed hero. If you’re going to look after both separately,
this is the one to redo.
The logo is cropped into a circle (and that’s where your wordmark dies)
This is the detail that ruins the most designs. On Apple, the logo sits in a wide box and your long wordmark fits in full. On Google, it’s cropped round.
If you send the same file to both, on Android your wordmark loses its ends and is left with the three letters in the middle. The fix isn’t technical, it’s design:
- Prepare a square version of the logo just for Google.
- Centre it and give it breathing room: anything touching the edge of the square is lost in the crop.
- If your brand is a long piece of text, use the symbol or the initial, not the full wordmark.
The visible fields
Google lays out the card differently: there are no “rows” as on Apple, but fields with their own names.
| Field | What it is | What to put there |
|---|---|---|
issuerName | Who issues it | The name of the club, not just the business |
programName | The pass title | The customer’s name, if you have it |
accountName | The holder | The member’s first name and surname |
loyaltyPoints | The big counter | “7/10” on a stamp card, the balance if you use points |
textModulesData | Free text blocks | Tier, next reward, short terms |
hexBackgroundColor | The card colour | A hex #rrggbb. If you leave it empty, it’s taken from the dominant colour of your header (and failing that, from the logo) |
hexBackgroundColor in
#rrggbb format, and if you leave it empty the system uses the dominant colour of your
header image; if there’s no header either, the dominant colour of your logo. A photo
with lots of brown leaves you with a brown card. Set it yourself.
The scan code
The card carries a code for your team to scan. The usual choice, and the one that works best at a counter, is a QR code: any phone can read it, it copes with a dirty or dim screen, and you don’t have to buy a scanner.
A small detail with consequences: the text under the code. If you leave the member ID there, the customer sees a jumble of characters under their card. It’s better to leave it empty or put something that means something to them.
Messages
To notify a customer on Android, you add a message to their card. It works differently from Apple, where the notification is the update of the pass itself.
This has two consequences to keep in mind:
- The same notice looks different on each system. Always test on an iPhone and an Android before sending anything to your whole base.
- Messages pile up on the card. They aren’t notifications that disappear: they stay there. Sending one a week turns the card into a noticeboard of old announcements.
On what to write and when, we have a whole guide: pass notifications.
Google’s review
Unlike Apple — where once you have the certificate you can start issuing — in Google Wallet pass classes go through a review before they can be issued at scale. It isn’t instant, so factor it into your timelines: if you promise a client their card will be ready “tomorrow”, make that tomorrow on iPhone and a few days on Android.
Frequently asked questions
Can I have the same loyalty card on iPhone and Android?
Yes, but it is not the same file. Apple uses a .pkpass package that gets downloaded; Google Wallet uses an object that lives on Google’s servers and is linked to. You have to build both, and the design does not carry over as it is.
What images appear on a Google Wallet card?
Two: the programme logo (programLogo), at least 660 × 660 px and square, shown at the top cropped into a circle; and the header image (heroImage), which Google recommends at 1032 × 812 px and displays at 100% of the card’s width. Both as PNG.
Why does my logo look cut off on Android?
Because Google masks it into a circle. A wide logo loses its ends. You need to upload a square version of at least 660 × 660 px, centred and with a 15% safe margin all round: anything touching the edge gets eaten by the crop.
How do you notify a customer in Google Wallet?
You add a message to the card object. This differs from Apple, where the notification is the update of the pass itself. That is why the same notice can look different on each phone, and you need to test it on both.
If you’re coming from Apple or heading there, the size table is in Apple Wallet pass sizes.