Airaw Widget API

The Airaw Widget API is a JavaScript bridge that allows HTML widgets displayed on CarPlay to retrieve real-time iOS system data — battery, network, music, weather, and more.

Airaw Widget API は、CarPlay 上に表示される HTML ウィジェットが iOS システム情報（バッテリー・ネットワーク・音楽・天気など）を リアルタイムで取得するための JavaScript ブリッジです。

Communication is bidirectional. The widget requests data via WKScriptMessageHandler (airawAction) — or the injected helper airawRequest(method) — which avoids touching window.location. The legacy arapi: URL scheme is still supported for compatibility. Airaw responds by injecting global variables and calling mainUpdate(type).

通信は双方向です。データ要求は WKScriptMessageHandler（airawAction）、または注入済みの airawRequest(method) を推奨します（window.location を汚しません）。 互換のため従来の arapi: URL スキームも利用できます。 Airaw がグローバル変数を注入した上で mainUpdate(type) を呼び出します。

Architectureアーキテクチャ

The data flow between the widget and Airaw is shown below.

Widget ↔ Airaw 間のデータフローを示します。

Communication Model通信モデル

Quick Startクイックスタート

Minimal widget implementation example.

最小構成のウィジェット実装例です。

<!-- Request all data on page load -->
<script>
window.addEventListener('load', function() {
  // Recommended: injected helper (uses postMessage internally)
  airawRequest('arcall_all');
  // Legacy: window.location = 'arapi:arcall_all';
});

// Airaw calls this after injecting variables
function mainUpdate(type) {
  if (type === 'battery') {
    document.getElementById('bat').textContent = batteryPercent + '%';
  }
  if (type === 'weather') {
    document.getElementById('temp').textContent = weather.temperature + '°C';
  }
}
</script>

Widget Options (airaw-widget-schema.json)ウィジェットオプション（airaw-widget-schema.json）

Place a schema file named airaw-widget-schema.json in the same folder as your widget HTML. Airaw reads it to build a settings UI and injects the merged values into the WebView as window.AIRAW_WIDGET_OPTIONS. User overrides are persisted under /var/jb/Library/Airaw/WidgetOptions/ on rootless setups (path may vary by jailbreak).

ウィジェットの HTML と同じフォルダに airaw-widget-schema.json を置きます。 Airaw がスキーマを読み取り設定画面を生成し、マージ結果を WebView に window.AIRAW_WIDGET_OPTIONS として注入します。 ユーザーが変更した値は rootless 環境では /var/jb/Library/Airaw/WidgetOptions/ 以下に保存されます（JB により実パスは異なる場合があります）。

Schema shapeスキーマの形

Top-level keys such as widgetId / version are optional metadata for authors. Airaw uses the properties object to generate prefs cells and defaults.

ルートの widgetId や version は作者向けメタデータとして任意です。 設定 UI と既定値には properties オブジェクトが使われます。

{
  "widgetId": "com.example.mywidget",
  "version": 1,
  "properties": {
    "accentColor": {
      "type": "string",
      "default": "#4fc3f7",
      "label": "Accent color (#hex)"
    },
    "compactCards": {
      "type": "boolean",
      "default": false,
      "label": "Compact cards"
    }
  }
}

Storage identifier (slug)保存キー（スラッグ）

Overrides are stored under /Library/Airaw/WidgetOptions/ (rootless prefix applied by the jailbreak). The plist basename starts from the HTML path’s folder names: xenhtml.<parent>.<folder> (segments lowercased). Example: …/MyPack/widget/index.html → xenhtml.mypack.widget.plist. If your schema defines a non-empty widgetId, Airaw appends a sanitized segment so different widgets under the same folder path do not collide: xenhtml.mypack.widget.<sanitized-widgetId>.plist. When you add widgetId later, an existing legacy plist at the base-only filename is moved to the new name on first access so user settings are preserved.

保存先は（rootless ではプレフィックス付きの）/Library/Airaw/WidgetOptions/ です。 ベース名は HTML のフォルダから xenhtml.<親>.<フォルダ>（小文字）。例: …/MyPack/widget/index.html → xenhtml.mypack.widget.plist。 スキーマに空でない widgetId がある場合は衝突回避のため xenhtml.mypack.widget.<sanitized-widgetId>.plist のように続けます。 後から widgetId を追加した場合、既存のレガシー plist は初回アクセス時に新ファイル名へ移動され、設定は引き継がれます。

