LINE MINI App 自定义操作按钮实现指南

LINE MINI App 自定义操作按钮是放在应用正文里的主动分享入口。用户点击后选择好友、群组或聊天，liff.shareTargetPicker() 再以用户身份发送开发者准备的分享卡片。实现时应遵循 LINE 指定的 Flex Message 格式，为详情页使用永久链接，并把成功、取消和调用失败当作三种不同结果。

核心结论

• 顶部内置操作按钮自动分享当前页面；正文里的自定义操作按钮可以控制分享卡片内容。
• 未认证和已认证的 LINE MINI App 都可使用自定义操作按钮，它与生产环境 Service Message 资格无关。
• 用户必须已登录，并且需要在 LINE Developers Console 启用 share target picker。
• 自定义分享卡片使用一个 Flex Message bubble，不能使用 carousel。
• 只有 { status: "success" } 表示完成分享；Promise 成功结束但没有结果对象表示用户取消。

自定义操作按钮解决什么问题

LINE 官方的自定义操作按钮指南区分了两种入口。Header 里的内置按钮由 LINE 展示，只分享当前页面，行为和内容不可定制。应用正文里的自定义按钮则可将开发者构造的消息交给目标选择器。

维度	自定义操作按钮	Service Message	Messaging API
触发者	用户点击并选择接收人	用户完成合资格操作后由服务端通知	Official Account 回复或主动发送
主要 API	MINI App 内的 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 登录会话；仅有 auto login 时可能出现邮箱登录界面。应分别测试 LIFF browser 和真实用户会走的外部浏览器路径。

2. 按 LINE 规则构造 Flex Message

自定义分享必须使用单个 Flex Message bubble，不能使用 carousel。卡片需要标题、subtitle 或 detail、按钮区以及品牌 footer。不要把示例当成可任意修改的 Flex 画布，应逐项遵循官方指定的组件属性。

按钮最多三个，至少一个要打开被分享内容的详情页。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. 从明确的用户点击调用 API

卡片内容应来自服务端已校验权限的业务记录，不要直接信任 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" }	只提示分享操作完成，不宣称对方已查看
用户取消	Promise resolve，但没有结果对象	安静返回原页面，不弹错误
选择器显示前失败	Promise 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