クイックスタート
ライブアクティビティを開始、表示、更新、終了します。
必要なものは次の3つです。
- HTTPリクエストを送る手段（
curl、バックエンド、サーバーレス関数）。 - APIキー。アカウントを作成し、ダッシュボードでプランを選んで（無料プランで使えます）、Developer > API Keyからキーをコピーします。
- スマートフォン。iOS 18以降のiPhone、またはWebActivityアプリを入れたAndroidスマートフォン。
すべての呼び出しで、x-api-keyヘッダーにAPIキーが必要です。キーは秘密情報です。リクエストはブラウザのコードではなく、必ずバックエンドから送ります。
アクティビティを開始する
最初のstateを送ります。layoutでデザイン（progress、picture、versus、countdown）が決まります。widgetContainerIdは必須で、このウィジェットを示す任意のテキストです。以降のすべての呼び出しで同じ値を送ります。brand.titleはアプリ内でのアクティビティ名です。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
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が含まれます：
1 2 3 4 5 6 7 8 9 10
{ "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をWebページに貼り付けます。Track With Live Activityボタンが表示されます。
- iPhone：タップするとアプリが開きます。インストールしていない場合はApp Clipが開きます。
- Android：タップするとWebActivityアプリが開きます。インストールしていない場合はGoogle Playが開きます。
- パソコン：クリックすると、スマートフォンでスキャンするQRコードが表示されます。
するとカードがロック画面とDynamic Islandに表示されます。まだWebページがない場合は、iframeのsrc URLをパソコンのブラウザで開いてボタンをクリックします。色を変えたり暗いページで使ったりするには、起動ボタンを参照してください。
アクティビティは、最初に開いたスマートフォンのものになります。1つのボタンを多くの人に配るには、reuse: trueを付けて開始します。1つのボタンで多くのスマートフォンにを参照してください。
更新を送る
activityId、そのwidgetContainerId、変更するフィールドだけを送ります。保存済みのステートにマージされます。
1 2 3 4 5 6 7 8 9 10 11 12 13
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秒かかることがあります。配信と請求を参照してください。
終了する
用事が済んだらアクティビティを終了します。カードは音を鳴らさず、すぐにスマートフォンから消えます。最後のデザインを画面に残したい場合は、それを更新として送り、あとでアクティビティを終了します。
1 2 3 4 5 6 7
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を付けた更新を送ると、同じスマートフォンにカードが戻ります。
グループを指定する
開始時に設定したgroupが、アクティビティのラベルになります。activityIdなしでgroupとそのwidgetContainerIdを送ると、1回の呼び出しですべてを更新または終了できます：
1 2 3 4 5 6 7 8 9 10
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を付けた更新を送ります。
ライフサイクルのコールバックを受け取る
ダッシュボードでWebhookエンドポイントを追加します。アクティビティが初めてスマートフォンに表示されたとき、そしてユーザーがアプリでオフにしたり削除したりしたときに、サービスがエンドポイントを呼び出します。Webhookを参照してください。
レイアウトを変更する
どの更新でも、新しいlayoutとそのレイアウトのフィールドを送れます。カードが新しいレイアウトに変わります。レイアウトを参照してください。
