POST /api/start
アクティビティを作成し、その起動ボタンを取得します。スマートフォンでボタンを開くとカードが表示されます。
すべての呼び出しで、APIキーをx-api-keyヘッダーで送ります。すべてのリクエストはContent-Type: application/jsonで、フィールド名は正確なcamelCaseです（accentColorHex。accent_color_hexは不可）。エラーの一覧はエラーと制限にあります。
本文
| フィールド | 型 | 説明 |
|---|---|---|
state | object | 必須。カードに表示する内容。レイアウトとstateオブジェクトを参照してください。 |
widgetContainerId | string | 必須。ウィジェットを示す任意のテキスト（例：「pizza-tracker」）。このウィジェットへの以降のすべての呼び出しで同じ値を送ります。スマートフォンはコンテナごとに1つのアクティビティを保持します。 |
group | string | 1回の呼び出しで多くのアクティビティを更新または終了するためのラベル。 |
brand | object | アクティビティの名前とブランディング。brandオブジェクトを参照してください。 |
reuse | boolean | trueにすると、1つの起動ボタンを多くのスマートフォンで使えます。1つのボタンで多くのスマートフォンにを参照してください。 |
keepAlive | boolean | trueにすると、iOSに終了される前に、7時間ごとにカードを再起動します。再起動のたびに通知されます。カウントダウンなど、8時間より長く続くものに使います。長時間のアクティビティを参照してください。 |
webhookIdentifier | string | このアクティビティのWebhookイベントを、この識別子を持つエンドポイントに送ります。Webhookを参照してください。 |
基本的な開始
最もシンプルな開始。見出しとロゴ付きのプログレスバー。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
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" } }'
すべてのオプションを使った開始
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
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は空です。
1 2 3 4 5 6 7 8 9 10
{ "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をWebページに置きます。スマートフォンではタップでアクティビティが開きます。パソコンではクリックすると、スマートフォンでスキャンするQRコードが表示されます。
iframeのsrcには、3つの任意の設定があります：
| 設定 | 値 | 説明 |
|---|---|---|
color | 6桁の16進数カラー（#なし） | ボタンの色。例：&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"）では、ボタンは読み込まれません。
