상태 객체

휴대폰의 카드에 표시되는 내용을 정하는 모든 필드.

state는 카드에 표시되는 내용이에요. 레이아웃별로 어떤 필드가 표시되는지는 레이아웃에 있어요. 규칙은 다음과 같아요:

업데이트(그리고 종료의 finalState)에서는 보낸 필드가 저장된 상태에 병합돼요. 보내지 않은 필드는 값을 유지해요.
versus도 같은 방식으로 한 단계 아래까지 병합돼요. segments는 통째로 교체돼요.
필드를 비우려면 ""로 보내세요(segments는 []).
전체 상태는 16KB 이하여야 해요.

Android는 텍스트, 강조 색상, 아이콘, 사진 레이아웃의 사진, 진행 바, 점수, 리그 로고, 액션 버튼으로 시스템 알림을 그려요. iPhone 전용으로 표시된 필드는 Android에서 아무 효과가 없어요.

레이아웃과 텍스트

필드	유형	기본값	설명
`layout`	string	`progress`	`progress`, `picture`, `versus`, `countdown` 중 하나예요. start에서 설정하고, 유형을 바꾸려면 업데이트에서 바꾸세요.
`primaryText`	string	""	진행률 레이아웃의 헤드라인, 사진 레이아웃의 캡션이에요. 모든 알림의 제목이기도 하니 모든 레이아웃에서 설정하세요.
`secondaryText`	string	""	헤드라인 아래 줄이자 모든 알림의 본문이에요. 카운트다운 레이아웃에서는 시계 옆 이름이에요.
`stage`	string	없음	현재 단계를 나타내는 짧은 단어예요("배달 중"). iPhone은 진행률 레이아웃에서만 컴팩트 Dynamic Island에 표시해요. Android 16은 상태 칩에 표시해요. 7자 안팎으로 유지하세요.
`isComplete`	boolean	false	최종 상태면 `true`예요. 진행률 레이아웃은 컴팩트 Dynamic Island에 "완료"를 표시해요. 카드는 종료될 때까지 남아 있어요.

색상

색상은 #RRGGBB 텍스트예요. 텍스트 색상 필드는 없어요. 텍스트는 잘 보이도록 검은색이나 흰색으로 바뀌어요. Dynamic Island는 항상 어두워요.

필드	유형	기본값	설명
`accentColorHex`	string	파란색	브랜드 색상이에요. 진행 바, 색조, Android 강조 색상에 쓰여요. 사용자 지정 배경 색상 위에서는 진행 바가 대신 검은색이나 흰색이 돼요. 상태에 값이 없으면 `brand.color`가 설정해요.
`backgroundColorHex`	string	검은색	잠금 화면 배경이에요(진행률, 대결, 카운트다운). iPhone 전용.
`backgroundGradientHex`	string	없음	두 번째 색상이에요. `backgroundColorHex`와 함께 쓰면 배경이 그라데이션이 돼요(진행률, 대결, 카운트다운). iPhone 전용.

이미지

이미지 필드에는 휴대폰이 다운로드할 수 있는 전체 https URL을 넣어요. WebP를 쓰세요. 모양과 크기는 잘 맞는 이미지에 있어요. 업데이트에서 새 이미지 URL을 보내면 카드가 재시작되니, URL은 호출마다 같게 유지하세요.

필드	유형	기본값	설명
`headerIconUrl`	string	없음	진행률과 카운트다운 레이아웃의 로고이자, 사진 레이아웃의 작은 마크예요. 둥근 정사각형으로 그려져요.
`backgroundImageUrl`	string	없음	카드 뒤에 깔리는 전체 크기 이미지예요. 사진 레이아웃의 사진, 또는 진행률이나 대결 레이아웃의 배경이에요. 어두운 레이어가 텍스트를 읽기 쉽게 해 줘요. 카운트다운 레이아웃에는 표시되지 않아요.
`lockScreenImageUrl`	string	없음	잠금 화면에 어두운 Dynamic Island와 다른 이미지가 필요할 때 쓰는 잠금 화면용 `headerIconUrl`이에요. 진행률과 사진 레이아웃에서 쓰여요.
`islandImageUrl`	string	없음	사진 레이아웃 전용. 잠금 화면보다 작은 Dynamic Island용 사진이에요. 없으면 잠금 화면 사진을 써요. iPhone 전용.
`androidIconUrl`	string	없음	Android에서 `headerIconUrl`을 대신해요.
`androidImageUrl`	string	없음	Android에서 `backgroundImageUrl`을 대신해요. 사진 레이아웃은 이 이미지를 펼친 알림의 사진으로 보여 줘요.
`immersive`	boolean	false	`true`이면 `backgroundImageUrl` 위의 어두운 레이어를 없애요. 어두운 이미지에만 쓰세요. iPhone 전용.