JavaScript APIJavaScript からの利用

function applyOptions(o) {
  if (!o) return;
  document.documentElement.style.setProperty('--accent', o.accentColor || '#4fc3f7');
  document.body.classList.toggle('compact', !!o.compactCards);
}

window.addEventListener('airawwidgetoptions', function(e) {
  applyOptions(e.detail);
});

window.onAirawWidgetOptions = applyOptions;

// Initial paint if already injected before listeners ran
if (typeof window.AIRAW_WIDGET_OPTIONS !== 'undefined') {
  applyOptions(window.AIRAW_WIDGET_OPTIONS);
}

Settings UI設定アプリでの操作

Open Airaw’s screen where you configure CarPlay widget placement for your HTML widget. When the schema file is present, a group titled HTML widget options lists switches, sliders, or text fields per property. Tap Apply to push changes to CarPlay / refresh the WebView.

Airaw のCarPlay 上のウィジェット配置を編集する設定画面で、その HTML ウィジェットを開きます。 スキーマがある場合、HTMLウィジェットのオプションというグループにスイッチ・スライダー・テキストなどが現れます。 変更を反映するには Apply をタップしてください。

Trigger APIsトリガー API

Call Airaw from JavaScript to refresh widget data. Prefer airawRequest(method) or postMessage so the webview does not navigate. The arapi: URL form remains supported as a legacy fallback.

JavaScript から Airaw にデータ取得を依頼します。airawRequest(method) または postMessage を推奨します（WebView がナビゲーションしないため）。 arapi: 形式はレガシー互換として残ります。

airawRequest('arcall_Battery');
// postMessage: window.webkit.messageHandlers.airawAction.postMessage({ action: 'requestData', method: 'arcall_Battery' });
// legacy: window.location = 'arapi:arcall_Battery';

airawRequest('arcall_Statusbar');
// postMessage … method: 'arcall_Statusbar'
// legacy: window.location = 'arapi:arcall_Statusbar';

airawRequest('arcall_Music');
// postMessage … method: 'arcall_Music'
// legacy: window.location = 'arapi:arcall_Music';

airawRequest('arcall_Weather');
// postMessage … method: 'arcall_Weather'
// legacy: window.location = 'arapi:arcall_Weather';

airawRequest('arcall_System');
// postMessage … method: 'arcall_System'
// legacy: window.location = 'arapi:arcall_System';

airawRequest('arcall_all');
// postMessage … method: 'arcall_all'
// legacy: window.location = 'arapi:arcall_all';

Callbacks — mainUpdate(type)コールバック — mainUpdate(type)

After collecting data, Airaw injects global variables and calls mainUpdate(type). Use type to identify the category and read the corresponding variables.

Airaw はデータ収集後、グローバル変数を注入してから mainUpdate(type) を呼び出します。 type で対象カテゴリを判別し、各変数を読み取ります。

function mainUpdate(type) {
  if (type === 'battery') {
    const pct = typeof batteryPercent !== 'undefined' ? batteryPercent : 0;

    document.getElementById('pct').textContent  = pct + '%';
    document.getElementById('icon').style.display = batteryCharging ? 'block' : 'none';

    // Connected devices (AirPods, etc.)
    if (bateryInfo?.devices?.length) {
      bateryInfo.devices.forEach(d => console.log(d.deviceName, d.batteryPercent));
    }
  }
}

