Skip to main content

Loyalty assets — formats, sizes, and best practices

Every visual asset surfaced by a Keyban loyalty programme maps to a specific field in the Loyalty settings or in Apple / Google Wallet configuration. The constraints below are the enforced ones — they come straight from the Zod schemas the backend validates against. Stick to them and the upload UI will not push back; deviate and the asset will either be rejected at save time or look wrong on the target surface.

The five surfaces at a glance​

A loyalty programme spreads its visual identity over five distinct surfaces. Each one has its own field set, its own dimensions and its own forgiveness budget — what works for the Google hero will look broken on the Apple strip.

  1. Web appLogo + background, full-screen customer view.
  2. Reward tiersOne card-art per tier (WEBP preferred).
  3. Google WalletRound logo, hero banner, fallback colour.
  4. Loyalty programmeOne configuration in Admin → Application → Loyalty → Settings.
  5. OnboardingWelcome background + 3–5 carousel slides.
  6. Apple WalletLogo, icon, strip image, fallback colours.
A single loyalty programme drives five visual surfaces: the web app shell, the onboarding flow, the reward tier cards, the Apple Wallet pass and the Google Wallet pass. Each surface consumes its own subset of asset URLs.
How assets get there

All asset URLs are configured from Admin → Application → Loyalty → Settings. The upload widget on each field uploads the file to Keyban-managed storage and writes the resulting public URL into the corresponding schema field for you. You can also paste an external HTTPS URL if you'd rather keep the master copy on your own CDN — the schema only validates that the value resolves to a valid HTTPS URL.

Aspect ratios at a glance​

The five surfaces share three families of aspect ratios. Eyeballing them side by side makes it obvious why a single 1920 × 1080 export won't satisfy the Apple strip or the Google hero.

1:1 — App / Google logos
16:9 — Backgrounds, tier art
4:3 — Carousel slides
~3.7:1 — Apple strip (624×168)
3:1 — Google hero (1032×336)
~3.2:1 — Apple logo (160×50)

Where each asset shows up​

AssetSurfaceSchema field
App logoLoyalty web app, headerapplicationTheme.logoUrl
App backgroundLoyalty web app, behind cardsapplicationTheme.bgImageUrl
Onboarding backgroundFirst-launch welcome screenloyaltySettings.app.onboarding.bgImageUrl
Onboarding carouselFirst-launch slidesloyaltySettings.app.onboarding.carousel.images[]
Reward tier card artTier list and tier-detail screensloyaltyRewardTier.bgImageUrl
Apple Wallet pass logoTop of pass, header striployaltySettings.appleWallet.logoUrl
Apple Wallet pass iconNotification thumbnail, lock screenloyaltySettings.appleWallet.iconUrl
Apple Wallet strip imageBackground under the logoloyaltySettings.appleWallet.bgImageUrl
Google Wallet logoRound badge on the card faceloyaltySettings.googleWallet.logoUrl
Google Wallet hero imageBanner at the top of the cardloyaltySettings.googleWallet.bgImageUrl

Loyalty web application​

Two images plus a colour palette set the tone for the whole web app.

