LINE MINI App 自訂動作按鈕實作指南

LINE MINI App 自訂動作按鈕是放在應用程式內容區的分享入口。使用者點擊後選擇好友、群組或聊天室，liff.shareTargetPicker() 再以使用者身分送出開發者準備的分享卡片。實作時要遵循 LINE 指定的 Flex Message 格式，為詳細頁使用永久連結，並分開處理成功、取消及呼叫失敗。

重點整理

• Header 內建動作按鈕會自動分享目前頁面；內容區的自訂動作按鈕則可控制分享卡片內容。
• 未認證與已認證 LINE MINI App 都能使用自訂動作按鈕，這不代表取得正式環境 Service Message 資格。
• 使用者必須已登入，且要在 LINE Developers Console 開啟 share target picker。
• 自訂分享使用一個 Flex Message bubble，不可使用 carousel。
• 只有 { status: "success" } 表示完成分享；Promise resolve 但沒有結果物件代表使用者取消。

自訂動作按鈕與其他 LINE 訊息功能的差異

LINE 官方自訂動作按鈕指南區分兩個入口。Header 的內建按鈕由 LINE 顯示，只分享當前頁面，行為與內容不能自訂。應用程式內容區的自訂按鈕，則能把開發者建立的訊息交給目標選擇器。

比較項目	自訂動作按鈕	Service Message	Messaging API
觸發方式	使用者點擊並選擇收件人	使用者完成合資格操作後由伺服器通知	Official Account 回覆或主動傳送
主要 API	liff.shareTargetPicker()	Service Message API	Messaging API
收件人看到的傳送者	分享的使用者	地區對應的 MINI App 通知聊天室	LINE Official Account
認證邊界	未認證與已認證皆可	正式環境須為已認證 MINI App	依 Official Account 規則

若要判斷功能資格，請看未認證與已認證 MINI App 比較；若要選擇通知管道，請看Service Message 與 Messaging API 比較。自訂按鈕不會增加這兩種訊息權限。

LINE MINI App 自訂動作按鈕實作清單

1. 開啟 share target picker

正常初始化 LIFF，確認使用者已登入，並在 LINE Developers Console 開啟 share target picker。官方 LIFF API Reference列明這兩項條件。

顯示按鈕前先檢查 liff.isApiAvailable("shareTargetPicker")。在手機外部瀏覽器，目標選擇器還需要 SSO 登入 session；只有 auto login 時可能跳出電子郵件登入畫面。LIFF browser 與使用者實際進入的外部瀏覽器都要驗證。

2. 依規格建立 Flex Message

自訂分享必須使用單一 Flex Message bubble，不能用 carousel。卡片需要標題、subtitle 或 detail、按鈕區，以及識別 MINI App 的 footer。元件屬性要依官方指定配置，不能任意改造範例。

按鈕最多三個，至少一個要開啟分享內容的詳細頁。Footer 顯示 MINI App 圖示與名稱，並以 URI action 返回首頁。

3. 詳細頁使用永久連結

要重新開啟 MINI App 內指定頁面時，不要直接使用一般網站 endpoint URL。LINE 的永久連結說明提供以下公式：

LIFF URL +（MINI App 頁面 URL - Endpoint URL）= 永久連結

若 LIFF URL 為 https://miniapp.line.me/123456-abcdefg，頁面為 https://example.com/orders/42?from=share，連結就是：

https://miniapp.line.me/123456-abcdefg/orders/42?from=share

永久連結可包含 path、query 與 hash。請在 LINE 裡測試未登入、訂單過期與內容已刪除等狀態。Header 內建按鈕會自動產生當前頁面的永久連結，自訂卡片按鈕則要自行建立。

4. 從明確的使用者點擊呼叫

卡片資料應來自伺服器已核對權限的業務記錄，不要直接信任 URL 參數。控制流程可分成：

async function shareItem(messages) {
  if (!liff.isApiAvailable("shareTargetPicker")) {
    return { outcome: "unavailable" };
  }

  try {
    const result = await liff.shareTargetPicker(messages);
    return result?.status === "success"
      ? { outcome: "shared" }
      : { outcome: "cancelled" };
  } catch (error) {
    return { outcome: "failed", error };
  }
}

messages 必須放入符合現行 LINE 指南的 Flex Message bubble。

5. 分辨成功、取消與錯誤

結果	API 行為	介面處理
已分享	以 { status: "success" } resolve	只顯示分享動作完成，不宣稱對方已查看
使用者取消	resolve 但沒有結果物件	返回原頁，不顯示錯誤
選擇器顯示前失敗	reject 並帶 LiffError	記錄安全錯誤碼，提供重試或內建分享入口

LINE 不提供目標選擇器的收件人數。不能把成功結果當成送達人數、瀏覽數或轉換資料。

6. 進行實機驗收

至少測試已登入/未登入、LIFF browser/手機外部瀏覽器、功能開啟/關閉、單一/多個目標、取消、有效/過期深層連結，以及較長的繁體中文內容。可選目標包含好友、群組與聊天室，不包含 OpenChat。

UnifyPort 的適用範圍

UnifyPort 不實作 liff.shareTargetPicker()，也不建立 LINE 目標選擇器、驗證 Flex Message 版面或提供分享對象分析。這些屬於官方 LINE MINI App 與 LIFF 流程。

UnifyPort 處理另一個動作：客戶向已連接的普通 LINE 帳號傳送訊息。支援的訊息可作為標準化 message.received 事件送達；Webhook endpoint 設定 signing_secret 後，可用 X-Device-Timestamp 與 X-Device-Signature 驗證 HMAC-SHA256 簽章。

若分享頁面日後帶來客服對話，請把分享動作、訂單或活動 ID、入站對話保留為不同記錄，再由系統關聯。實作前查看 LINE 授權指南及訊息支援矩陣。

限制與取捨

• 只分享當前頁面時，優先使用可自動產生永久連結的 Header 內建按鈕。
• 需要引導式分享卡片時才選自訂按鈕，因為它增加版面、連結、登入與裝置測試工作。
• 不能靜默傳送、自動選擇收件人、證明送達或取得收件人數。
• 它不是 Service Message、Messaging API、Official Account 或客服訊息接收的替代品。

FAQ

未認證 LINE MINI App 可以使用自訂動作按鈕嗎？

可以。LINE 現行功能表將自訂動作按鈕列為未認證與已認證皆可用；正式環境 Service Message 是另一項只限已認證應用程式的功能。

內建與自訂動作按鈕有何不同？

內建 Header 按鈕分享目前頁面，內容不能修改；自訂內容按鈕把符合指南的開發者訊息交給 liff.shareTargetPicker()。

可以取得分享收件人數嗎？

不可以。LINE 基於隱私不收集也不提供透過目標選擇器分享的收件人數。

為何 Promise resolve 後沒有 status？

使用者在傳送前關閉選擇器時，Promise 會 resolve 但沒有結果物件。這是取消，不是 API 錯誤。

詳細頁按鈕該使用哪個 URL？

首頁以外應使用永久連結。它可帶 path、query 或 hash，並讓使用者回到 MINI App 內的指定頁面。

下一步

依 LINE 官方自訂動作按鈕實作指南完成卡片與實機驗收。若另有普通 LINE 客戶訊息接收需求，再從 UnifyPort LINE 授權指南評估獨立路徑。

資料來源

以下 LINE 官方資料於 2026-08-08 核對：

• Implementing a custom action button
• LIFF API Reference：liff.shareTargetPicker()
• Creating permanent links
• Custom features