stateオブジェクト
スマートフォンでカードに表示される内容を制御する、すべてのフィールド。
stateはカードに表示される内容です。どのレイアウトがどのフィールドを表示するかはレイアウトにあります。ルールは次のとおりです：
- 更新時（および終了時の
finalState）は、送ったフィールドが保存済みのステートにマージされます。送らなかったフィールドは値がそのまま残ります。 versusも同じように1階層下までマージされます。segmentsは丸ごと置き換えられます。- フィールドを空にするには
""を送ります（segmentsの場合は[]）。 - ステート全体は16KB以下にする必要があります。
Androidは、テキスト、アクセントカラー、アイコン、ピクチャーの写真、プログレスバー、スコア、リーグのロゴ、アクションボタンからシステム通知を描画します。iPhoneのみと記載されたフィールドは、Androidでは何もしません。
レイアウトとテキスト
| フィールド | 型 | デフォルト | 説明 |
|---|---|---|---|
layout | string | progress | progress、picture、versus、countdownのいずれか。開始時に設定します。更新で変えると種類が切り替わります。 |
primaryText | string | "" | プログレスでは見出し、ピクチャーではキャプション。すべての通知のタイトルにもなるので、どのレイアウトでも設定します。 |
secondaryText | string | "" | 見出しの下の行で、すべての通知の本文。カウントダウンでは時計の横の名前。 |
stage | string | なし | 現在のステップを表す短い言葉（「配達中」）。iPhoneでは、プログレスの場合だけコンパクトなDynamic Islandに表示されます。Android 16ではステータスチップに表示されます。7文字程度に収めます。 |
isComplete | boolean | false | 最終ステートではtrue。プログレスでは、コンパクトなDynamic Islandに「完了」と表示されます。カードは終了するまで残ります。 |
カラー
カラーは#RRGGBBのテキストです。文字色のフィールドはありません。文字は読みやすいように黒か白になります。Dynamic Islandは常に暗い色です。
| フィールド | 型 | デフォルト | 説明 |
|---|---|---|---|
accentColorHex | string | 青 | ブランドカラー。プログレスバー、色合い、Androidのアクセントに使われます。背景色をカスタムにすると、バーは代わりに黒か白になります。ステートで設定されていない場合はbrand.colorで設定されます。 |
backgroundColorHex | string | 黒 | ロック画面の背景（プログレス、バーサス、カウントダウン）。iPhoneのみ。 |
backgroundGradientHex | string | なし | 2つ目の色。backgroundColorHexと組み合わせると、背景がグラデーションになります（プログレス、バーサス、カウントダウン）。iPhoneのみ。 |
画像
画像フィールドには、スマートフォンがダウンロードできる完全なhttps URLを指定します。WebPを使います。形とサイズは収まる画像にあります。更新で新しい画像URLを送るとカードが再起動するので、URLは呼び出し間で同じものを使います。
| フィールド | 型 | デフォルト | 説明 |
|---|---|---|---|
headerIconUrl | string | なし | プログレスとカウントダウンのロゴ、およびピクチャーの小さいマーク。角の丸い正方形で描画されます。 |
backgroundImageUrl | string | なし | カードの背後に表示されるフルサイズの画像。ピクチャーの写真、またはプログレスやバーサスの背景です。暗いレイヤーで文字を読みやすくします。カウントダウンでは表示されません。 |
lockScreenImageUrl | string | なし | ロック画面用のheaderIconUrl。暗いDynamic Islandとは別の画像がロック画面に必要な場合に使います。プログレスとピクチャーで使われます。 |
islandImageUrl | string | なし | ピクチャーのみ。ロック画面より小さいDynamic Island用の別の写真。指定しない場合はロック画面の写真が使われます。iPhoneのみ。 |
androidIconUrl | string | なし | AndroidでheaderIconUrlの代わりに使われます。 |
androidImageUrl | string | なし | AndroidでbackgroundImageUrlの代わりに使われます。ピクチャーでは展開時の写真として表示されます。 |
immersive | boolean | false | trueにすると、backgroundImageUrlの上の暗いレイヤーがなくなります。暗い画像でのみ使います。iPhoneのみ。 |
プログレス
| フィールド | 型 | デフォルト | 説明 |
|---|---|---|---|
progress | number | 0 | バーの塗りつぶし（0〜1）。セグメントスタイルでsegmentsがある場合は、代わりに完了したステップの割合が使われます。 |
progressStyle | string | segmented | segmented（ステップごとに1つのカプセル）またはlinear（1本のバーで、両端に最初と最後のステップのラベルが付きます）。 |
segments | object[] | なし | ステップ。それぞれ{ "label": string, "complete": boolean }。最大12個。更新のたびにリスト全体を送ります。 |
estimatedMinutes | number | なし | 分単位の整数。stageが設定されていない場合、コンパクトなDynamic Islandに「N分」と表示されます。0で非表示になります。iPhoneのみ。 |
カウントダウン
| フィールド | 型 | デフォルト | 説明 |
|---|---|---|---|
countdownTo | number | なし | 目標時刻。Unixエポック秒の数値で指定します（ミリ秒やテキストは不可）。時計はスマートフォン上で進みます。時刻になると通知が送られます。 |
countdownStyle | string | auto | hms（00:00:00）、days、hours、months、years、autoのいずれか。autoは、最後の36時間は進む時計（00:00:00）を、それより前は最も大きい単位を表示します。 |
completionText | string | なし | 時刻になると時計の代わりに表示され、その通知のタイトルにもなります。省略すると、iPhoneではsecondaryText、AndroidではprimaryTextが表示されます。 |
アクションボタン
ボタンを消すには、3つのフィールドすべてを""で送ります。
| フィールド | 型 | デフォルト | 説明 |
|---|---|---|---|
actionLabel | string | なし | ボタンのテキスト（「ライブで見る」）。iPhoneでは、ピクチャーとバーサスで、ロック画面と展開したDynamic Islandに表示されます。コンパクトなDynamic Islandには表示されません。Androidでは、actionURLが設定されていればどのレイアウトでも表示されます。 |
actionURL | string | なし | ボタンで開くhttpまたはhttpsのURL。それ以外のURLは破棄されます。 |
actionColorHex | string | 赤（バーサス）、オレンジ（ピクチャー） | ボタンの色。iPhoneのみ。 |
versusオブジェクト
layoutがversusの場合に、stateの中に設定します。
| フィールド | 型 | デフォルト | 説明 |
|---|---|---|---|
leftName / rightName | string | "" | 2つの陣営の名前。 |
leftScore / rightScore | string | "0" | スコアはテキストなので、「12」「$1,500」「X」のどれでも使えます。数値はテキストに変換されます。 |
leftStatus / rightStatus | string | "" | 各名前の下の小さい行（「勝利」）。 |
activeSide | string | なし | "left"または"right"。Dynamic Islandが最小表示のときに、その側のロゴを表示します。 |
leftColorHex / rightColorHex | string | 文字色 | 各陣営のスコアの色。iPhoneのみ。 |
centerLabel | string | なし | 中央の小さいテキスト（「マップ」）。 |
centerValue | string | なし | その下の値（「Overpass」）。 |
leftImageUrl / rightImageUrl | string | なし | 2つのロゴ。透明なPNGがきれいに表示されます。 |
centerImageUrl | string | なし | 中央の画像（オークションの品、マップなど）。 |
sourceLogoUrl | string | なし | リーグまたはブランドのロゴ。iPhoneの下部ストリップ、Apple Watchのタイル、Androidのアイコンに使われます。 |
brandオブジェクト
任意。start呼び出しのトップレベルで設定します。あとからPOST /api/brandingで変更できます。ブランド名の下に表示されるサイトは、起動ボタンを置いたページから決まるので、ブランドのフィールドではありません。
| フィールド | 型 | 説明 |
|---|---|---|
title | string | アプリの一覧に表示されるアクティビティ名。省略するとnameが使われます。 |
name | string | ブランド名（「Acme」）。アプリ、バーサスの下部ストリップに表示され、primaryTextが空の場合は通知のタイトルになります。省略するとソース名は表示されません。 |
logo | string | アプリのカバーに使うロゴのURL。省略するとheaderIconUrl、それもなければWebActivityのロゴが使われます。 |
description | string | カバーのタイトルの下の短い行。省略するとsecondaryTextが使われます。 |
color | string | #RRGGBB形式のブランドカラー。ステートにない場合はaccentColorHexに設定されます。 |
