레이아웃

레이아웃은 네 가지예요. 정보에 맞는 것을 고르세요.

레이아웃	용도	예시
`progress`	단계, 또는 목표를 향해 커지는 값.	주문, 배송, 모금 행사.
`picture`	사진이 가장 중요할 때.	반려동물 매칭, 매물, 그 순간의 사진.
`versus`	점수가 있는 두 편.	게임, 경기, 경매.
`countdown`	시간상의 한 순간. 시계는 휴대폰에서 흘러가요.	발사, 킥오프, 마감.

시작할 때 상태에 layout 값을 설정하세요. 나중에 바꾸려면 업데이트에서 새 layout 값과 그 레이아웃의 필드를 보내세요. 실시간 현황 하나가 점수를 보여 주다가 사진을, 다시 점수를 보여 줄 수 있어요.

레이아웃별 표시 항목

iPhone에서:

필드	진행률	사진	대결	카운트다운
`primaryText`	헤드라인	캡션	표시 안 됨	표시 안 됨
`secondaryText`	헤드라인 아래 줄	캡션 아래 텍스트	표시 안 됨	시계 옆 이름
`headerIconUrl`	로고	작은 로고	표시 안 됨	로고
`backgroundImageUrl`	배경	사진	배경	표시 안 됨
`versus`	표시 안 됨	표시 안 됨	이름, 점수, 로고, 상태, 가운데 열	표시 안 됨
액션 버튼	표시 안 됨	표시됨	표시됨	표시 안 됨
컴팩트 Dynamic Island	`stage`, 그다음 "N분", 그다음 링	사진만	점수와 로고	남은 시간

모든 레이아웃에서 알림은 primaryText 값을 제목으로, secondaryText 값을 본문으로 써요. 표시하지 않는 레이아웃에서도 둘 다 설정하세요.

Android에서는 모든 레이아웃이 제목과 한 줄 텍스트로 된 알림이에요:

제목: primaryText. 대결 레이아웃은 점수("Lincoln 14-7 Central"), 카운트다운 레이아웃은 남은 시간.
텍스트: secondaryText. 대결 레이아웃은 가운데 열, 가운데 열이 없으면 상태.
사진 레이아웃은 사용자가 알림을 펼치면 사진을 보여 줘요.

잘 맞는 텍스트 길이

가장 작은 iPhone 화면 기준의 안전한 길이예요. 더 긴 텍스트는 "..." 없이 들어가는 마지막 단어에서 잘려요. Android는 긴 텍스트를 자르지 않고 줄바꿈해요. 보내기 전에 빌더에서 디자인을 확인하세요.

레이아웃	필드	글자 수
진행률	`primaryText`	로고가 있으면 17, 없으면 21
진행률	`secondaryText`	28
진행률	단계 라벨 (`segments`)	단계 3개면 12, 2개면 21
진행률	`stage`	7
사진	`primaryText`	27, 두 줄
사진	`secondaryText`	48, 두 줄
대결	`leftName` / `rightName`	가운데 열이 있으면 12, 없으면 16
대결	`leftStatus` / `rightStatus`	14
대결	`centerLabel` / `centerValue`	10
대결	`leftScore` / `rightScore`	로고와 가운데 열이 있으면 2자리
카운트다운	`secondaryText`	20
제한 없음	`actionLabel`	10
제한 없음	`brand.name`	18

잘 맞는 이미지

WebP를 쓰세요. PNG와 JPEG도 되지만 SVG는 안 돼요. 빌더는 모든 이미지를 너비 400픽셀의 WebP로, 슬롯 모양에 맞게 잘라 저장해요. 같은 크기를 쓰세요:

필드	모양	크기
`headerIconUrl`, `lockScreenImageUrl`, `androidIconUrl`, 대결 로고	정사각형	400 x 400
`backgroundImageUrl`	가로형, 2.34:1	400 x 171
`islandImageUrl`	거의 정사각형, 1.12:1 (`immersive` 값이 `true`이면 2.12:1)	400 x 358
`androidImageUrl`	1.39:1	400 x 288

로고 배경은 투명하게 하세요.

예시

단계가 있는 진행률

주문이 진행되면서 단계가 하나씩 완료돼요.

curl -X POST https://api.webliveactivity.com/api/start \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "widgetContainerId": "pizza-tracker",
  "brand": {
    "title": "Order #1234"
  },
  "state": {
    "layout": "progress",
    "primaryText": "In the oven now",
    "secondaryText": "Your order is cooking",
    "accentColorHex": "#0A84FF",
    "backgroundColorHex": "#0080BA",
    "headerIconUrl": "https://acme.example/logo.png",
    "estimatedMinutes": 30,
    "progressStyle": "segmented",
    "segments": [
      {
        "label": "Cooking",
        "complete": false
      },
      {
        "label": "On the way",
        "complete": false
      },
      {
        "label": "Delivered",
        "complete": false
      }
    ]
  }
}'

사진

사진은 backgroundImageUrl에 넣어요. headerIconUrl 값은 작은 로고예요.

curl -X POST https://api.webliveactivity.com/api/start \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "widgetContainerId": "pet-matches",
  "brand": {
    "title": "Meet Luna"
  },
  "state": {
    "layout": "picture",
    "primaryText": "Luna",
    "secondaryText": "2 year old Tabby, Spayed",
    "accentColorHex": "#FF6B35",
    "headerIconUrl": "https://petfinder.example/logo.png",
    "backgroundImageUrl": "https://petfinder.example/luna.jpg",
    "actionLabel": "View Live",
    "actionURL": "https://petfinder.example/luna"
  }
}'

대결

점수, 로고, 상태, 가운데 열이 있는 두 편.

curl -X POST https://api.webliveactivity.com/api/start \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "widgetContainerId": "csgo-scores",
  "brand": {
    "title": "CSGO Esports"
  },
  "state": {
    "layout": "versus",
    "primaryText": "Heroic leads 12-9",
    "secondaryText": "Map: Overpass",
    "accentColorHex": "#0A84FF",
    "backgroundColorHex": "#001226",
    "backgroundGradientHex": "#00428C",
    "actionLabel": "Watch Live",
    "actionURL": "https://hltv.org/matches",
    "versus": {
      "leftName": "Movistar",
      "rightName": "Heroic",
      "leftScore": "9",
      "rightScore": "12",
      "leftStatus": "T side",
      "rightStatus": "CT side",
      "activeSide": "right",
      "leftImageUrl": "https://hltv.org/movistar.png",
      "rightImageUrl": "https://hltv.org/heroic.png",
      "centerLabel": "Map",
      "centerValue": "Overpass",
      "sourceLogoUrl": "https://hltv.org/csgo.png"
    }
  }
}'

카운트다운

시간이 됐을 때 카드가 아직 휴대폰에 있으면, 서비스가 알아서 알림을 한 번 보내요. 시계 자리와 그 알림에 표시할 문구는 completionText 값으로 설정하세요. 8시간보다 긴 카운트다운은 keepAlive: true 설정으로 시작하세요. 그렇지 않으면 시간이 되기 전에 iOS가 카드를 끝내요.

curl -X POST https://api.webliveactivity.com/api/start \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "widgetContainerId": "gta6-countdown",
  "keepAlive": true,
  "brand": {
    "title": "GTA VI"
  },
  "state": {
    "layout": "countdown",
    "primaryText": "Grand Theft Auto VI",
    "secondaryText": "GTA VI",
    "countdownTo": 1795046400,
    "countdownStyle": "days",
    "completionText": "Out now",
    "headerIconUrl": "https://rockstargames.com/gta6-logo.png"
  }
}'