# LIFF v2 APIリファレンス
# 共通仕様
# 動作環境
LIFF v2の動作環境については、『LIFFドキュメント』の「概要」を参照してください。
なお、LIFFアプリをLIFFブラウザで開いた場合と、外部ブラウザで開いた場合では、使用できる機能が異なります。たとえば、liff.scanCode()は、外部ブラウザでは利用できません。詳しくは、各クライアントAPIの説明をご覧ください。
現在のところ、OpenChatではLIFFアプリの利用は正式にサポートされていません。たとえば、LIFFアプリからプロフィール情報を取得できない場合があります。
# LIFF SDKのエラー
# LiffErrorオブジェクト
code
String
エラーコード
message
String
エラーメッセージ。定義されたメッセージが存在する場合に返されます。
# エラー内容
| エラーコード | 説明 |
|---|---|
| 400 | リクエストに問題があります。リクエストパラメータとJSONの形式を確認してください。 |
| 401 | Authorizationヘッダーを正しく送信していることを確認してください。 |
| 403 | APIを使用する権限がありません。ご契約中のプランやアカウントに付与されている権限を確認してください。 |
| 429 | リクエスト頻度をレート制限内に抑えてください。 |
| 500 | APIサーバーの一時的なエラーです。 |
| INIT_FAILED | LIFF SDKの初期化時にエラーが発生しました。 |
| INVALID_ARGUMENT | 無効な引数が指定されました。 |
| UNAUTHORIZED |
|
| FORBIDDEN |
|
| INVALID_CONFIG | 無効な設定です。
|
| INVALID_ID_TOKEN | IDトークンが正規のものであることを確認できませんでした。 |
| EXCEPTION_IN_SUBWINDOW | サブウィンドウで問題が発生しました。
|
| THINGS_NO_LINKED_DEVICES | デバイスがありません。 |
| BLUETOOTH_SETTING_OFF | Bluetooth機能がオフになっています。 |
| THINGS_TERMS_NOT_AGREED | ユーザーがLINE Thingsの利用規約に同意していません。 |
| BLUETOOTH_NO_LOCATION_PERMISSION | ユーザーが位置情報の取得を許可していません。 |
| BLUETOOTH_LOCATION_DISABLED | 位置情報取得機能がオフになっています。 |
| BLUETOOTH_LE_API_UNAVAILABLE | LIFFのBluetoothプラグインが使用できません。 |
| BLUETOOTH_CONNECT_FAILED | デバイスとの接続に失敗しました。 |
| BLUETOOTH_ALREADY_CONNECTED | デバイスは接続済みです。 |
| BLUETOOTH_CONNECTION_LOST | デバイスが接続されていません。 |
| BLUETOOTH_UNSUPPORTED_OPERATION | 指定したcharacteristicでは、指定した操作がサポートされていません。 |
| BLUETOOTH_SERVICE_NOT_FOUND | 指定したサービスが、GATTサーバーに存在しません。 |
| BLUETOOTH_CHARACTERISTIC_NOT_FOUND | 指定したcharacteristicが、サービスに存在しません。 |
| UNKNOWN | 不明なエラーです。 |
# LIFF SDKのプロパティ
# liff.id
liff.init()に渡したLIFFアプリID（String型）を保持するプロパティです。
liff.init()を実行するまでは、nullです。
# liff.ready
LIFFアプリ起動後、liff.init()の実行が初めて終了したときにresolveするPromiseオブジェクトを保持するプロパティです。
liff.readyを利用すると、liff.init()の終了を待って、任意の処理を実行できます。
liff.readyは、liff.init()によるLIFFアプリの初期化が終了する前でも実行できます。
liff.init()実行中に何か問題が起きても、liff.readyはrejectしません。また、LiffErrorオブジェクトを返すこともありません。
# 初期化
# liff.init()
LIFFアプリを初期化します。このメソッドを実行すると、LIFF SDKの他のメソッドを実行できるようになります。このとき、LIFF SDKは、現在のユーザーのアクセストークンやIDトークンをLINEプラットフォームから取得します。
- LIFF SDKが取得したアクセストークンを利用するには、「liff.getAccessToken()」を呼び出します。
- LIFF SDKが取得したIDトークンのペイロードを利用するには、「liff.getDecodedIDToken()」を呼び出します。
liff.init()メソッドは、1次リダイレクト先URLに付与されるliff.stateやaccess_token=xxxなどの情報を元に初期化処理を行います。エンドポイントURLにクエリパラメータやパスが含まれている場合、正しくLIFFアプリを初期化するために、1次リダイレクト先URLと2次リダイレクト先URLで、1回ずつliff.init()メソッドを実行してください。リダイレクトについて詳しくは、「LIFF URLにアクセスしてからLIFFアプリが開くまでの動作について」を参照してください。liff.init()メソッドが返すPromiseオブジェクトがresolveする前に、サーバーやフロントエンド側の処理などでURLを変更しないようにしてください。URLを変更すると、INIT_FAILEDが返され、LIFFアプリを開けません。たとえば、liff.init()実行後にlocation.replace()などでリダイレクトする場合は、Promiseオブジェクトがresolveされてから画面遷移するように設計してください。liff.init({ liffId: myLiffId }).then(() => { // Redirect to another page after the returned Promise object has been resolved location.replace("https://line.me/{liffId}/path"); });1次リダイレクト先URLに自動的に付与される
access_token=xxxはユーザーのアクセストークン（機密情報）です。Google Analyticsなど外部のロギングツールに、1次リダイレクト先URLを送らないように注意してください。
なお、LIFF v2.11.0以降のバージョンでは、liff.init()がresolveされたタイミングでURLから機密情報が除外されます。そのため、以下のようにthen()メソッド内でページビューを送信することで、機密情報の漏洩を防ぐことができます。ロギングツールを利用する場合は、LIFFアプリをv2.11.0以降にバージョンアップすることをお勧めします。LIFF v2.11.0の更新内容について詳しくは、『LIFFドキュメント』の「リリースノート」を参照してください。liff.init({ liffId: myLiffId }).then(() => { ga("send", "pageview"); });
LIFF URLへのアクセス時やLIFF間遷移時などに、URLに liff.* のようなクエリパラメータが付与されることがあります。
例：
liff.state（LIFF URLに指定した追加情報を示す）liff.referrer（LIFF間遷移前のURLを示す。詳しくは、「LIFF間遷移前のURLを取得する」を参照してください）
上記は、LIFFアプリを正常に動作させるために、SDK側から付与されるクエリパラメータです。 LIFFアプリのURLに独自の処理を行う場合は、LIFFアプリの起動やLIFF間遷移などLIFFアプリの正常な動作を保証するため、liff.initがresolveされるまでliff.*のクエリパラメータを変更しないように設計してください。
以下のプロパティおよびメソッドは、liff.init()メソッドを実行する前でも利用できます。
LIFFアプリを初期化する前にLIFFアプリを動作させている環境を取得したり、LIFFアプリ初期化に失敗した際にLIFFアプリを閉じたりできます。
- liff.ready
- liff.getOS()
- liff.getLanguage()
- liff.getVersion()
- liff.getLineVersion()
- liff.isInClient()
- liff.closeWindow()
- liff.use()
- liff.i18n.setLang()
liff.closeWindow()メソッドは、LIFF SDKバージョンが2.4.0以上の場合のみ、liff.init()によるLIFFアプリの初期化が終了する前でも実行できます。
# 構文
liff.init(config, successCallback, errorCallback);
# 引数
config
Object
LIFFアプリの設定
config.liffId
String
LIFFアプリID。LIFFアプリをチャネルに追加すると取得できます。詳しくは、「LIFFアプリをチャネルに追加する」を参照してください。
ここで指定したLIFFアプリIDは、liff.idで取得できます。
config.withLoginOnExternalBrowser
Boolean
外部ブラウザでのLIFFアプリ初期化時にliff.login()メソッドを自動で実行するかどうかを、以下のどちらかの値で指定します。デフォルト値はfalseです。
true：外部ブラウザでliff.login()メソッドを自動で実行します。false：外部ブラウザでliff.login()メソッドを自動で実行しません。
successCallback
Function
LIFFアプリの初期化に成功したときにデータオブジェクトを返すコールバック
successCallbackは、戻り値のPromiseオブジェクトのresolveと同じタイミングで処理されます。ただし、処理の順番は保証されません。
errorCallback
Function
LIFFアプリの初期化に失敗したときにエラーオブジェクトを返すコールバック
errorCallbackは、戻り値のPromiseオブジェクトのrejectと同じタイミングで処理されます。ただし、処理の順番は保証されません。
# 戻り値
Promiseオブジェクトが返されます。
# エラーレスポンス
Promiseがrejectされたときは、LiffErrorが渡されます。
# 動作環境の取得
# liff.getOS()
ユーザーがLIFFアプリを動作させている環境を取得します。
このメソッドは、liff.init()によるLIFFアプリの初期化が終了する前でも実行できます。
# 構文
liff.getOS();
# 引数
なし
# 戻り値
ユーザーがLIFFアプリを動作させている環境が、文字列で返されます。戻り値はユーザーエージェント文字列中のOS名に基づくため、返却される値はブラウザの種類（LIFFブラウザ、LINE内ブラウザ、外部ブラウザ）を問いません。
たとえば、ユーザーがiOSを使用している場合、使用しているブラウザがLIFFブラウザかSafariかは問わず、ios が返却されます。
| 戻り値 | 説明 |
|---|---|
| ios | iOSもしくはiPadOS |
| android | Android |
| web | 上記以外 |
LIFFアプリをサポートするOSやブラウザについては、動作環境を参照してください。
# liff.getLanguage()
LIFFアプリを動作させている環境の言語設定を取得します。
このメソッドは、liff.init()によるLIFFアプリの初期化が終了する前でも実行できます。
# 構文
liff.getLanguage();
# 引数
なし
# 戻り値
LIFFアプリを動作させている環境のnavigator.languageで取得できる言語設定が、文字列で返されます。
# liff.getVersion()
LIFF SDKのバージョンを取得します。
このメソッドは、liff.init()によるLIFFアプリの初期化が終了する前でも実行できます。
# 構文
liff.getVersion();
# 引数
なし
# 戻り値
LIFF SDKのバージョンが、文字列で返されます。
# liff.getLineVersion()
ユーザーのLINEバージョンを取得します。
このメソッドは、liff.init()によるLIFFアプリの初期化が終了する前でも実行できます。
# 構文
liff.getLineVersion();
# 引数
なし
# 戻り値
ユーザーがLIFFブラウザでLIFFアプリを開くと、ユーザーのLINEバージョンが文字列で返されます。ユーザーが外部ブラウザでLIFFアプリを開くと、 nullが返されます。
# liff.getContext()
LIFFアプリが起動された画面（1対1のトーク、グループトーク、複数人トーク、または外部ブラウザ）に関する情報を取得します。
LIFFアプリに対するトークルームの内部識別子（1対1トークID、グループID、トークルームID）の提供は廃止されました。詳しくは、2023年2月6日のニュース、「2023年2月6日をもってLIFFアプリに対するトークルームの内部識別子の提供を廃止しました」を参照してください。
# 構文
liff.getContext();
# 引数
なし
# 戻り値
各種APIを呼び出すために必要な情報を含むデータオブジェクトが返されます。
type
String
LIFFアプリが起動された画面の種類。以下のいずれかの値が含まれます。
utou：1対1のトークgroup：グループトークroom：複数人トークexternal：外部ブラウザnone：LINEの1対1のトーク、グループ、複数人トーク、外部ブラウザ以外から起動した場合。例：ウォレットタブ
LIFF間遷移後のLIFFアプリでも、このプロパティが返ります。
viewType
String
LIFFアプリの画面サイズ。typeプロパティがutou、group、またはroomの場合に、以下のいずれかの値が含まれます。
compacttallfull
詳しくは、「LIFFアプリをチャネルに追加する」を参照してください。
accessTokenHash
String
SHA256でハッシュ化したアクセストークンの前半部分。アクセストークンの検証に使用されます。
userId
String
ユーザーID。typeプロパティが、utou、room、group、noneまたはexternalの場合に含まれます。ただし、typeプロパティがexternalの場合は、nullが返されることがあります。
availability.shareTargetPicker.permission
Boolean
LIFFアプリを起動した環境で、liff.shareTargetPicker()が使用可能かどうかを表します。
true：liff.shareTargetPicker()が使用可能。false：liff.shareTargetPicker()が使用不可。
※liff.shareTargetPicker()の使用可否は、このプロパティではなく、liff.isApiAvailable('shareTargetPicker')で確認することをお勧めします。
availability.shareTargetPicker.minVer
String
liff.shareTargetPicker()が使用可能なLINEの最小バージョン
availability.multipleLiffTransition.permission
Boolean
LIFFアプリを起動した環境で、LIFFアプリを閉じずにliff.openWindow()で別のLIFFアプリへ遷移することが可能かどうかを表します。
true：現在表示しているLIFFアプリを閉じずに別のLIFFアプリを開くことが可能。false：現在表示しているLIFFアプリを閉じずに別のLIFFアプリを開くことが不可。
※LIFF間遷移可否の情報は、このプロパティではなく、liff.isApiAvailable('multipleLiffTransition')で確認することをお勧めします。
availability.multipleLiffTransition.minVer
String
LIFFアプリを閉じずに別のLIFFアプリを開くことが可能なLINEの最小バージョン
endpointUrl
String
LIFFアプリのエンドポイントURL。
permanentLinkPattern
String
LIFF URLの追加情報の処理方法。concatが返されます。
詳しくは、『LIFFドキュメント』の「LIFFアプリを開く」を参照してください。
liffId
String
LIFF ID。
utouId
String
このプロパティは廃止されました。詳しくは、2023年2月6日のニュース、「2023年2月6日をもってLIFFアプリに対するトークルームの内部識別子の提供を廃止しました」を参照してください。
groupId
String
このプロパティは廃止されました。詳しくは、2023年2月6日のニュース、「2023年2月6日をもってLIFFアプリに対するトークルームの内部識別子の提供を廃止しました」を参照してください。
roomId
String
このプロパティは廃止されました。詳しくは、2023年2月6日のニュース、「2023年2月6日をもってLIFFアプリに対するトークルームの内部識別子の提供を廃止しました」を参照してください。
# liff.isInClient()
LIFFアプリをLIFFブラウザで動作させているかどうかを取得します。
このメソッドは、liff.init()によるLIFFアプリの初期化が終了する前でも実行できます。
# 構文
liff.isInClient();
# 引数
なし
# 戻り値
# liff.isLoggedIn()
# 構文
liff.isLoggedIn();
# 引数
なし
# 戻り値
true：ログインしているfalse：ログインしていない
# liff.isApiAvailable()
指定したAPIが、LIFFアプリを起動した環境で使用可能かどうかを確認します。たとえば、APIが対応しているLINEバージョンであることや、APIを呼び出すために特別な同意が必要な場合は同意していることを確認します。
# 構文
liff.isApiAvailable(apiName);
# 引数
apiName
String
LIFFのクライアントAPIの名前。以下のAPI名を指定できます。
multipleLiffTransitionは、LIFFアプリを閉じずに別のLIFFアプリを開くこと（LIFF間遷移）が可能かどうか、という状態を表すプロパティで、APIの名前ではありません。詳しくは、『LIFFドキュメント』の「LIFFアプリから別のLIFFアプリを開いた場合の動作について（LIFF間遷移）」を参照してください。
# 戻り値
指定したAPIが、現在の環境で使用可能かどうかが返されます。
| 戻り値 | 説明 |
|---|---|
true | 使用可能 |
false | 使用不可能。以下の場合は、falseが返されます。
|
# 認証
# liff.login()
外部ブラウザおよびLINE内ブラウザ上で、ログイン処理を行います。
LIFFブラウザの場合、liff.init()実行時に自動でログイン処理が実行されるため、liff.login()は利用できません。
LIFFブラウザ内でLINEログインによる認可リクエストを行った際の動作は保証されません。また、LIFFアプリを外部ブラウザやLINE内ブラウザで開く場合には、必ず本メソッドでログイン処理を行い、LINEログインによる認可リクエストは行わないでください。
# 構文
liff.login(loginConfig);
# 引数
loginConfig
Object
ログインの設定
loginConfig.redirectUri
String
ログイン後にLIFFアプリで表示するURL。デフォルト値は［エンドポイントURL］に設定したURLです。［エンドポイントURL］の設定方法について詳しくは、『LIFFドキュメント』の「LIFFアプリをチャネルに追加する」を参照してください。
redirectUriに指定したURLが［エンドポイントURL］に設定したURLで始まらない場合、ログイン処理に失敗し、エラー画面が表示されます。
たとえば、［エンドポイントURL］がhttps://example.com/path1/path2?query1=value1の場合、ログイン処理の成否は以下のとおりです。なお、クエリパラメータやURLフラグメントはログイン処理の成否に影響しません。
| redirectUri | ログイン処理 |
|---|---|
| ✅ 成功 |
| ❌ 失敗 |
# 戻り値
なし
# liff.logout()
# 構文
liff.logout();
# 引数
なし
# 戻り値
なし
# liff.getAccessToken()
LIFF SDKが取得した「現在のユーザーのアクセストークン」を取得します。
LIFFアプリからサーバーにユーザー情報を送信するときに、このAPIで取得したアクセストークンを利用できます。サーバーでユーザー情報を使用する方法について詳しくは、『LIFFドキュメント』の「LIFFアプリおよびサーバーでユーザー情報を使用する」を参照してください。
アクセストークンの有効期限は、発行後12時間です。なお、ユーザーがLIFFアプリを閉じると、有効期限が切れていなくてもアクセストークンは無効化されます。
LIFFブラウザでLIFFアプリを起動した場合は、
liff.init()を呼び出したときに、LIFF SDKがアクセストークンを取得します。外部ブラウザでLIFFアプリを起動した場合は、以下の手順を行ったのちに、LIFF SDKがアクセストークンを取得します。
- LIFFアプリで、
liff.login()を呼び出す。 - ユーザーがログインする。
- LIFFアプリで、再度
liff.init()を呼び出す。
- LIFFアプリで、
# 構文
liff.getAccessToken();
# 引数
なし
# 戻り値
現在のユーザーのアクセストークンを文字列で返します。
# liff.getIDToken()
LIFF SDKが取得した「現在のユーザーの生のIDトークン」を取得します。IDトークンは、ユーザー情報を含むJSONウェブトークン（JWT）です。
LIFFアプリからサーバーにユーザー情報を送信するときに、このAPIで取得したIDトークンを利用できます。サーバーでユーザー情報を使用する方法について詳しくは、『LIFFドキュメント』の「LIFFアプリおよびサーバーでユーザー情報を使用する」を参照してください。
LIFFアプリをチャネルに追加するときに、openidスコープを選択してください。スコープを選択しなかった場合やユーザーが認可しなかった場合は、IDトークンを取得できません。スコープの選択は、LIFFアプリ追加後もLINE DevelopersコンソールのLIFFタブで変更できます。
LIFFブラウザでLIFFアプリを起動した場合は、
liff.init()を呼び出したときに、LIFF SDKがIDトークンを取得します。外部ブラウザでLIFFアプリを起動した場合は、以下の手順を行ったのちに、LIFF SDKがIDトークンを取得します。
- LIFFアプリで、
liff.login()を呼び出す。 - ユーザーがログインする。
- LIFFアプリで、再度
liff.init()を呼び出す。
- LIFFアプリで、
LIFFアプリをチャネルに追加するときに、emailスコープを選択し、ユーザーが認可すると、メールアドレスも取得できます。スコープの選択は、LIFFアプリ追加後もLINE DevelopersコンソールのLIFFタブで変更できます。
# 構文
liff.getIDToken();
# 引数
なし
# 戻り値
生のIDトークンが返されます。
# liff.getDecodedIDToken()
LIFF SDKが取得したIDトークンの「ペイロード」を取得します。ペイロードには、ユーザーの表示名、プロフィール画像のURL、メールアドレスなどの情報が含まれます。
LIFFアプリでユーザーの表示名などを利用する場合に、このメソッドを利用してください。
このメソッドで取得したユーザー情報をサーバーに送信しないでください。サーバーでユーザー情報を使用する方法について詳しくは、『LIFFドキュメント』の「LIFFアプリおよびサーバーでユーザー情報を使用する」を参照してください。
LIFFアプリをチャネルに追加するときに、openidスコープを選択してください。スコープを選択しなかった場合やユーザーが認可しなかった場合は、IDトークンを取得できません。スコープの選択は、LIFFアプリ追加後もLINE DevelopersコンソールのLIFFタブで変更できます。
LIFFブラウザでLIFFアプリを起動した場合は、
liff.init()を呼び出したときに、LIFF SDKがIDトークンを取得します。外部ブラウザでLIFFアプリを起動した場合は、以下の手順を行ったのちに、LIFF SDKがIDトークンを取得します。
- LIFFアプリで、
liff.login()を呼び出す。 - ユーザーがログインする。
- LIFFアプリで、再度
liff.init()を呼び出す。
- LIFFアプリで、
LIFFアプリをチャネルに追加するときに、emailスコープを選択し、ユーザーが認可すると、メールアドレスも取得できます。スコープの選択は、LIFFアプリ追加後もLINE DevelopersコンソールのLIFFタブで変更できます。
# 構文
liff.getDecodedIDToken();
# 引数
なし
# 戻り値
IDトークンのペイロードが返されます。
IDトークンのペイロードについて詳しくは、「IDトークンからプロフィール情報を取得する」の「ペイロード」を参照してください。
# liff.permission.query()
# 構文
liff.permission.query(permission);
# 引数
permission
String
確認対象の権限。以下のいずれかのスコープを指定します。
# 戻り値
Promiseオブジェクトが返されます。
Promiseがresolveされると、以下のプロパティを持つオブジェクトが渡されます。
state
String
以下のいずれかの値が含まれます。
granted: 権限付与にユーザーが同意済みprompt: 権限付与にユーザーが未同意unavailable: 指定したスコープをチャネルが持たないため、利用不可
# liff.permission.requestAll()
LINEミニアプリが要求する権限の「アクセス許可要求画面」を表示します。
liff.permission.requestAll()はLINEミニアプリでのみ動作します。
このメソッドを実行するには、あらかじめLINE Developersコンソールで、［チャネル同意の簡略化］をオンにする必要があります。チャネル同意の簡略化の設定方法について詳しくは、『LINEミニアプリドキュメント』の「「チャネル同意の簡略化」の設定方法」を参照してください。
権限付与にユーザーがすべて同意済みの場合、liff.permission.requestAll()を実行すると、Promiseがrejectされ、LiffErrorが渡されます。そのため、liff.permission.query()を使って、ユーザーが未同意の権限があるかどうかを確認してください。未同意の権限がある場合にのみ、liff.permission.requestAll()を実行するようにしてください。
# 構文
liff.permission.requestAll();
# 引数
なし
# 戻り値
Promiseオブジェクトが返されます。
# エラーレスポンス
［チャネル同意の簡略化］がオンになっていない場合や、権限付与にユーザーがすべて同意済みの場合は、Promiseがrejectされ、LiffErrorが渡されます。
# プロフィール
# liff.getProfile()
現在のユーザーのプロフィール情報を取得します。
このメソッドで取得したユーザー情報をサーバーに送信しないでください。サーバーでユーザー情報を使用する方法について詳しくは、『LIFFドキュメント』の「LIFFアプリおよびサーバーでユーザー情報を使用する」を参照してください。
LIFFアプリをチャネルに追加するときに、profileスコープを選択してください。スコープを選択しなかった場合やユーザーが認可しなかった場合は、プロフィール情報を取得できません。スコープの選択は、LIFFアプリ追加後もLINE DevelopersコンソールのLIFFタブで変更できます。
# 構文
liff.getProfile();
# 引数
なし
# 戻り値
# liff.getFriendship()
ユーザーとLINE公式アカウントの友だち関係を取得します。
ただし、LIFFアプリが追加されているLINEログインのチャネルに、LINE公式アカウントがリンクされている場合に、そのLINE公式アカウントとの友だち関係のみを取得できます。LINEログインのチャネルに、LINE公式アカウントをリンクする方法については、『LINEログインドキュメント』の「LINEログインしたときにLINE公式アカウントを友だち追加する（友だち追加オプション）」を参照してください。
LIFFアプリをチャネルに追加するときに、profileスコープを選択してください。スコープを選択しなかった場合やユーザーが認可しなかった場合は、友だち関係を取得できません。スコープの選択は、LIFFアプリ追加後もLINE DevelopersコンソールのLIFFタブで変更できます。
# 構文
liff.getFriendship();
# 引数
なし
# 戻り値
# ウィンドウ
# liff.openWindow()
指定したURLをLINE内ブラウザまたは外部ブラウザで開きます。
liff.openWindow()の外部ブラウザでの利用は、保証対象外です。
iOS版LINEかつLIFF v2.16.1以前で、urlプロパティにクエリパラメータ（?key=value）が含まれず、かつURLフラグメント（#URL-fragment）が含まれていると、URLフラグメントの末尾に意図しないクエリパラメータが追加されたURLが開かれます。
以下は、liff.openWindow()実行時に開かれるURLの例です。
| LIFF SDKバージョン | urlプロパティ | 開かれるURL |
|---|---|---|
| v2.16.1 | https://example.com#URL-fragment | https://example.com#URL-fragment?is_liff_external_open_window=false |
| v2.17.0 | https://example.com#URL-fragment | https://example.com#URL-fragment |
# 構文
liff.openWindow(params);
# 引数
params
Object
パラメータオブジェクト
params.url
String
URL。完全なURLで指定します。
params.external
Boolean
指定したURLを外部ブラウザで開くかどうかを、以下のどちらかの値で指定します。デフォルト値はfalseです。
true：外部ブラウザで開きます。false：LINE内ブラウザで開きます。
# 戻り値
なし
# liff.closeWindow()
LIFFアプリを閉じます。
このメソッドは、LIFF SDKバージョンが2.4.0以上の場合のみ、liff.init()によるLIFFアプリの初期化が終了する前でも実行できます。
liff.closeWindow()の外部ブラウザでの動作は、保証対象外です。
# 構文
liff.closeWindow();
# 引数
なし
# 戻り値
なし
# メッセージ
# liff.sendMessages()
ユーザーの代わりに、LIFFアプリが開かれているトーク画面にメッセージを送信します。この機能は1対1のトークルームから起動したLIFFアプリのLIFFブラウザ内でのみ利用できます。
LIFFアプリをチャネルに追加するときに、chat_message.writeスコープを選択してください。スコープを選択しなかった場合やユーザーが認可しなかった場合は、メッセージは送信できません。スコープの選択は、LIFFアプリ追加後もLINE DevelopersコンソールのLIFFタブで変更できます。
liff.sendMessages()メソッドは、ユーザー同士、またはLINE公式アカウントとユーザーの1対1のトークルーム内で、LIFFアプリを開くためのURLスキームでLIFFアプリを起動した場合のみ利用できます。
そのため、以下の場合はliff.sendMessages()メソッドが利用できず、エラーコード403のuser doesn't grant required permissions yetエラーが発生します。
- KeepおよびKeepメモ (opens new window)の機能を利用してLIFFアプリにアクセスした場合
- Webサイトのリダイレクト処理などによりLIFFアプリを開くためのURLスキームにアクセスした場合
- LIFFアプリから別のLIFFアプリを開いた場合。詳しくは、『LIFFドキュメント』の「LIFFアプリから別のLIFFアプリを開いた場合の動作について（LIFF間遷移）」を参照してください。
# 構文
liff.sendMessages(messages);
# 引数
messages
Objectの配列
メッセージオブジェクト
最大件数：5
Messaging APIの以下のタイプのメッセージを送信できます。
- テキストメッセージ。ただし、
emojisプロパティおよびquoteTokenプロパティは利用できません。 - スタンプメッセージ。ただし、
quoteTokenプロパティは利用できません。 - 画像メッセージ
- 動画メッセージ。ただし、
trackingIdプロパティは利用できません。 - 音声メッセージ
- 位置情報メッセージ
- テンプレートメッセージ。ただし、設定できるアクションはURIアクションのみです。
- Flex Message。ただし、設定できるアクションはURIアクションのみです。
ボットのLINE公式アカウントが参加しているトークでメッセージが送信されると、LINEプラットフォームからボットサーバーにWebhookイベントが送信されます。liff.sendMessages()メソッドで画像、動画、および音声のメッセージが送信されると、結果として送信されるWebhookイベントのcontentProvider.typeプロパティの値はexternalになります。詳しくは、『Messaging APIリファレンス』の「メッセージイベント」を参照してください。
# 戻り値
Promiseオブジェクトが返されます。
- メッセージの送信が成功すると、
Promiseがresolveされます。値は渡されません。 - メッセージの送信が失敗すると、
Promiseがrejectされ、LiffErrorが渡されます。
# liff.shareTargetPicker()
ターゲットピッカー（グループまたは友だちを選択する画面）を表示し、ターゲットピッカーで選択した相手に、開発者が作成したメッセージを送信します。このメッセージは、ユーザーが送信したかのように、グループまたは友だちに表示されます。
- ターゲットピッカーを表示するには、LINE Developersコンソールでシェアターゲットピッカーをオンにしてください。詳しくは、『LIFFドキュメント』の「シェアターゲットピッカーを利用するには」を参照してください。
- 外部ブラウザで利用する場合は、
liff.login()を呼び出して、ログイン処理を行ってから、liff.shareTargetPicker()を呼び出します。
ユーザーのプライバシーを保護するため、シェアターゲットピッカーで、何人にメッセージが送信されたかの情報は取得できません。また、提供も行なっておりません。
# 構文
liff.shareTargetPicker(messages, options);
# 引数
messages
Objectの配列
メッセージオブジェクト
最大件数：5
Messaging APIの以下のタイプのメッセージを送信できます。
- テキストメッセージ
- 画像メッセージ
- 動画メッセージ
- 音声メッセージ
- 位置情報メッセージ
- テンプレートメッセージ。ただし、設定できるアクションはURIアクションのみです。
- Flex Message。ただし、設定できるアクションはURIアクションのみです。
options
Object
シェアターゲットピッカーのオプション
options.isMultiple
Boolean
ユーザーがターゲットピッカーで選択するメッセージ送信先として、複数の送信先を選択可能にするかどうかを、以下のどちらかの値で指定します。デフォルト値はtrueです。
true：ユーザーはグループ、友だち、トークの中から、複数の送信先を選択できます。false：ユーザーは友だちの中から、1人のみを送信先として選択できます。
isMultipleプロパティにfalseを設定しても、シェアターゲットピッカーを複数回呼び出すことや、シェア後のメッセージをユーザー側で再度シェアすることで、複数のユーザーへのメッセージ送信が可能です。厳密にユーザーから1人の友だちに対して、一度しかメッセージを送信できないようにする場合には、LIFFアプリ実装時に制限をかける必要があります。
URLを含むメッセージを送信し、URLへのアクセスを制限する場合の例を紹介します。
- URLにユニークなトークンを付与し、メッセージを送信します。
- メッセージ内のURLへアクセスされた際にサーバー側でトークンを検証し、複数のユーザーからのアクセスを制限します。
# 戻り値
Promiseオブジェクトが返されます。
正しくメッセージが送信されると、
Promiseがresolveされ、以下のプロパティを持つオブジェクトが渡されます。status
String
常に
successです。メッセージを送信する前に、ユーザーがキャンセルしてターゲットピッカーを閉じると、
Promiseがresolveされますが、オブジェクトは渡されません。ターゲットピッカーが表示される前に問題が発生した場合は、
Promiseがrejectされ、LiffErrorが渡されます。LiffErrorオブジェクトについては、「LIFF SDKのエラー」を参照してください。
Promiseがresolveした場合とrejectした場合のコールバック関数内で、alert()を実行すると一部端末で正しく動作しません。
# カメラ
# liff.scanCodeV2()
二次元コードリーダーを起動し、読み取った文字列を取得します。二次元コードリーダーを起動するには、あらかじめLINE Developersコンソールで、 [Scan QR] をオンにする必要があります。
liff.scanCodeV2()は以下の環境で動作します。
- iOS：iOS14.3以降かつLINEバージョン11.7.0以降
- Android：LINEバージョン11.7.0以降
- 外部ブラウザ：WebRTC API (opens new window) をサポートするウェブブラウザ
| OS | バージョン | LINEアプリのバージョン | 外部ブラウザ | |
|---|---|---|---|---|
| 10.17.0〜11.6.x | 11.7.0以降 | |||
| iOS | 11〜14.2 | ❌ | ❌ | ✅ ※1 |
| 14.3以降 | ❌ | ✅ ※2 | ✅ ※1 | |
| Android | すべてのバージョン | ❌ | ✅ ※2 | ✅ ※1 |
| PC | すべてのバージョン | ❌ | ❌ | ✅ ※1 |
※1 WebRTC API (opens new window)をサポートするウェブブラウザのみ利用できます。
※2 LIFFブラウザの画面サイズがFullの場合のみ利用できます。詳しくは、『LIFFドキュメント』の「LIFFブラウザの画面サイズ」を参照してください。
LIFFアプリをチャネルに追加するときに、［Scan QR］をオンにしてください。［Scan QR］の設定は、LIFFアプリ追加後もLINE DevelopersコンソールのLIFFタブで変更できます。
liff.scanCodeV2()は、内部でjsQR (opens new window)という外部ライブラリを使用しています。そのため、liff.scanCodeV2()メソッド実行時に起動する二次元コードリーダーは、jsQR (opens new window)の動作仕様に依存します。なお、使用ライブラリは予告なく更新、変更される可能性があります。
# 構文
liff.scanCodeV2();
# 引数
なし
# 戻り値
Promiseオブジェクトが返されます。
二次元コードリーダーで文字列が読み取れると、Promiseがresolveされ、読み取った文字列を含むオブジェクトが渡されます。
value
String
二次元コードリーダーで読み取った文字列
# エラーレスポンス
Promiseがrejectされたときは、LiffErrorが渡されます。
# liff.scanCode()
従来のliff.scanCode()メソッドは非推奨になります。二次元コードリーダーを実装する場合は、liff.scanCodeV2()メソッドを使用することをお勧めします。
LINEの二次元コードリーダーを起動し、読み取った文字列を取得します。二次元コードリーダーを起動するには、あらかじめLINE Developersコンソールで、 [Scan QR] をオンにする必要があります。
liff.scanCode()は以下の環境で動作します。
| OS | バージョン | LINEアプリのバージョン | 外部ブラウザ | |
|---|---|---|---|---|
| 10.17.0〜11.6.x | 11.7.0以降 | |||
| iOS | すべてのバージョン | ❌ | ❌ | ❌ |
| Android | すべてのバージョン | ✅ | ✅ | ❌ |
| PC | すべてのバージョン | ❌ | ❌ | ❌ |
技術的な問題があり、iOS版LINEでは、liff.scanCodeはundefinedになります。サンプルコードのように、関数の存在を確認してから、使用してください。iOS版LINEや外部ブラウザでも二次元コードリーダーをお使いになりたい場合は、「liff.scanCodeV2()」を参照してください。
- LIFFアプリをチャネルに追加するときに、［Scan QR］をオンにしてください。［Scan QR］の設定は、LIFFアプリ追加後もLINE DevelopersコンソールのLIFFタブで変更できます。
liff.scanCode()は、外部ブラウザでは利用できません。
# 構文
liff.scanCode();
# 引数
なし
# 戻り値
Promiseオブジェクトが返されます。
LINEの二次元コードリーダーで文字列が読み取れると、Promiseがresolveされ、読み取った文字列を含むオブジェクトが渡されます。
value
String
二次元コードリーダーで読み取った文字列
# パーマネントリンク
# liff.permanentLink.createUrlBy()
LIFFアプリの任意のページのパーマネントリンクを取得します。
パーマネントリンクの形式：
https://liff.line.me/{liffId}/{path}?{query}#{URL fragment}
# 構文
liff.permanentLink.createUrlBy(url);
# 引数
url
String
パーマネントリンクを取得するURL。任意のクエリパラメータを追加できます。
# 戻り値
Promiseオブジェクトが返されます。
Promiseがresolveされると、パーマネントリンクの文字列が渡されます。
# エラーレスポンス
パーマネントリンクを取得するURLが、LINE Developersコンソールの［エンドポイントURL］に指定したURLで始まらない場合、Promiseがrejectされ、LiffErrorが渡されます。
たとえば、パーマネントリンクを取得するURL（例：https://example.com/）が、［エンドポイントURL］（例：https://example.com/path1?q1=v1）より上の階層の場合、Promiseがrejectされます。
# liff.permanentLink.createUrl()
技術的な問題があり、liff.permanentLink.createUrl()は、次回メジャーバージョン以降に非推奨になる可能性があります。現在のページのパーマネントリンクを取得するには、liff.permanentLink.createUrlBy()を使用することをお勧めします。
現在のページのパーマネントリンクを取得します。
パーマネントリンクの形式：
https://liff.line.me/{liffId}/{path}?{query}#{URL fragment}
# 構文
liff.permanentLink.createUrl();
# 引数
なし
# 戻り値
現在のページのパーマネントリンクが、文字列で返されます。
現在のページのURLがLINE Developersコンソールの［エンドポイントURL］に指定したURLで始まらない場合、LiffError例外が発生します。
# liff.permanentLink.setExtraQueryParam()
技術的な問題があり、liff.permanentLink.setExtraQueryParam()は、次回メジャーバージョン以降に非推奨になる可能性があります。現在のページのパーマネントリンクに、任意のクエリパラメータを追加するには、liff.permanentLink.createUrlBy()を使用することをお勧めします。
現在のページのパーマネントリンクに、任意のクエリパラメータを追加できます。
liff.permanentLink.setExtraQueryParam()を実行するたびに、前回追加したクエリパラメータは破棄されます。
- 追加したクエリパラメータを削除するには、
liff.permanentLink.setExtraQueryParam("")を実行します。 - 追加したクエリパラメータは、ユーザーが別のページに移動すると破棄されます。
# 構文
liff.permanentLink.setExtraQueryParam(extraString);
# 引数
extraString
String
追加するクエリパラメータ
# 戻り値
なし
# Bluetoothプラグイン
# liff.initPlugins()
# 構文
liff.initPlugins(pluginNames);
# 引数
pluginNames
Stringの配列
プラグインの名前。以下のいずれかの値を指定します。
bluetooth
※Bluetoothプラグインは、Android版LINEの場合のみ、有効化できます。iOS版では有効化に失敗し、FORBIDDENエラーが返されます。
# 戻り値
Promiseオブジェクトが返されます。
- プラグインの有効化が成功すると、
Promiseがresolveされます。 - プラグインの有効化に失敗すると、
Promiseがrejectされ、エラー情報が渡されます。
# liff.bluetooth.getAvailability()
技術的な問題があり、iOS版LINEでは、liff.bluetooth.getAvailability()の提供を一時停止しています。
Bluetoothプラグインが利用できるかどうかを確認します。このメソッドを実行すると、以下の内容が確認されます。
チャネルに追加したLIFFアプリのBluetoothサポートの有無
注意チャネルに追加したLIFFアプリのBLE機能を有効にしていないと、Bluetoothプラグインは有効化できません。
スマートフォンのBluetooth設定
ユーザーがLINE Thingsの利用規約に同意していること
ユーザーがLINEをAndroidで使用している場合は、位置情報の取得権限
あらかじめliff.initPlugins()を使用して、Bluetoothプラグインを有効化してください。
# 構文
liff.bluetooth.getAvailability();
# 引数
なし
# 戻り値
Promiseオブジェクトが返されます。
Bluetoothプラグインが利用できるかどうかが確認されると、Promiseがresolveされ、Bluetoothプラグインが利用できるかどうかを示すBooleanオブジェクトが渡されます。
# liff.bluetooth.requestDevice()
技術的な問題があり、iOS版LINEでは、liff.bluetooth.requestDevice()の提供を一時停止しています。
連携済みのデバイスをスキャンし、情報を取得します。
フィルターを使って、アドバタイズメントパケットを受け入れるデバイスを制限できます。
あらかじめliff.initPlugins()を使用して、Bluetoothプラグインを有効化してください。
# 構文
liff.bluetooth.requestDevice(options);
# 引数
options
Object
フィルターを表すRequestDeviceOptionsオブジェクト。省略したときは、すべてのデバイスからのアドバタイズメントパケットを受け入れます。
# データオブジェクト
# RequestDeviceOptionsオブジェクト
filters
Objectの配列
# LINEBluetoothRequestDeviceFilterオブジェクト
deviceId
String
アドバタイズメントパケットを受け入れるデバイスのデバイスID
# 戻り値
Promiseオブジェクトが返されます。
連携済みのデバイスをスキャンし、情報を取得できると、Promiseがresolveされ、デバイスの情報を示すBluetoothDeviceオブジェクトが渡されます。
# データオブジェクト
# BluetoothDeviceオブジェクト
id
String
デバイスID
name
String
デバイス名
gatt
Object
watchingAdvertisements
Boolean
アドバタイズメントパケットの監視状況（※）
| メソッド | 戻り値 | 説明 |
|---|---|---|
| watchAdvertisements | Promise <void> | アドバタイズメントパケットの受け入れを開始します。（※） |
| unwatchAdvertisements | void | アドバタイズメントパケットの受け入れを停止します。（※） |
| addEventListener | void | イベントリスナーを登録します。advertisementreceivedイベント（※）とgattserverdisconnectedイベントに、イベントリスナーを登録できます。 |
| removeEventListener | void | 登録済みのイベントリスナーを削除します。advertisementreceivedイベント（※）とgattserverdisconnectedイベントに登録したイベントリスナーを削除できます。 |
※試験的に実装している機能です。これらの機能は予告なく変更、または停止される可能性があります。
# BluetoothRemoteGATTServerオブジェクト
デバイスと通信するには、GATTサーバー（汎用アトリビュートプロファイルサーバー）を表すBluetoothRemoteGATTServerオブジェクトを使用します。
liff.bluetooth.requestDevice()実行後、Promiseがresolveすると、BluetoothDeviceオブジェクトのgattプロパティから、BluetoothRemoteGATTServerにアクセスできます。
device
Object
connected
Boolean
接続している場合はtrue。接続していない場合はfalse
| メソッド | 戻り値 | 説明 |
|---|---|---|
| connect | Promise <BluetoothRemoteGATTService> | デバイスと接続します。 |
| disconnect | void | デバイスのGATTサーバーから切断します。 |
| getPrimaryService(serviceUUID) | Promise <BluetoothRemoteGATTService> | GATTサーバーのプライマリサービスを取得します。serviceUUIDには、128ビットのUUIDを文字列で指定します。 注：このメソッドはUUIDを検証しません。UUIDの検証は、characteristicの読み込み、書き込み、通知の開始、通知の停止を実行する際に行われます。 |
# BluetoothRemoteGATTServiceオブジェクト
BluetoothRemoteGATTServiceオブジェクトは、characteristicを取得するためのオブジェクトです。
device
Object
uuid
String
GATT Service UUID
| メソッド | 戻り値 | 説明 |
|---|---|---|
| getCharacteristic(characteristicUUID) | Promise <BluetoothRemoteGATTCharacteristic> | characteristicを取得します。characteristicUUIDには、128ビットのUUIDを文字列で指定します。 注：このメソッドはUUIDを検証しません。UUIDの検証は、characteristicの読み込み、書き込み、通知の開始、通知の停止を実行する際に行われます。 |
# BluetoothRemoteGATTCharacteristicオブジェクト
BluetoothRemoteGATTCharacteristicオブジェクトは、デバイスのcharacteristicの読み込み、書き込み、通知の開始、通知の停止を実行するためのオブジェクトです。
service
Object
uuid
String
UUID
value
Object
| メソッド | 戻り値 | 説明 |
|---|---|---|
| readValue | Promise <DataView (opens new window)> | characteristicの値を読み取ります。 |
| writeValue(value) | Promise <void> | characteristicにArrayBuffer (opens new window)、TypedArray (opens new window)、またはDataView (opens new window)の値を書き込みます。 |
| startNotifications | Promise <BluetoothRemoteGATTCharacteristic> | characteristic変更の通知を開始します。 |
| stopNotifications | Promise <BluetoothRemoteGATTCharacteristic> | characteristic変更の通知を停止します。 |
| addEventListener | void | イベントリスナーを登録します。targetプロパティを含むcharacteristicvaluechangedイベントに、イベントリスナーを登録できます。 |
| removeEventListener | void | 登録済みのイベントリスナーを削除します。characteristicvaluechangedイベントに登録したイベントリスナーを削除できます。 |
readValue()writeValue()startNotifications()stopNotifications()メソッドは、UUIDとプロパティを検証します。存在しないUUIDやプロパティを指定した場合は、エラーが発生します。
# イベント
# advertisementreceivedイベント
アドバタイズメントパケットを受信すると、advertisementreceivedイベントが発生します。
advertisementreceivedイベントは、試験的に実装している機能です。この機能は予告なく変更、または停止される可能性があります。
device
Object
name
String
デバイス名
rssi
Number
RSSI
manufacturerData
Object
Map<Number, DataView>オブジェクト。会社識別コード（Company Identifier Code）をDataViewオブジェクトにマップしたデータです。
# gattserverdisconnectedイベント
# characteristicvaluechangedイベント
characteristicが変更されると、characteristicvaluechangedイベントが発生します。
# liff.bluetooth.referringDevice
技術的な問題があり、iOS版LINEでは、liff.bluetooth.referringDeviceの提供を一時停止しています。
LIFFアプリがデバイス経由で起動された場合、liff.bluetooth.referringDeviceに、そのデバイスの情報を示すBluetoothDeviceオブジェクトが設定されます。
# LIFFプラグイン
# liff.use()
# 構文
liff.use(module, option);
# 引数
module
Object
プラガブルSDKのLIFF APIのモジュールやLIFFプラグイン。
LIFF APIのモジュールを渡す場合、インスタンス化する必要があります。詳しくは、『LIFFドキュメント』の「プラガブルSDKの使用方法」を参照してください。
LIFFプラグインを渡す場合、LIFFプラグインがクラスのときは、インスタンス化する必要があります。詳しくは、『LIFFドキュメント』の「LIFFプラグインを使用する」を参照してください。
# 戻り値
liffオブジェクトが返されます。
# 多言語化
# liff.i18n.setLang()
# 構文
liff.i18n.setLang(language);
# 引数
language
String
RFC 5646（BCP 47） (opens new window)で定義されている言語タグ。指定した言語タグの翻訳がない場合は、enがフォールバックとして使用されます。
# 戻り値
Promiseオブジェクトが返されます。
# エラーレスポンス
Promiseがrejectされたときは、LiffErrorが渡されます。