> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xanhcard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kích thước ảnh cho thẻ

> Chuẩn bị đúng kích thước, tỉ lệ và định dạng ảnh cho thẻ Apple Wallet và Google Wallet để ảnh hiển thị sắc nét, không bị mờ hay cắt sai.

## Tổng quan

Apple Wallet và Google Wallet hiển thị ảnh theo cách khác nhau. Mỗi vị trí ảnh trên thẻ có một khung riêng. Hệ thống co giãn ảnh của bạn theo đúng tỉ lệ, lấp đầy khung, rồi cắt phần thừa.

Vì vậy, đúng tỉ lệ quan trọng hơn đúng từng pixel. Nếu ảnh sai tỉ lệ, ảnh sẽ bị cắt mất logo hoặc bị mờ.

Bạn nhập ảnh trong tab **Images** của trình chỉnh sửa mẫu thẻ:

* Apple Wallet: tab **Apple Wallet** → tab con **Images** (xem [Thiết kế cho Apple Wallet](/templates/apple-wallet))
* Google Wallet: tab **Google Wallet** → tab con **Images** (xem [Thiết kế cho Google Wallet](/templates/google-wallet))

<img src="https://mintcdn.com/xanhcard/oMUUuAnumaWwVH74/images/templates/06-apple-wallet-images.png?fit=max&auto=format&n=oMUUuAnumaWwVH74&q=85&s=06b5761ce28bf315902320ec0acf3923" alt="Tab Apple Wallet - Images" width="2796" height="2440" data-path="images/templates/06-apple-wallet-images.png" />

## Bảng kích thước chuẩn

### Apple Wallet

Apple dùng 3 mật độ điểm ảnh cho màn hình thường và Retina: `1x`, `@2x`, `@3x`. Bạn nên tải lên bản `@3x` (lớn nhất). XanhCard dùng bản đó để hiển thị trên mọi thiết bị.

| Vị trí                             | 1x         | @2x        | @3x (nên dùng) | Tỉ lệ              |
| ---------------------------------- | ---------- | ---------- | -------------- | ------------------ |
| Logo                               | 160×50 px  | 320×100 px | 480×150 px     | Rộng, khoảng 3,2:1 |
| Strip (thẻ thường)                 | 375×123 px | 750×246 px | 1125×369 px    | Rộng, khoảng 3:1   |
| Strip (vé sự kiện)                 | 375×98 px  | 750×196 px | 1125×294 px    | Rộng               |
| Strip (coupon, quà tặng)           | 375×144 px | 750×288 px | 1125×432 px    | Rộng               |
| Background (vé sự kiện có ảnh nền) | 180×220 px | —          | —              | Dọc                |
| Thumbnail                          | 90×90 px   | 180×180 px | 270×270 px     | Vuông 1:1          |
| Icon (màn hình khóa, thông báo)    | 29×29 px   | 58×58 px   | 87×87 px       | Vuông 1:1          |

<Note>
  Apple quy định khung logo tối đa là 160×50 điểm ảnh, nhưng bạn nên dùng ảnh hẹp hơn khung để hiển thị gọn. Ảnh strip và background có thể hiển thị hơi khác nhau tùy dòng iPhone và phiên bản iOS.
</Note>

### Google Wallet

Google chỉ cần một URL ảnh cho mỗi vị trí. Hệ thống của Google tự co giãn ảnh. Bạn chỉ cần đúng tỉ lệ và đủ độ phân giải.

| Vị trí                   | Kích thước nên dùng | Tỉ lệ              | Ghi chú                                                   |
| ------------------------ | ------------------- | ------------------ | --------------------------------------------------------- |
| Logo (vuông)             | 660×660 px          | Vuông 1:1          | Bắt buộc. Google cắt tròn, xem phần vùng an toàn bên dưới |
| Wide logo (logo ngang)   | 1280×400 px         | Ngang, khoảng 16:5 | Tùy chọn, hiển thị thay logo vuông, không bị cắt tròn     |
| Hero (ảnh lớn)           | 1032×336 px         | Rộng, khoảng 3:1   | Mặc định được ẩn, bạn bật khi cần                         |
| Ảnh mở rộng (Extend 1–5) | 1032×336 px         | Rộng, khoảng 3:1   | Dùng cùng tỉ lệ với hero                                  |

