Add private images to wallet passes

You can add publicly accessible images to a pass by upload when designing your template in the dashboard or by providing a URL when creating or updating a pass through the API. For images that should not be exposed publicly, such as a member’s profile photo, a business card, or other personal content, add them as private images. Private images can only be viewed as part of the pass they’re used in, not from a public URL.

How private images work

Private images use an API-only workflow:

1. Upload — Upload the raw image binary, and Airship returns its storage path.
2. Reference — Use that path as an image field’s value when you create or update a pass.

The images must be in PNG format, and when uploading, you must specify a type, which determines how the image is resized. Each platform allows different types for specific uses. See the imageType parameter for the resized dimensions.

Google Wallet

Private images can only be used for a Google Wallet pass’s main image, set on the imageModulesData field. The field requires a private image, and using the private path on any other Google image field causes the image to be dropped. Use the type mainImage in your upload call. It’s resized to 180×180 pixels.

Airship uses Google’s Secure Private Images  feature to render the image.

Apple Wallet

Private images are not required for Apple Wallet passes, but they’re recommended when an image is personal to the pass holder and shouldn’t be accessible from a public URL. If the image doesn’t need to be private, you can reference it with a public URL instead. Airship bundles a private image directly into the pass file.

You can use an Apple private image in any image field, but it’s resized upon upload for the type you set:

• thumbnail_image is 180×180 pixels
• strip_image is 624×246 pixels

Make sure the field you use it in matches the type you picked when uploading, or the image may not render at the correct size.

Multi-use

Reuse an uploaded image across multiple passes in the same project instead of uploading it again for each one.

Google’s own private image reference only works for a single pass, but Airship generates a new one for each pass automatically, so you only need to upload the image once.

Image data retention

Airship automatically deletes a private image 13 months after upload, or 6 months after last access, whichever comes first. The following timestamps are used to calculate this period:

• Upload date — The day you call the upload endpoint
• Last access date — The day a pass is created via the API or a user opens an Adaptive Link that generates one

Upload a private image

To upload an image, send a POST request to https://wallet-api.urbanairship.com/v1/images/projects/{projectId}/{imageNameIdentifier} with the raw binary PNG data as the request body. For supported authorization types and the full request and response definitions, see the Upload image endpoint in the Wallet API reference.

POST /v1/images/projects/12345/test_image.png?imageType=mainImage HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: image/png
Api-Revision: 1.2

...

A successful upload returns 200 OK with metadata about the stored image and the path you’ll use to reference the image in a pass.

{
    "path": "passtools_prod/1/images/587ac4e3d188b0fcd4f05038d8814fefd82ac834_test_image.png",
    "source": "uploaded",
    "imageType": "mainImage",
    "width": 180,
    "height": 180
}

Use a private image in a pass

Use the path from the upload response as the value for an image field when you create or update a pass. For Google Wallet, set it on the image module field imageModulesData. For Apple Wallet, set it on the thumbnail_image or strip_image field.

The following example shows the imageModulesData field referencing a private image on a Google Wallet pass. Include your pass’s other fields as usual.

{
  "fields": {
    "imageModulesData": {
      "fieldType": "imageModulesData",
      "label": "Full-Width Image",
      "value": "passtools_prod/1/images/587ac4e3d188b0fcd4f05038d8814fefd82ac834_test_image.png"
    }
  }
}