FieldFormatDimensionsMax sizeNotes
applicationTheme.logoUrlPNG512 × 512 px (square)500 KBReadable on light and dark backgrounds
applicationTheme.bgImageUrlPNG1920 × 1080 px (16:9)1 MBSubtle — text overlays on top
applicationTheme.primaryColorHEX (#RRGGBB)——Used for primary CTAs
applicationTheme.secondaryColorHEX (#RRGGBB)——Used for accents

Onboarding​

The first-launch flow is opt-in (only rendered when the carousel is configured) and lets you set the tone before the user sees their first points balance.

FieldFormatDimensionsMax size
onboarding.bgImageUrlPNG1920 × 1080 px1 MB
onboarding.carousel.images[].urlPNG800 × 600 px (4:3)300 KB

Each carousel slide also accepts an optional title and description. Plan for 3 to 5 slides — past five, conversion to « finish onboarding » drops noticeably.

Reward tier card art​

Each reward tier accepts a single background image rendered as the tier card's hero.

FieldFormatDimensionsMax size
loyaltyRewardTier.bgImageUrlWEBP preferred, PNG accepted1920 × 1080 px1 MB

Prefer WEBP here — the tier list often shows three or more cards on a single screen, and PNGs at 1920 × 1080 add up fast on mobile. WEBP at quality 80 typically lands at 30–40 % of the PNG file size with no visible loss on the gradient backgrounds tier art usually relies on.

Apple Wallet pass​

Apple's pkpass format is the strictest of the three surfaces — every field must be PNG, and Apple enforces three resolution variants (1x, 2x, 3x) for retina rendering.

FieldFormatDimensionsMax size
appleWallet.logoUrlPNG160 × 50 (1x), 320 × 100 (2x), 480 × 150 (3x)100 KB per variant

Transparent background, high contrast, no fine lines — the strip is narrow and any decoration smaller than ~24 px is illegible.

Icon​

FieldFormatDimensionsMax size
appleWallet.iconUrlPNG29 × 29 (1x), 58 × 58 (2x), 87 × 87 (3x)100 KB per variant

The icon is what shows up in the Wallet app's pass picker and on the lock-screen notification. Treat it as a favicon — your brand mark, not a wordmark.

Strip background​

FieldFormatDimensionsMax size
appleWallet.bgImageUrlPNG624 × 168 (2x), 936 × 252 (3x)100 KB per variant

When omitted, Apple falls back to a flat appleWallet.bgColor. Use the flat-colour fallback for high-volume programmes — it ships smaller and renders identically across iOS versions.

Colours​

All colours below are HEX (#RRGGBB).

FieldRole
appleWallet.bgColorStrip fallback when no bgImageUrl is set
appleWallet.labelColorField labels (« Balance », « Member ID »)
appleWallet.fgColorDynamic field values (the balance number itself)

fgColor and bgColor need a contrast ratio of at least 4.5:1 to pass WCAG AA — pick a dark fgColor against a light strip, or vice versa. Apple does not enforce this; your accessibility audit will.

Google Wallet pass​

Google's loyalty class accepts JPEG too, but the schema only allows PNG — it's the safer common subset across Android versions.

Logo​

FieldFormatDimensionsMax size
googleWallet.logoUrlPNG≥ 660 × 660 px (square)500 KB

Google applies a circular mask to the logo — anything in the outer 15 % is clipped. Frame the brand mark inside a centred circle of diameter 561 px (660 × 0.85) and you are safe.

safe zone

660 × 660 — keep marks inside the inner circle

Hero image​

FieldFormatDimensionsMax size
googleWallet.bgImageUrlPNG1032 × 336 px (3:1)5 MB

The hero is the largest creative surface in the entire programme. The 5 MB ceiling is the schema limit — practical mobile cellular delivery calls for keeping it under 800 KB.

Colour fallback and texts​

FieldRole
googleWallet.bgColorCard fallback when no bgImageUrl is set, HEX
googleWallet.titleDisplay name in the Google Wallet pass list
googleWallet.headerHeader text on the card face
googleWallet.detailsHeaderHeading inside the « Details » view
googleWallet.detailsBodyBody inside the « Details » view, multi-line

Best practices​

  • One source of truth per asset. Host the master file (your highest resolution / vector source) on your CDN, then derive every variant from it. Manual exports drift fast.
  • Cache-bust on update. When you replace an asset, append a versioned query string (?v=2025-05-06) — Apple Wallet caches aggressively and an unversioned overwrite can take hours to surface.
  • Keep brand colour parity across surfaces. Apple bgColor, Google bgColor, and applicationTheme.primaryColor should agree to within a few HEX points — disagreement is the most common audit-time issue.
  • Test against both 1x and 3x Apple variants. Apple selects the variant by device DPI, not by user setting; an asset that looks great at 3x may pixelate on an SE-generation iPhone.
  • Validate the Google logo safe zone visually. Drop a 561 px centred circle on the canvas before exporting — anything outside is invisible to the user.
  • Provide an alt copy for accessibility. The header and detailsBody are read by screen readers; treat them like UI copy, not decoration.

Delivery checklist for a creative team​

When handing off a kit to engineering, package the following per programme:

  • All Apple variants at 1x, 2x, 3x for logo, icon, bgImageUrl (9 files total).
  • Google logoUrl (single file ≥ 660 × 660) and bgImageUrl (1032 × 336).
  • App logoUrl and bgImageUrl (one each).
  • Onboarding bgImageUrl and 3–5 carousel slides.
  • One reward-tier bgImageUrl per planned tier (WEBP).
  • A colors.json (or equivalent) with HEX values for applicationTheme.{primaryColor, secondaryColor}, appleWallet.{bgColor, labelColor, fgColor}, googleWallet.bgColor.
  • Optionally, a texts.json with googleWallet.{title, header, detailsHeader, detailsBody} and appleWallet.title so the operator can paste them directly into the Admin Console.

Source files (.psd, .ai, .fig) help future iterations but are not required by Keyban — only the public URLs are.