Apple Wallet 패스 빌더

Apple Wallet 패스 빌더는 Control Panel의 시각적 디자이너입니다. 패스 스타일을 선택하고, 브랜딩, 필드, 바코드를 채우고, 실시간 미리보기를 확인하고, 패스를 생성할 수 있으므로 pass.json을 직접 작성할 필요가 없습니다.

패스 생성

Control Panel에서 캠페인 → 월렛 패스로 이동하여 전체 패스 탭을 열고 Apple Wallet을 선택한 다음 패스 생성을 클릭합니다.

패스 구성

• 처음부터 만들기: 빈 패스로 시작합니다. 패스 스타일을 선택한 다음 아래 섹션에서 색상, 이미지, 필드, 바코드 및 기타 옵션을 직접 설정합니다.

• 템플릿에서 만들기: 템플릿 로드를 클릭하고, 템플릿 선택에서 내장된 패스(탑승권, 쿠폰, 이벤트 티켓, 일반 또는 스토어 카드)를 선택합니다. 템플릿은 클릭하는 즉시 적용됩니다. 양식은 패스 스타일, 색상, 패스 필드, 바코드 및 기본 정보로 미리 채워지고, 관련 날짜는 현재 시간으로 설정됩니다. 템플릿에는 이미지가 포함되지 않으므로 패스를 생성하기 전에 아이콘과 로고를 업로드하세요. 필요에 따라 값을 편집하거나 스타일을 변경할 수 있습니다. Pushwoosh는 템플릿의 팀 및 Pass Type ID를 애플리케이션의 값으로 대체합니다.

패스 스타일 선택

PASS STYLE에서 5가지 Apple Wallet 패스 스타일 중 하나를 선택합니다. 스타일은 레이아웃과 사용 가능한 필드 영역 및 이미지를 제어합니다:

• Boarding Pass
• Coupon
• Event Ticket
• Store Card
• Generic

스타일을 전환하면 모든 패스 필드가 지워지므로 필드와 이미지를 추가하기 전에 스타일을 선택하세요.

패스 이름 및 설명 추가

BASIC INFORMATION에서 다음을 입력합니다:

Pass Name	패스 제목이자 업데이트 알림에 표시되는 소스 이름입니다.
Description	패스에 대한 간단한 설명입니다.
Logo Text	로고 옆에 표시되는 텍스트입니다.

색상 및 이미지 설정

색상

COLORS에서 다음을 설정합니다:

• Background Color: 패스 배경입니다.
• Foreground Color: 패스의 주요 텍스트 및 아이콘입니다.
• Label Color: 필드 레이블의 색상입니다 (예: FROM, GATE).

색상을 설정하거나 변경하려면 해당 필드를 클릭하고 색상 선택기에서 색상을 선택합니다.

참고

색상은 rgb(r, g, b) 형식으로 저장됩니다.

이미지

IMAGES에서 Icon과 Logo(모두 필수)를 업로드합니다. 선택적 이미지는 패스 스타일에 따라 다릅니다:

이미지	크기	사용 가능한 스타일
아이콘	29×29	모든 스타일 (필수)
로고	160×50	모든 스타일 (필수)
스트립	375×144	Coupon, Event Ticket, Store Card
배경	180×220	Event Ticket
썸네일	90×90	Event Ticket, Generic
푸터	286×15	Boarding Pass

각 이미지 슬롯 옆의 Choose File을 클릭하고 PNG 또는 JPEG 파일을 업로드합니다. Pushwoosh는 각 이미지를 중앙 기준으로 슬롯 크기에 맞게 자르고 Apple이 요구하는 해상도(@1x, @2x, @3x)를 준비합니다.

패스 필드 채우기

PASS FIELDS에서 패스에 나타나는 텍스트와 값을 추가합니다. 모든 스타일에 동일한 필드 그룹이 있으며, 제한은 다음과 같습니다:

• 헤더 필드 (패스 상단): 최대 3개
• 기본 필드 (주요 콘텐츠): 1개. Boarding Pass에서는 2개를 포함하며 그룹 이름은 다음과 같습니다: 기본 필드 (출발지/목적지)
• 보조 필드 (지원 정보): 최대 4개
• 추가 필드 (상세 정보): 최대 4개, Boarding Pass에서는 5개
• 뒷면 필드 (패스 뒷면)

필요한 각 그룹에서 + Add Field를 클릭합니다.

각 필드에 대해 다음을 설정합니다:

