POST /api/start

실시간 현황을 만들고 실행 버튼을 받아요. 휴대폰이 버튼을 열면 카드가 나타나요.

모든 호출에 키를 x-api-key 헤더로 보내세요. 모든 요청은 Content-Type: application/json이고, 필드 이름은 정확한 camelCase예요(accentColorHex, accent_color_hex는 안 돼요). 오류는 오류 및 한도에 정리돼 있어요.

본문

필드	유형	설명
`state`	object	필수. 카드에 표시되는 내용이에요. 레이아웃과 상태 객체를 참고하세요.
`widgetContainerId`	string	필수. 위젯을 가리키는 텍스트면 무엇이든 돼요. 예: "pizza-tracker". 이 위젯의 이후 모든 호출에 같은 값을 보내세요. 휴대폰 한 대에는 컨테이너당 실시간 현황이 하나만 유지돼요.
`group`	string	한 번의 호출로 여러 실시간 현황을 업데이트하거나 종료할 수 있게 해 주는 라벨이에요.
`brand`	object	실시간 현황의 이름과 브랜딩이에요. 브랜드 객체를 참고하세요.
`reuse`	boolean	`true`이면 실행 버튼 하나로 여러 휴대폰을 지원해요. 버튼 하나, 여러 휴대폰을 참고하세요.
`keepAlive`	boolean	`true`이면 iOS가 카드를 끝내기 전에 7시간마다 카드를 재시작해요. 재시작할 때마다 알림을 울려요. 카운트다운처럼 8시간보다 오래 이어지는 경우에 사용하세요. 오래 실행되는 실시간 현황을 참고하세요.
`webhookIdentifier`	string	이 실시간 현황의 웹훅 이벤트를 이 식별자를 가진 엔드포인트로 보내요. 웹훅을 참고하세요.

기본 start

가장 간단한 start: 헤드라인과 로고가 있는 진행 바.

curl -X POST https://api.webliveactivity.com/api/start \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "widgetContainerId": "acme-orders",
  "brand": {
    "title": "Order #1234"
  },
  "state": {
    "layout": "progress",
    "primaryText": "Order received",
    "progress": 0.1,
    "accentColorHex": "#0A84FF",
    "headerIconUrl": "https://acme.example/logo.png"
  }
}'

모든 옵션을 넣은 start

curl -X POST https://api.webliveactivity.com/api/start \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "widgetContainerId": "acme-orders",
  "group": "order-tracker",
  "keepAlive": true,
  "webhookIdentifier": "staging",
  "brand": {
    "title": "Order #1234",
    "name": "Acme",
    "logo": "https://acme.example/logo.png",
    "description": "Track your Acme order from kitchen to door",
    "color": "#06C167"
  },
  "state": {
    "layout": "progress",
    "primaryText": "Order received",
    "secondaryText": "We will start soon",
    "progress": 0.1
  }
}'

응답

201로 응답해요. 업데이트와 종료에 쓸 activityId 값을 보관하세요. userId 값은 같은 id를 휴대폰 앱에서 쓰는 이름으로 담은 거예요. group 값은 보내지 않았으면 비어 있어요.

{
  "ok": true,
  "activityId": "act-8f2cqa4mx7rd",
  "userId": "act-8f2cqa4mx7rd",
  "group": "order-tracker",
  "widgetContainerId": "acme-orders",
  "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 값을 넣으세요. 휴대폰에서는 탭하면 실시간 현황이 열려요. 컴퓨터에서는 클릭하면 휴대폰으로 스캔할 QR 코드가 표시돼요.

iframe의 src에는 선택 설정 세 가지를 넣을 수 있어요:

설정	값	설명
`color`	6자리 hex 색상, `#` 제외	버튼 색상이에요. 예: `&color=06C167`. 밝은 색상이면 텍스트가 어두워져요. 기본값: `type`의 색상.
`theme`	`light` (기본값), `dark`	버튼 아래 "Powered By" 텍스트의 색상이에요. 어두운 페이지에서는 `&theme=dark` 값을 추가하고, iframe의 `style`에서 `color-scheme:light`를 `color-scheme:dark`로 바꾸세요.
`type`	`track` (기본값), `launch`, `add`	버튼의 아이콘, 라벨, 기본 색상이에요. 푸시 그룹은 `notify`, `subscribe`, `follow`를 써요.

배경은 투명해요. 바꿀 수 있는 건 색상뿐이고, 아이콘과 라벨은 type에서 정해지며, 모든 요금제에서 버튼 아래에 "Powered By" 줄이 표시돼요.

버튼을 넣은 페이지가 휴대폰의 실시간 현황과 함께 표시되는 사이트가 돼요. API로는 설정할 수 없어요. 리퍼러를 숨기는 페이지(Referrer-Policy: no-referrer, same-origin, 또는 iframe의 referrerpolicy="no-referrer")에서는 버튼이 로드되지 않아요.

POST /api/start

본문

기본 start

모든 옵션을 넣은 start

응답

실행 버튼

“만들지 않고” 실시간 현황을 만들 준비가 됐나요?

오늘 바로 만들어 볼 준비가 됐나요?