function mainUpdate(type) {
  if (type === 'music') {
    const playing = typeof isplaying !== 'undefined' ? !!isplaying : (title !== '');
    const dur     = parseFloat(currentDuration)    || 0;
    const elapsed = parseFloat(currentElapsedTime) || 0;
    const pct     = dur > 0 ? (elapsed / dur) * 100 : 0;

    document.getElementById('title').textContent  = playing ? title  : 'Not Playing';
    document.getElementById('artist').textContent = playing ? artist : '';
    document.getElementById('bar').style.width    = pct + '%';

    // App name + icon (iOS 16+)
    const appLabel = typeof PlayingApplicationName !== 'undefined' && PlayingApplicationName
      ? PlayingApplicationName
      : (PlayingApplication || '');
    const appNameEl = document.getElementById('appName');
    if (appNameEl) appNameEl.textContent = appLabel;

    const appIcon = document.getElementById('appIcon');
    if (appIcon) {
      if (typeof playingAppIconUrl !== 'undefined' && playingAppIconUrl) {
        appIcon.src = playingAppIconUrl;
        appIcon.style.display = 'block';
      } else {
        appIcon.style.display = 'none';
      }
    }

    // iOS 16+: use artworkUrl (HTTP). Do not rely on Documents path.
    const img = document.getElementById('artwork');
    if (img) {
      if (playing && typeof artworkUrl !== 'undefined' && artworkUrl) {
        img.src = artworkUrl;
        img.style.display = 'block';
      } else {
        img.style.display = 'none';
      }
    }
  }
}

function mainUpdate(type) {
  if (type === 'weather') {
    if (typeof weather === 'undefined') return;

    const unit = weather.celsius === 'C' ? '°C' : '°F';
    document.getElementById('temp').textContent = weather.temperature + unit;
    document.getElementById('city').textContent = weather.city;

    // 7-day forecast
    const days = ['Sun','Mon','Tue','Wed','Thu','Fri','Sat'];
    weather.dayForecasts?.slice(0, 7).forEach(f => {
      console.log(days[f.dayOfWeek], f.high + unit, f.low + unit);
    });
  }
}

function mainUpdate(type) {
  if (type === 'CarPlay') {
    // Animate only when on page 0
    document.body.style.opacity = (pageIndex === 0) ? '1' : '0.4';
  }
}

Condition Codes天気コード（conditionCode）一覧

Numeric codes used by weather.conditionCode, dayForecasts[].icon, and hourlyForecasts[].conditionCode. Follows the Apple Weather framework (formerly WeatherData) definition.

weather.conditionCode / dayForecasts[].icon / hourlyForecasts[].conditionCode で使用される数値コードです。 Apple Weather フレームワーク（旧 WeatherData）の定義に従います。

Emoji mapping function絵文字マッピング関数の実装例

function weatherEmoji(code) {
  const c = parseInt(code, 10);
  if (c <= 1)  return '🌪';
  if (c <= 3)  return '⛈';
  if (c <= 12) return '🌧';
  if (c <= 17) return '⛈';
  if (c === 19) return '🌫';
  if (c <= 22) return '💨';
  if (c <= 30) return '🌨';
  if (c === 31 || c === 33) return '🌙';
  if (c === 32 || c === 34) return '☀️';
  if (c === 36) return '🌡';
  if (c <= 40) return '🌦';
  if (c <= 43) return '🌩';
  return '⛅';
}

Artwork Imageアートワーク画像の取得

iOS 16+ (recommended) — artworkUrliOS 16+（推奨）— artworkUrl

On iOS 16+, CarPlay widgets often run inside CarPlayWallpaper, which cannot read /var/mobile/Documents/ (sandbox). Airaw therefore serves artwork over a local HTTP server on SpringBoard and injects an HTTP URL as artworkUrl when calling mainUpdate('music').

iOS 16 以降、CarPlay ウィジェットは多くの場合 CarPlayWallpaper 上で動作し、 サンドボックスのため /var/mobile/Documents/ を直接読めません。 Airaw は SpringBoard 側のローカル HTTP でアートを配信し、 mainUpdate('music') 時に変数 artworkUrl として注入します。

// Injected example
artworkUrl = 'http://localhost:18765/AirawMedia/MusicArt.png?t=1710000000000';

// Recommended (iOS 16+ CarPlay widget)
function mainUpdate(type) {
  if (type !== 'music') return;
  const img = document.getElementById('artwork');
  if (!img) return;

  if (typeof artworkUrl !== 'undefined' && artworkUrl) {
    img.onerror = function() { this.style.display = 'none'; };
    img.onload  = function() { this.style.display = 'block'; };
    img.src = artworkUrl;  // already includes ?t=
  } else {
    img.style.display = 'none';
  }
}