Key (ID)	고유한 필드 식별자입니다 (자동으로 생성됨).
Label	패스에 표시되는 짧은 레이블입니다 (예: FROM).
Value	패스에 표시되는 값입니다 (예: SFO).
Change message	이 값이 변경될 때 업데이트 알림에 표시되는 텍스트입니다. 값이 변경될 때만 표시됩니다. 새 값에 %@를 사용하세요 (예: Gate changed to %@).

필드 카드에서 Format을 클릭하여 서식 옵션을 표시합니다. 필드를 제거하려면 X를 클릭합니다.

서식 옵션

• Value format: 텍스트, 날짜 / 시간 또는 숫자 / 통화.
• Text alignment: 기본값 (자연스러움), 왼쪽, 가운데, 오른쪽 또는 자연스러움.
• Data detectors (뒷면 필드만 해당): 뒷면 필드의 전화번호, 링크, 주소 및 캘린더 이벤트를 탭할 수 있는 콘텐츠로 변환합니다.

패스 콘텐츠 개인화하기

이름이나 포인트 잔액처럼 수신자별 고유 데이터를 표시하려면 텍스트 필드에 태그 플레이스홀더를 삽입합니다. { } 버튼은 다음에서 사용할 수 있습니다:

• 패스 이름, 설명, 로고 텍스트
• 필드의 레이블, 값, 변경 메시지
• 바코드 메시지, 대체 텍스트, 그룹화 식별자

플레이스홀더를 삽입하려면:

1. 텍스트 필드 옆의 { }를 클릭합니다.
2. 태그를 선택합니다.
3. 형식을 선택합니다. 옵션은 같은 대화 상자를 사용하는 Google Wallet 빌더의 패스 콘텐츠 개인화하기를 참조하세요.
4. 필요한 경우 대체 값 (비어 있는 경우) 필드에 값을 입력합니다.

실시간 미리보기는 User ID에 입력한 사용자의 태그 값을 표시합니다. User ID가 없으면 플레이스홀더를 표시합니다.

바코드 추가

BARCODE에서 형식을 선택하고 인코딩할 데이터를 입력합니다:

1. Barcode Format: 바코드의 모양과 스캔 가능한 스캐너 유형을 선택합니다.
   • QR Code (권장): 대부분의 휴대폰과 스캐너가 쉽게 읽을 수 있는 정사각형 코드입니다. 쿠폰, 로열티 카드 및 대부분의 패스에 가장 적합합니다.
   • PDF417: 여러 줄의 선으로 구성된 넓은 바코드입니다. 항공사 또는 대중교통 탑승권에 종종 필요합니다.
   • Aztec: QR과 유사한 소형 정사각형 코드입니다. 이벤트 및 대중교통 티켓에 일반적입니다.
   • Code128: 고전적인 수직선 바코드입니다. 스캐너 또는 POS 시스템에서 1D 바코드가 필요한 경우에만 선택하세요.
2. Barcode Message: 바코드에 인코딩된 값입니다 (예: 티켓 또는 멤버십 번호).
3. Alt Text (선택 사항): 패스의 바코드 아래에 표시되는 텍스트입니다.

만료 및 상태 설정

EXPIRATION & STATUS에서 패스가 표시되는 시점, 만료되는 시점 및 유효 여부를 제어합니다:

• Relevant Date (패스를 표시할 시점): 패스가 잠금 화면에 나타날 수 있는 날짜 및 시간입니다.
• Expiration Date (패스가 만료되는 시점): 이 날짜 및 시간 이후에는 Wallet에서 패스가 회색으로 표시됩니다.
• Mark as Voided (이 패스를 무효화): 패스를 더 이상 사용할 수 없도록 무효화하는 확인란입니다.

스타일에 특정한 고급 옵션

• Transit type (Boarding Pass만 해당): Air, Train, Bus, Boat 또는 Generic.
• Grouping identifier: Wallet에서 관련 패스를 함께 그룹화합니다.

위치 기반 관련성 (선택 사항)

LOCATION-BASED RELEVANCE에서 사용자가 추가한 위치 근처에 있을 때 패스가 나타납니다. 각 위치에 대해 사용자가 근처에 있을 때 잠금 화면에 표시되는 텍스트를 설정합니다. 최대 10개의 위치를 추가할 수 있습니다.

지도를 클릭하거나, 주소를 검색하거나, 좌표를 붙여넣거나, 지오존을 가져와 지점을 추가합니다. 마커를 드래그하여 위치를 미세 조정합니다.

최대 거리(미터 단위)는 패스가 관련성을 유지하기 위해 사용자가 얼마나 가까이 있어야 하는지를 제어합니다.