진행률

필드	유형	기본값	설명
`progress`	number	0	`0`부터 `1`까지의 진행 바 채움 정도예요. 구간형 스타일에서 `segments`가 있으면 완료된 단계의 비율을 대신 써요.
`progressStyle`	string	`segmented`	`segmented`(단계마다 캡슐 하나) 또는 `linear`(바 하나, 양 끝에 첫 단계와 마지막 단계 라벨 표시).
`segments`	object[]	없음	단계 목록이에요. 각 단계는 `{ "label": string, "complete": boolean }` 형태이고, 최대 12개예요. 업데이트할 때마다 전체 목록을 보내세요.
`estimatedMinutes`	number	없음	분 단위 정수예요. `stage`가 없으면 컴팩트 Dynamic Island에 "N분"으로 표시돼요. `0`이면 숨겨요. iPhone 전용.

카운트다운

필드	유형	기본값	설명
`countdownTo`	number	없음	목표 시각을 Unix epoch 초 단위 숫자로 넣어요(밀리초나 텍스트는 안 돼요). 시계는 휴대폰에서 흘러가요. 시각이 되면 알림이 전송돼요.
`countdownStyle`	string	`auto`	`hms` (00:00:00), `days`, `hours`, `months`, `years`, `auto` 중 하나예요. `auto`는 마지막 36시간 동안 흐르는 시계(00:00:00)를 보여 주고, 그 전에는 가장 큰 정수 단위로 보여 줘요.
`completionText`	string	없음	시각이 되면 시계 자리에 표시되고, 그 알림의 제목이 돼요. 없으면 iPhone은 `secondaryText`, Android는 `primaryText`를 보여 줘요.

액션 버튼

버튼을 없애려면 세 필드를 모두 ""로 보내세요.

필드	유형	기본값	설명
`actionLabel`	string	없음	버튼 텍스트예요("생중계 보기"). iPhone은 사진과 대결 레이아웃에서 잠금 화면과 확장된 Dynamic Island에 표시하고, 컴팩트에는 표시하지 않아요. Android는 `actionURL`이 설정되어 있으면 모든 레이아웃에 표시해요.
`actionURL`	string	없음	버튼이 여는 `http` 또는 `https` URL이에요. 다른 URL은 무시돼요.
`actionColorHex`	string	빨간색(대결), 주황색(사진)	버튼 색상이에요. iPhone 전용.

versus 객체

layout이 versus일 때 state 안에 설정하세요.

필드	유형	기본값	설명
`leftName` / `rightName`	string	""	양쪽의 이름이에요.
`leftScore` / `rightScore`	string	"0"	점수는 텍스트라서 "12", "$1,500", "X" 모두 돼요. 숫자는 텍스트로 바뀌어요.
`leftStatus` / `rightStatus`	string	""	각 이름 아래의 작은 줄이에요("승리").
`activeSide`	string	없음	`"left"` 또는 `"right"`예요. Dynamic Island가 가장 작을 때 그쪽 로고를 보여 줘요.
`leftColorHex` / `rightColorHex`	string	텍스트 색상	양쪽 점수 색상이에요. iPhone 전용.
`centerLabel`	string	없음	가운데의 작은 텍스트예요("맵").
`centerValue`	string	없음	그 아래의 값이에요("Overpass").
`leftImageUrl` / `rightImageUrl`	string	없음	두 로고예요. 투명 PNG가 가장 보기 좋아요.
`centerImageUrl`	string	없음	가운데 이미지예요(경매 물품, 지도 등).
`sourceLogoUrl`	string	없음	리그 또는 브랜드 로고예요. iPhone의 하단 띠, Apple Watch 타일, Android 아이콘에 쓰여요.

브랜드 객체

선택 사항이며, start 호출의 최상위에 설정해요. 나중에 POST /api/branding으로 바꿀 수 있어요. 브랜드 이름 아래 표시되는 사이트는 실행 버튼을 넣은 페이지에서 정해지므로 브랜드 필드가 아니에요.

필드	유형	설명
`title`	string	앱 목록에 표시되는 실시간 현황 이름이에요. 없으면 `name`을 써요.
`name`	string	브랜드 이름이에요("Acme"). 앱, 대결 레이아웃의 하단 띠, 그리고 `primaryText`가 비어 있을 때 알림 제목으로 표시돼요. 생략하면 출처 이름이 표시되지 않아요.
`logo`	string	앱 커버에 쓰는 로고 URL이에요. 없으면 `headerIconUrl`, 그다음 WebActivity 로고를 써요.
`description`	string	커버의 제목 아래 짧은 한 줄이에요. 없으면 `secondaryText`를 써요.
`color`	string	`#RRGGBB` 형식의 브랜드 색상이에요. 상태에 값이 없으면 `accentColorHex`를 설정해요.