LINE LIFF API - Agent Skill Hub

📱 LINE LIFF API

用於開發、調試或與 LINE Front-end Framework (LIFF) SDK 互動（包括初始化、身分驗證、取得使用者個人檔案、發送訊息和分享內容給好友）。

概述 (Overview)

此技能提供與 LINE Front-end Framework (LIFF) 用戶端 JS SDK 整合和互動的結構化參考。涵蓋 LIFF SDK 屬性、初始化、身分驗證、使用者上下文、個人檔案取得，以及分享目標選擇器 (Share Target Picker) 與條碼掃描等自訂功能。

何時使用 (When to Use)

建立在 LINE 內建 LIFF 瀏覽器或外部瀏覽器中執行的網頁應用程式。
使用 liff.init() 初始化 LIFF SDK 以取得 LINE 專屬功能。
執行使用者身分驗證 (liff.login(), liff.logout(), liff.isLoggedIn())。
獲取使用者詳細資訊 (liff.getProfile(), liff.getDecodedIDToken())。
直接向當前聊天室發送訊息 (liff.sendMessages()) 或選擇目標好友以分享內容 (liff.shareTargetPicker())。
取得執行階段環境參數（OS、語言、LINE 版本等）。

核心模式 (Core Pattern)

務必儘早呼叫 liff.init()，並在調用其他 LIFF SDK 方法之前等待傳回的 Promise 解析完成。

初始化與登入流程 (JavaScript 範例)

import liff from '@line/liff';

async function initializeLiff(liffId) {
  try {
    await liff.init({ liffId });
    if (!liff.isLoggedIn()) {
      // 若尚未登入，自動重新導向至 LINE 登入頁面
      liff.login();
    } else {
      // 登入成功後開始使用其他 SDK 功能，例如取得個人檔案
      const profile = await liff.getProfile();
      console.log('User Profile:', profile);
    }
  } catch (error) {
    console.error('LIFF 初始化失敗:', error.code, error.message);
  }
}

快速參考 (Quick Reference)

在 `liff.init()` 之前即可使用的方法

這些方法可用於在 SDK 完全初始化之前查詢環境狀態：

liff.ready (表示初始化完成的 Promise 物件)
liff.getOS() (傳回 'ios', 'android', 或 'web')
liff.getAppLanguage() (取得 LINE 應用程式的語言設定)
liff.getVersion() / liff.getLineVersion()
liff.isInClient() (檢查是否在 LINE 應用程式內執行)
liff.closeWindow() (關閉 LIFF 視窗)

核心 SDK 方法 (Core SDK Methods)

方法	傳回類型	描述
`liff.init(config)`	`Promise<void>`	使用 `liffId` 初始化 LIFF 應用程式
`liff.isLoggedIn()`	`Boolean`	檢查使用者是否已通過驗證
`liff.login(options)`	`void`	觸發 LINE 登入流程
`liff.logout()`	`void`	登出使用者
`liff.getProfile()`	`Promise<Profile>`	取得使用者個人檔案（姓名、圖片、狀態訊息）
`liff.getDecodedIDToken()`	`Object`	解碼使用者的 OIDC ID Token（包含電子郵件）
`liff.sendMessages(msgs)`	`Promise<void>`	向當前聊天室發送訊息（最多 5 則）
`liff.shareTargetPicker(msgs)`	`Promise<Response>`	開啟好友選擇器以分享訊息
`liff.openWindow(options)`	`void`	在 LIFF 瀏覽器或外部瀏覽器中開啟網址

實作步驟 (Implementation Steps)

註冊 LIFF 應用程式：在 LINE Developers 控制台建立 LINE Login 通道，並註冊您的 LIFF 應用程式以取得 LIFF ID 並設定 Endpoint URL。
匯入 SDK：透過 CDN (https://static.line-scdn.net/liff/edge/2/sdk.js) 或 npm (npm install @line/liff) 將 LIFF SDK 新增到您的專案中。
初始化：呼叫 liff.init({ liffId })。請確保僅在 init 的 Promise 解析完成之後才觸發網址變更或分析工具的頁面檢視，以防止憑證洩漏。
獲取權限範圍 (Scopes)：確保您的通道已被授予必要的權限範圍（例如 profile, openid, chat_message.write），以便調用個人檔案或傳送訊息的 API。
驗證 Token（伺服器端）：如果您需要在後端驗證使用者身分，請將原始 ID Token（透過 liff.getIDToken() 取得）或 Access Token 傳送到您的後端，並呼叫 LINE 的驗證端點。

常見錯誤 (Common Mistakes)

在初始化前呼叫方法：在 liff.init() 的 Promise 解析完成之前，即呼叫 liff.getProfile() 等方法。
Endpoint URL 路徑錯誤：在與控制台中設定的 Endpoint URL 不同（或不是其子目錄）的網址上執行 liff.init()。這會導致警告並使初始化無法正常運作。
Google Analytics 資訊洩漏：在初始化完成前，將包含使用者 Access Token 的主要重新導向網址記錄到 Google Analytics。在 LIFF v2.11.0+ 中，憑證會在解析後自動清除；請將分析記錄邏輯寫在 liff.init().then() 區塊內。
誤解 OpenChat 相容性：LIFF 應用程式在 LINE OpenChat 內大部分不相容（例如：無法取得使用者個人檔案）。
忽視外部瀏覽器限制：期望 liff.scanCode() 或 liff.sendMessages() 等功能在外部手機/電腦瀏覽器中運作（這些功能僅在 LINE 內建 LIFF 瀏覽器中受支援）。請使用 liff.isInClient() 檢查相容性。
修改 SDK 查詢參數：在初始化解析完成之前手動修改 liff.state 或 liff.referrer 等查詢參數，這會破壞 LIFF 轉跳機制。

← 返回技能庫