위치 vs. 비콘

LOCATION-BASED RELEVANCE 섹션은 지도 기반 위치만 구성합니다. 장소와 최대 거리를 미터 단위로 정의합니다. 기기는 위치 서비스를 사용하여 사용자가 충분히 가까이 있는지 결정합니다. 그러면 Wallet은 해당 위치에 대한 잠금 화면 텍스트를 표시할 수 있습니다.

실내에서 패스를 iBeacon 하드웨어에 연결하려면 아래의 IBEACON RELEVANCE 섹션을 사용하세요.

사용 사례 예시

• 소매: 고객이 매장 근처에 있을 때 로열티 카드나 쿠폰이 표시됩니다. 잠금 화면 텍스트는 매장 근처에 있음을 알리고 패스 사용을 상기시킬 수 있습니다.
• 이벤트: 사용자가 행사장(경기장, 극장 또는 축제장) 근처에 있을 때 이벤트 티켓이 나타나 문 앞에서 패스를 빠르게 찾을 수 있습니다.
• 여행: 탑승권이 출발 공항이나 터미널 근처에서 눈에 띄게 되어 승객이 Wallet을 열기 전에 잠금 화면에서 게이트나 항공편 세부 정보를 볼 수 있습니다.
• 호텔/식당: 정의한 카페나 호텔 위치 근처에서 쿠폰이나 멤버십 패스가 나타날 수 있습니다.

iBeacon 관련성 (선택 사항)

IBEACON RELEVANCE에서 기기가 일치하는 신호를 브로드캐스트하는 물리적 iBeacon 송신기 근처에 있을 때 패스가 나타납니다. 이 기능은 지도 기반 위치 서비스를 신뢰하기 어려운 실내에서 작동합니다.

비콘을 추가하려면 Add beacon을 클릭합니다(최대 10개). 비콘을 제거하려면 해당 카드에서 **×**를 클릭합니다.

각 비콘에 대해 다음을 설정합니다:

• Proximity UUID: 비콘의 식별자입니다 (예: B9407F30-F5F8-466E-AFF9-25556B57FE6D).
• Major 및 Minor (선택 사항): 일치 범위를 장소와 개별 비콘으로 좁힙니다. 각각 0에서 65535 사이의 숫자이며, 0은 빈 값과 동일하게 동작합니다. 해당 UUID를 브로드캐스트하는 모든 비콘과 일치시키려면 둘 다 비워 두거나 둘 다 0으로 설정하세요.
• Relevant text: 패스가 관련성을 갖게 될 때 잠금 화면에 표시되는 텍스트입니다.

User ID 입력

이 패스를 받을 사람의 Pushwoosh User ID를 입력합니다. Pushwoosh는 해당 사용자에게 패스를 발급하고 All passes의 USER 아래에 목록으로 표시합니다.

미리보기 및 유효성 검사

편집하는 동안 실시간 미리보기가 업데이트되므로 Wallet에서 패스가 어떻게 보일지 대략적으로 확인할 수 있습니다.

기기에서는 미리보기가 다를 수 있습니다

미리보기는 근사치입니다. 실제 기기에서는 패스가 다르게 보일 수 있습니다. 표시된 바코드는 자리 표시자입니다. 실제 바코드는 최종 .pkpass에서 생성됩니다.

패스를 생성하지 않고 Apple의 사양과 비교하여 확인하려면 Validate pass를 클릭합니다. 빌더는 누락된 필수 이미지 및 기타 문제를 표시합니다.

패스 생성

생성을 선택합니다. Pushwoosh는 패스의 유효성을 검사하고 이미지를 처리합니다. 생성에는 몇 초가 걸리며, 그 후 패스가 전체 패스에 나타납니다.

생성 후 패스 편집(일련 번호로 업데이트 포함), 다운로드 및 삭제에 대해서는 기존 패스 관리를 참조하세요. 사용자에게 패스를 보내려면 Wallet 패스 공유를 참조하세요.

하나의 디자인을 여러 사용자에게 발급하고 발급된 모든 패스의 공유 필드를 한 번에 업데이트하려면 대신 Wallet Pass Campaign을 생성하세요. 캠페인은 이 빌더와 동일한 디자인 섹션을 사용합니다.

API를 통한 패스 관리

패스 빌더가 수행하는 모든 작업은 PassKit Designer API를 통해서도 가능합니다: 패스 생성, 업데이트, 목록 조회, 다운로드 및 삭제.

Apple Wallet PassKit API