빠른 시작

실시간 현황을 시작하고, 표시하고, 업데이트하고, 종료해요.

필요한 것은 세 가지예요:

HTTP 요청을 보낼 수단 (curl, 백엔드, 서버리스 함수).
API 키. 계정을 만들고 대시보드에서 요금제를 고른 다음(무료도 돼요), Developer > API Key에서 키를 복사하세요.
휴대폰: iOS 18 이상의 iPhone, 또는 WebActivity 앱이 설치된 Android 휴대폰.

모든 호출에는 x-api-key 헤더에 API 키가 필요해요. 키는 비밀이에요. 요청은 브라우저 코드가 아니라 백엔드에서 보내세요.

실시간 현황 시작하기

첫 state 객체를 보내세요. layout 값이 디자인(progress, picture, versus, countdown)을 정해요. widgetContainerId 값은 필수이고, 이 위젯을 가리키는 텍스트면 무엇이든 돼요. 이후 모든 호출에 같은 값을 보내세요. brand.title 값은 앱에 표시되는 실시간 현황 이름이에요.

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",
  "group": "order-tracker",
  "brand": {
    "title": "Order #1234"
  },
  "state": {
    "layout": "progress",
    "primaryText": "Preparing your order",
    "progress": 0.25
  }
}'

응답(201)에는 이후 모든 호출에 쓰는 activityId 값과, 실행 버튼인 links.iframe 값이 들어 있어요:

{
  "ok": true,
  "activityId": "act-8f2cqa4mx7rd",
  "userId": "act-8f2cqa4mx7rd",
  "group": "order-tracker",
  "widgetContainerId": "pizza-tracker",
  "links": {
    "iframe": "<iframe src=\"https://api.webliveactivity.com/embed/button?type=track&userId=act-8f2cqa4mx7rd\" width=\"340\" height=\"95\" style=\"border:0;color-scheme:light\"></iframe>"
  }
}

휴대폰에서 열기

웹 페이지에 links.iframe 값을 붙여 넣으세요. Track With Live Activity 버튼이 표시돼요.

iPhone: 탭하면 앱이 열리거나, 설치 없이 앱 클립이 열려요.
Android: 탭하면 WebActivity 앱이 열리거나, 설치할 수 있게 Google Play가 열려요.
컴퓨터: 클릭하면 휴대폰으로 스캔할 QR 코드가 표시돼요.

그러면 잠금 화면과 Dynamic Island에 카드가 나타나요. 아직 웹 페이지가 없나요? 컴퓨터 브라우저에서 iframe의 src URL을 열고 버튼을 클릭하세요. 색상을 바꾸거나 어두운 페이지에서 쓰려면 실행 버튼을 참고하세요.

실시간 현황은 처음 연 휴대폰의 것이 돼요. 버튼 하나를 여러 사람에게 주려면 reuse: true 옵션으로 시작하세요. 버튼 하나, 여러 휴대폰을 참고하세요.

업데이트 보내기

activityId 값, 해당 widgetContainerId 값, 그리고 바뀌는 필드만 보내세요. 저장된 상태에 병합돼요.

curl -X POST https://api.webliveactivity.com/api/update \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "activityId": "act-8f2cqa4mx7rd",
  "widgetContainerId": "pizza-tracker",
  "state": {
    "primaryText": "Out for delivery",
    "stage": "On the way",
    "progress": 0.7,
    "estimatedMinutes": 8
  }
}'

카드가 그 자리에서 업데이트돼요. priority: 5 설정으로 보내지 않으면 업데이트마다 휴대폰에 알림이 울려요. 업데이트가 도착하기까지 최대 45초가 걸릴 수 있어요. 전송 및 요금을 참고하세요.

종료하기

작업이 끝나면 실시간 현황을 종료하세요. 카드는 소리 없이 휴대폰에서 바로 사라져요. 마지막 디자인을 화면에 남기려면 업데이트로 보낸 다음 나중에 종료하세요.

curl -X POST https://api.webliveactivity.com/api/end \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "activityId": "act-8f2cqa4mx7rd",
  "widgetContainerId": "pizza-tracker"
}'

종료해도 실시간 현황이 삭제되지는 않아요. restart: true 설정으로 업데이트하면 같은 휴대폰에 카드가 다시 나타나요.

그룹 대상으로 보내기

start에서 설정한 group 값은 실시간 현황에 라벨을 붙여요. activityId 없이 group 값과 해당 widgetContainerId 값을 보내면 한 번의 호출로 모두 업데이트하거나 종료할 수 있어요:

curl -X POST https://api.webliveactivity.com/api/update \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "group": "order-tracker",
  "widgetContainerId": "pizza-tracker",
  "state": {
    "secondaryText": "Kitchen is busier than usual"
  }
}'

오래 실행되는 실시간 현황

iOS는 카드가 시작되고 8시간이 지나면 일반 업데이트를 더 받지 않아요. keepAlive: true 설정으로 실시간 현황을 시작하면 서비스가 7시간마다 카드를 재시작해서 카드가 휴대폰에 계속 남아요. 이 재시작은 매번 알림을 울려요. 8시간보다 긴 카운트다운이 알림 시간까지 남으려면 이 설정이 필요해요. 설정하지 않으면 8시간이 지난 뒤의 다음 업데이트는 재시작으로 보내져서 카드를 다시 만들고 항상 알림을 울려요. 사용자가 밀어서 없앤 카드를 다시 띄우려면 restart: true 설정으로 업데이트를 보내세요.

수명 주기 콜백 받기

대시보드에서 웹훅 엔드포인트를 추가하세요. 실시간 현황이 휴대폰에 처음 나타날 때, 그리고 사용자가 앱에서 끄거나 삭제할 때 서비스가 이 엔드포인트를 호출해요. 웹훅을 참고하세요.

레이아웃 바꾸기

어떤 업데이트에서든 새 layout 값과 그 레이아웃의 필드를 보내세요. 카드가 새 레이아웃으로 바뀌어요. 레이아웃을 참고하세요.