<Note>
  Trong XanhCard, ô nhập wide logo gợi ý 600×200 px. Tỉ lệ này tương đương chuẩn 1280×400 px của Google, nên bạn có thể dùng một trong hai kích thước.
</Note>

## Định dạng và dung lượng

* **Định dạng:** dùng PNG khi cần nền trong suốt (đặc biệt là logo). JPG dùng được cho ảnh strip và hero không cần trong suốt.
* **Màu sắc:** xuất ảnh với cấu hình màu sRGB để màu trên điện thoại giống với màu bạn thiết kế.
* **Dung lượng:** nén ảnh trước khi tải lên bằng TinyPNG hoặc Squoosh. Ảnh càng nhẹ, thẻ càng tải nhanh khi người dùng nhận qua email hoặc trang web.
* **Không phóng to quá mức:** ảnh lớn hơn bảng trên không nét hơn. Ảnh quá lớn chỉ làm file thẻ nặng và hiển thị chậm.

<Tip>
  Tải ảnh lên qua **Assets Management** và dùng URL đó trong mẫu thẻ thay vì URL bên ngoài. Ảnh tải lên luôn sẵn sàng và hiển thị ổn định. Xem [Quản lý tài nguyên](/assets/overview).
</Tip>

## Vùng an toàn

Vùng an toàn là phần ảnh chắc chắn hiển thị, không bị cắt trên mọi thiết bị.

### Logo Apple: dùng bản ngang, crop sát

Khung logo Apple là hình chữ nhật rộng (3,2:1). Nếu bạn dùng logo vuông, logo sẽ co lại rất nhỏ và lọt thỏm giữa khoảng trống.

Bạn nên:

* Xuất một bản logo ngang (biểu tượng + tên thương hiệu nằm cạnh nhau)
* Crop sát vào nét vẽ, không chừa viền trắng
* Dùng PNG nền trong suốt để màu nền thẻ hiện qua tự nhiên

### Logo Google: chừa lề vì bị cắt tròn

Google cắt logo vuông thành hình tròn. Bạn nên:

* Chừa lề an toàn khoảng 15% quanh logo
* Không tự cắt tròn trước, giữ nguyên ảnh vuông nền đầy
* Đặt biểu tượng chính vào giữa ảnh

Nếu dùng wide logo (bản ngang), ảnh không bị cắt tròn.

### Strip và hero: giữ nội dung quan trọng ở giữa

Strip của Apple và hero của Google không cùng tỉ lệ. Nếu bạn dùng chung một file cho cả hai, Google sẽ cắt hai cạnh bên.

Bạn nên:

* Giữ chữ, logo và chi tiết quan trọng trong 80% chiều rộng ở giữa
* Để hai mép ngoài là nền trơn, mất đi cũng không sao
* Không đặt chữ hoặc mã vạch trong ảnh strip và hero, vì chữ có thể bị cắt hoặc hiển thị khác nhau tùy thiết bị

### Logo trên nền thẻ

Logo PNG trong suốt được đặt trực tiếp lên màu nền thẻ, không phải lên nền trắng. Logo đen trên nền thẻ tối sẽ bị chìm và khó đọc.

Trước khi xuất bản, bạn hãy xem trước logo trên đúng màu nền đã chọn trong tab **General**.

<Warning>
  Apple vẽ chữ của thẻ đè lên ảnh strip ở góc trên. Bạn không nên đặt chi tiết quan trọng ở góc trên của ảnh strip.
</Warning>

## Cách nhập ảnh trong XanhCard

