useAddToHomescreen()

useAddToHomescreen() 是 <SwAddToHomescreenGuide> 內部使用的 composable，封裝了 PWA 加入主畫面引導的顯示決策 + 生命週期管理：UA 偵測、設定讀取、會話/持久化記憶、延時觸發等。所有 window / navigator 存取都包在 onMounted + import.meta.client 內，SSR 安全。

業務側通常不直接呼叫——掛載 <SwAddToHomescreenGuide /> 即可獲得完整能力。僅當業務希望完全自訂引導 UI（不用 framework 的 bottom-sheet）時才需要直接消費此 composable。

顯示決策（全部滿足才回傳 `open=true`）

下面的探測器展示你當前的訪問環境對各道閘的判定（桌面瀏覽器通常卡在閘 ④）：

加载中...

客戶端環境（import.meta.client）
PWA 已啟用（runtimeConfig.public.swiftWebFramework.pwa.enabled）
addToHomescreen 未被顯式關閉
不在 standalone 模式（使用者尚未把站點加到主畫面）
UA 可明確判定為 iOS Safari 或 Android Chromium 主流瀏覽器
使用者最近"沒被記住關閉"（由 rememberFor 決定）

基本用法

<script setup lang="ts">
const { open, platform, dismiss } = useAddToHomescreen({
  delay: 2000,
  rememberFor: 'session',
})
</script>

<template>
  <Teleport to="body">
    <div v-if="open" class="my-custom-guide">
      <p v-if="platform === 'ios'">點擊 Safari 工具列的「分享」→「加入主畫面」</p>
      <p v-else-if="platform === 'android'">點擊右上角選單 →「加入主畫面」</p>
      <button @click="dismiss">關閉</button>
    </div>
  </Teleport>
</template>

設定入口

useAddToHomescreen({
  delay: 3000,        // 可選，mount 後多久彈（毫秒）。預設走 runtimeConfig 或 2000
  rememberFor: '7d',       // 可選，記憶多久。預設走 runtimeConfig 或 'session'
})

參數	類型	預設值	說明
`delay`	`number`	`2000`	mount 後多久彈出。優先順序：參數 > runtimeConfig > 2000
`rememberFor`	`'session' \| PeriodSpec`	`'session'`	記憶策略。`'session'` = sessionStorage；`'Nm'`·`'Nh'`·`'Nd'` = N 分·時·天內不再彈；`'0d'` = 不記憶
`trackInstall`	`{ traceId?: string }`	`undefined`	PWA 安裝成功埋點（opt-in）：傳入即監聽 `appinstalled`，經 `useTracker` 上報 WebSDK `appInstall`（`trace_id` 取 `traceId`，缺省空字串）。僅需 PWA 啟用，不受引導顯示閘影響（使用者從瀏覽器選單安裝也計入）；不傳零行為

回傳值

名稱	類型	說明
`open`	`Ref<boolean>`	引導是否顯示。延時到點後自動置 `true`，呼叫 `dismiss()` 後置 `false`
`platform`	`Ref<'ios' \| 'android' \| null>`	目前裝置引導目標平台。`null` 表示不彈（應該被外層 `v-if="open"` 兜底）
`dismiss`	`() => void`	主動關閉引導。僅改變 `open`，是否記憶已在 `open` 觸發時寫入

儲存 key

模式	儲存	Key	資料
`rememberFor: 'session'`	sessionStorage	`<cachePrefix>sw:a2hs:shown`	`boolean`（AES 加密）
`rememberFor: N`（正數）	localStorage	`<cachePrefix>sw:a2hs:dismissedAt`	`number` timestamp（AES 加密）

兩種模式的 key 不同，切換 rememberFor 時不會衝突。<cachePrefix> 來自 runtimeConfig.public.cachePrefix（多專案共用網域時自動隔離）。

注意事項

此 composable 僅供 <SwAddToHomescreenGuide> 內部使用，自訂 UI 時也可消費，但 framework 不保證回傳值的穩定性（patch 版本可能微調）
記錄"已彈"的時機是 setTimeout 觸發那一刻（open 變 true 時），即便使用者沒看到（分頁失焦等）也算一次"已展示"。這避免了"使用者秒關卻沒記錄導致下次又彈"的體驗問題
PWA 未啟用時（pwa.enabled === false），dev 模式 console 會有 warn 提示要嘛啟用 PWA、要嘛從 app.vue 註解 / 刪除掛載點