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 官方自訂動作按鈕指南把兩個分享入口分開。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 核對：