<Steps>
  <Step title="Tải ảnh lên Assets">
    Mở **Assets Management** ở cuối thanh điều hướng bên trái, nhấn **Upload Assets** và chọn file đã chuẩn bị đúng kích thước.
  </Step>

  <Step title="Dán URL vào mẫu thẻ">
    Mở mẫu thẻ, vào tab **Apple Wallet** → **Images** hoặc tab **Google Wallet** → **Images**. Dán URL ảnh vào từng vị trí: **Logo**, **Strip**, **Background**, **Thumbnail**, **Icon** (Apple) hoặc **Logo**, **Wide Logo**, **Hero** (Google). Với Apple, bạn dán bản nét nhất vào ô `@3x`.
  </Step>

  <Step title="Xem trước và xuất bản">
    Nhập dữ liệu mẫu trong tab **Preview Data** để xem thẻ hiển thị thế nào. Kiểm tra trên cả iPhone và Android nếu có thể, sau đó nhấn **Publish**.
  </Step>
</Steps>

<img src="https://mintcdn.com/xanhcard/oMUUuAnumaWwVH74/images/templates/08-google-wallet-images.png?fit=max&auto=format&n=oMUUuAnumaWwVH74&q=85&s=604c7257c4757c9aebdd8869af342ce7" alt="Tab Google Wallet - Images" width="2804" height="1960" data-path="images/templates/08-google-wallet-images.png" />

## Lỗi thường gặp

<AccordionGroup>
  <Accordion title="Ảnh bị mờ hoặc vỡ">
    Ảnh gốc nhỏ hơn khung hiển thị. Bạn hãy xuất lại ảnh theo cột `@3x` (Apple) hoặc đúng kích thước pixel (Google) trong bảng trên, rồi tải lên lại.
  </Accordion>

  <Accordion title="Logo Google bị cắt mất góc">
    Đây là hành vi mặc định vì Google cắt logo vuông thành hình tròn. Bạn hãy chừa lề 15% quanh logo, hoặc chuyển sang dùng wide logo bản ngang.
  </Accordion>

  <Accordion title="Ảnh strip đẹp trên iPhone nhưng bị cắt cạnh trên Android">
    Strip của Apple rộng hơn hero của Google. Bạn hãy giữ nội dung quan trọng trong 80% giữa ảnh và để hai mép là nền trơn.
  </Accordion>

  <Accordion title="Logo bị chìm vào màu nền thẻ">
    Logo PNG trong suốt hiển thị trực tiếp trên màu nền bạn chọn. Bạn hãy thử bản logo màu sáng hơn, hoặc đổi màu nền trong tab **General** để đủ tương phản.
  </Accordion>

  <Accordion title="Thẻ Apple báo lỗi chung sau khi đổi ảnh">
    Apple từ chối file ảnh sai kích thước mà không chỉ rõ file nào. Bạn hãy xuất lại đúng pixel trong bảng Apple Wallet và thử lại.
  </Accordion>

  <Accordion title="Đổi icon nhưng ngoài màn hình khóa chưa đổi">
    Apple lưu icon trong bộ nhớ đệm. Bạn hãy tắt hẳn ứng dụng Wallet rồi mở lại, hoặc khởi động lại thiết bị để thấy icon mới.
  </Accordion>
</AccordionGroup>

## Checklist trước khi xuất bản

* [ ] Logo có bản ngang cho Apple, bản vuông chừa lề cho Google
* [ ] Strip và hero đúng tỉ lệ, nội dung quan trọng nằm giữa ảnh
* [ ] File PNG cho logo, JPG hoặc PNG cho strip và hero
* [ ] Ảnh đã nén, màu sRGB
* [ ] Đã xem trước trên đúng màu nền thẻ
* [ ] Đã kiểm tra bản xem trước trên cả Apple Wallet và Google Wallet

Tham khảo thêm:

* [Thiết kế cho Apple Wallet](/templates/apple-wallet)
* [Thiết kế cho Google Wallet](/templates/google-wallet)
* [Quản lý tài nguyên](/assets/overview)