Legacy path (not for iOS 16+ CarPlayWallpaper)レガシー経路（iOS 16+ CarPlayWallpaper では非推奨）

Airaw still writes a copy to the Documents path for older environments / Prefs preview. Do not rely on this path inside iOS 16+ CarPlayWallpaper widgets — the file is not readable there.

互換のため Documents にもコピーしますが、 iOS 16+ の CarPlayWallpaper ウィジェットではこのパスに依存しないでください（読めません）。

/var/mobile/Documents/MusicArt.png

// Legacy only (Prefs preview / older hosts that can read Documents)
const img = document.getElementById('artwork');
img.src = '/var/mobile/Documents/MusicArt.png?t=' + Date.now();
img.onerror = function() { this.style.display = 'none'; };

Best Practices実装のヒント

1. Safe variable access1. 安全な変数アクセス

Airaw always injects variables before calling mainUpdate, but use typeof checks for safety when opening the HTML file directly during development.

Airaw は変数を注入してから mainUpdate を呼びますが、開発・デバッグ時に 直接 HTML を開く場合に備え、typeof チェックを推奨します。

// Recommended pattern
const pct = typeof batteryPercent !== 'undefined' ? batteryPercent : 0;

// Nullish coalescing (modern browsers)
const temp = weather?.temperature ?? '--';

2. Periodic polling2. 定期更新の実装

Airaw notifies automatically on changes, but you can also poll at a fixed interval.

Airaw は変化があった際に自動で通知しますが、一定間隔でポーリングすることもできます。

// Refresh all data every 30 seconds
setInterval(function() {
  if (typeof airawRequest === 'function') {
    airawRequest('arcall_all');
  } else {
    window.location = 'arapi:arcall_all';
  }
}, 30000);

3. mainUpdate template3. mainUpdate のテンプレート

function mainUpdate(type) {
  switch (type) {
    case 'battery':
      /* batteryPercent, batteryCharging, batteryLowPowerMode,
         batteryCycles, batteryHealth, batteryVoltage,
         batteryCelsius, bateryInfo */
      break;
    case 'statusbar':
      /* signalBars, signalName, wifiBars, wifiName,
         signalNetworkType */
      break;
    case 'music':
      /* title, artist, album, currentDuration,
         currentElapsedTime, PlayingApplication, PlayingApplicationName,
         isplaying, artworkUrl, playingAppIconUrl (iOS 16+ HTTP) */
      break;
    case 'weather':
      /* weather.{ temperature, city, condition, humidity,
         windSpeed, uvIndex, high, low, celsius,
         dayForecasts[], hourlyForecasts[] ... } */
      break;
    case 'system':
      /* deviceName, deviceType, systemVersion, ipAddress,
         ramFree, ramUsed, ramTotal */
      break;
    case 'CarPlay':
      /* pageIndex */
      break;
  }
}

window.addEventListener('load', function() {
  if (typeof airawRequest === 'function') {
    airawRequest('arcall_all');
  } else {
    window.location = 'arapi:arcall_all';
  }
});

4. Demo data for development4. デバッグ用デモデータ

To develop the UI without a real device, refer to the fillRandom() function in airaw-sample-widget.html. It injects demo values into all fields without making any API calls.

実デバイスなしで UI 開発を進める場合は、airaw-sample-widget.html の fillRandom() 関数を参考にしてください。 API 呼び出しを一切せずにすべてのフィールドにデモ値を注入できます。

5. Widget options alongside API data5. API データと並行するウィジェットオプション

User-configurable widget options (schema file + window.AIRAW_WIDGET_OPTIONS) are independent of data triggers (requestData / airawRequest / legacy arapi:) and mainUpdate. You can read options inside mainUpdate or react via airawwidgetoptions — see the Widget Options section.

スキーマに基づくユーザー設定（window.AIRAW_WIDGET_OPTIONS）は、データ取得（requestData / airawRequest / レガシー arapi:）や mainUpdate とは別経路です。 mainUpdate 内で参照してもよいし、airawwidgetoptions で UI を更新しても構いません。詳細はウィジェットオプションを参照してください。