# LIFF v2 API reference
# Common specifications
# Operating environment
For more information about supported operating environments for LIFF v2, see Overview in the LIFF documentation.
Which functions you can use depends on whether the LIFF app is opened in a LIFF browser or an external browser. For example, you can't use liff.scanCode()
in an external browser. For more information, see the descriptions for each client API.
For example, retrieving a user's profile information through a LIFF app isn't possible in most cases.
# LIFF SDK errors
# LiffError object
code
String
Error code
message
String
Error message. Returned when the defined message exists.
# Error details
Error code | Description |
---|---|
400 | Problem with the request. Check the request parameters and JSON format. |
401 | Check that the authorization header is correct. |
403 | Not authorized to use the API. Confirm that your account or plan is authorized to use the API. |
429 | Make sure that you are within the rate limit for requests. |
500 | Temporary error on the API server. |
INIT_FAILED | Failed to init LIFF SDK. |
INVALID_ARGUMENT | An invalid argument was specified. |
UNAUTHORIZED |
|
FORBIDDEN |
|
INVALID_CONFIG | An invalid setting.
|
INVALID_ID_TOKEN | Failed to verify the ID token. |
EXCEPTION_IN_SUBWINDOW | Problem with subwindow.
|
THINGS_NO_LINKED_DEVICES | No linked device is available. |
BLUETOOTH_SETTING_OFF | Bluetooth is off. |
THINGS_TERMS_NOT_AGREED | LINE Things TOS is not agreed. |
BLUETOOTH_NO_LOCATION_PERMISSION | Location permission is not granted. |
BLUETOOTH_LOCATION_DISABLED | Location setting is off. |
BLUETOOTH_LE_API_UNAVAILABLE | The BLE API for LIFF is not available on this device. |
BLUETOOTH_CONNECT_FAILED | Failed to connect to the device. |
BLUETOOTH_ALREADY_CONNECTED | The device is already connected. |
BLUETOOTH_CONNECTION_LOST | No device is connected. |
BLUETOOTH_UNSUPPORTED_OPERATION | The specified operation is not supported for the specified characteristic. |
BLUETOOTH_SERVICE_NOT_FOUND | The specified service does not exist in the GATT server. |
BLUETOOTH_CHARACTERISTIC_NOT_FOUND | The specified characteristic does not exist in the service. |
UNKNOWN | Unknown error. |
# LIFF SDK properties
# liff.id
The property that holds the LIFF app ID (String
type) passed to liff.init()
.
The value of liff.id
is null
until you run liff.init()
.
# liff.ready
A property holding the Promise
object that resolves when you run liff.init()
for the first time after starting the LIFF app.
If you use liff.ready
, you can execute any process after the completion of liff.init()
.
You can use liff.ready
even before the initialization of the LIFF app by liff.init()
has finished.
If liff.init()
fails, liff.ready
will not be rejected. Also, it doesn't return a LiffError
object.
# Initialization
# liff.init()
Initializes a LIFF app. You can only call other LIFF SDK methods after calling liff.init()
. The LIFF SDK obtains the access token and ID token of the user from the LINE Platform when you initialize the LIFF app.
- To use the access token obtained by the LIFF SDK, call liff.getAccessToken().
- To use the ID token payload obtained by the LIFF SDK, call liff.getDecodedIDToken().
The
liff.init()
method performs initialization processing based on information such asliff.state
andaccess_token=xxx
given to the primary redirect URL. If your endpoint URL includes a query parameter or path, to properly initialize the LIFF app, execute theliff.init()
method once for both the primary redirect URL and the secondary redirect URL. For more information, see Behaviors from accessing the LIFF URL to opening the LIFF app.Don't change the URL during server or front-end processing before the
Promise
object returned by theliff.init()
method is resolved. If you change the URL, it will return 'INIT_FAILED' and the LIFF app can't be opened. For example, if you perform redirects usinglocation.replace()
after runningliff.init()
, design it so that the screen transitions after thePromise
object is resolved.liff.init({ liffId: myLiffId }).then(() => { // Redirect to another page after the returned Promise object has been resolved location.replace("https://line.me/{liffId}/path"); });
The
access_token=xxx
automatically granted to the primary redirect URL is the user's access token (confidential information). Don't send the primary redirect URL to an external logging tool such as Google Analytics.
Note that in LIFF v2.11.0 or later, credential information is excluded from URLs whenliff.init()
is resolved. Therefore, you can prevent leaking credential information by sending the page view in thethen()
method as follows. If you want to use logging tools, we recommend that you upgrade your LIFF app to v2.11.0 or later. For more information about the updates in LIFF v2.11.0, see Release Notes in the LIFF documentation.liff.init({ liffId: myLiffId }).then(() => { ga("send", "pageview"); });
When you access a LIFF URL or perform a transition between LIFF apps, the URL may be given query parameters that begin with liff.*
.
e.g.
liff.state
(indicates additional information specified in LIFF URL)liff.referrer
(indicates where the referrer came from when transitioning between LIFF apps. For more information, see Get URL from before LIFF-to-LIFF transition)
The above query parameters are given by the SDK so that LIFF apps can function properly. When you independently alter the above query parameters, proper opening of the LIFF app and a transition between LIFF apps may not be guaranteed. Implement your app so that the liff.*
query parameter is altered after liff.init()
is resolved.
This property or methods are available even before the liff.init()
method is executed.
You can get the environment in which the LIFF app is running before initializing the LIFF app, or close the LIFF app when the LIFF app initialization fails.
- liff.ready
- liff.getOS()
- liff.getLanguage()
- liff.getVersion()
- liff.getLineVersion()
- liff.isInClient()
- liff.closeWindow()
- liff.use()
- liff.i18n.setLang()
To use the liff.closeWindow()
method before the initialization of the LIFF app by liff.init()
has finished, your LIFF SDK version must be v2.4.0 or later.
# Syntax
liff.init(config, successCallback, errorCallback);
# Arguments
config
Object
LIFF app configurations
config.liffId
String
LIFF app ID. Can be obtained when you add the LIFF app to your channel. For more information, see Adding a LIFF app to your channel.
The LIFF app ID specified here can be obtained with liff.id
.
config.withLoginOnExternalBrowser
Boolean
Using either of the following values, specify whether or not to automatically execute the liff.login()
method when initializing a LIFF app in an external browser. The default value is false
.
true
: Automatically execute theliff.login()
method in external browsersfalse
: Don't automatically execute theliff.login()
method in external browsers
successCallback
Function
Callback to return a data object upon successful initialization of the LIFF app.
successCallback is processed at the same time that the Promise
object of the return value is resolved. However, there is no set order to which is processed first.
errorCallback
Function
Callback to return an error object upon failure to initialize the LIFF app.
errorCallback is processed at the same time that the Promise
object of the return value is rejected. However, there is no set order to which is processed first.
# Return value
Returns a Promise
object.
# Error response
When the Promise
is rejected, LiffError
is passed.
# Getting environment
# liff.getOS()
Gets the environment in which the user is running the LIFF app.
You can use this method even before the initialization of the LIFF app by liff.init()
has finished.
# Syntax
liff.getOS();
# Arguments
None
# Return value
The environment in which the user is running the LIFF app is returned as a string. Since the return value is based on the name of the OS in the user agent string, the return value is independent of the browser type (LIFF browser, LINE's in-app browser, external browser).
For example, if the user is using iOS, ios
will be returned, regardless of whether the user is using LIFF browser or Safari.
Return value | Description |
---|---|
ios | iOS or iPadOS |
android | Android |
web | Other than the above |
For more information about LIFF app supported operating systems and browsers, see Operating environment.
# liff.getLanguage()
Gets the language settings of the environment in which the LIFF app is running.
You can use this method even before the initialization of the LIFF app by liff.init()
has finished.
# Syntax
liff.getLanguage();
# Arguments
None
# Return value
String containing language settings specified in navigator.language
in the LIFF app's running environment.
# liff.getVersion()
Gets the version of the LIFF SDK.
You can use this method even before the initialization of the LIFF app by liff.init()
has finished.
# Syntax
liff.getVersion();
# Arguments
None
# Return value
The version of the LIFF SDK is returned as a string.
# liff.getLineVersion()
Gets the user's LINE version.
You can use this method even before the initialization of the LIFF app by liff.init()
has finished.
# Syntax
liff.getLineVersion();
# Arguments
None
# Return value
If a user opens the LIFF app using a LIFF browser, the LINE version of the user is returned as a string. If a user opens the LIFF app using an external browser, null
is returned.
# liff.getContext()
Gets the screen type (1-on-1 chat, group chat, multi-person chat, or external browser) from which the LIFF app is launched.
We've discontinued providing company internal identifiers of chat rooms (one-on-one chat ID, group ID, and room ID) to LIFF apps. For more information, see the news from February 6, 2023, We've discontinued providing company internal identifiers of chat rooms to LIFF apps as of February 6, 2023.
# Syntax
liff.getContext();
# Arguments
None
# Return value
A data object that contains the information necessary to make various API calls.
type
String
The type of screen from where the LIFF app was launched. One of:
utou
: 1-on-1 chatgroup
: Group chatroom
: Multi-person chatexternal
: External browsernone
: A screen other than a 1-on-1 chat, group chat, multi-person chat, or external browser. For example, Wallet tab.
This property is also returned for LIFF apps after transitioning between LIFF apps.
viewType
String
Size of the LIFF app view, only returned if the type
property is utou
, room
, or group
. One of:
compact
tall
full
For more information, see Adding the LIFF app to a channel.
accessTokenHash
String
First half of the hashed SHA256 value of the access token. Used to validate the access token.
userId
String
User ID. Included when the type
property is utou
, room
, group
, none
or external
. However, null may be returned when type
is external
.
availability.shareTargetPicker.permission
Boolean
Specifies whether liff.shareTargetPicker()
is available in the environment in which the LIFF app was launched.
true
:liff.shareTargetPicker()
is available.false
:liff.shareTargetPicker()
isn't available.
*To get information about the availability of liff.shareTargetPicker()
, we highly recommend using liff.isApiAvailable('shareTargetPicker') instead.
availability.shareTargetPicker.minVer
String
The minimum LINE version that supports liff.shareTargetPicker().
availability.multipleLiffTransition.permission
Boolean
Displays whether it's possible to transition to another LIFF app without closing the LIFF app within the LIFF browser.
true
: It's possible to open another LIFF app without closing the currently opened LIFF app.false
: It's not possible to open another LIFF app without closing the currently opened LIFF app.
*To get information about the availability of a transition between multiple LIFF apps, we highly recommend using liff.isApiAvailable('multipleLiffTransition') instead.
availability.multipleLiffTransition.minVer
String
The minimum LINE version that supports opening another LIFF app without closing the currently opened LIFF app.
endpointUrl
String
URL of the service endpoint.
permanentLinkPattern
String
How additional information in LIFF URLs is handled. concat
is returned.
For more information, see Opening a LIFF app in the LIFF documentation.
liffId
String
LIFF ID.
utouId
String
This property was discontinued. For more information, see the news from February 6, 2023, We've discontinued providing company internal identifiers of chat rooms to LIFF apps as of February 6, 2023.
groupId
String
This property was discontinued. For more information, see the news from February 6, 2023, We've discontinued providing company internal identifiers of chat rooms to LIFF apps as of February 6, 2023.
roomId
String
This property was discontinued. For more information, see the news from February 6, 2023, We've discontinued providing company internal identifiers of chat rooms to LIFF apps as of February 6, 2023.
# liff.isInClient()
Determines whether the LIFF app is running in a LIFF browser.
You can use this method even before the initialization of the LIFF app by liff.init()
has finished.
# Syntax
liff.isInClient();
# Arguments
None
# Return value
true
: Running in LIFF browserfalse
: Running in external browser or LINE's in-app browser
# liff.isLoggedIn()
# Syntax
liff.isLoggedIn();
# Arguments
None
# Return value
true
: The user is logged infalse
: The user is not logged in
# liff.isApiAvailable()
Checks whether the specified API is available in the environment where you started the LIFF app. Specifically, it verifies whether the current LINE version supports the API and whether the terms and conditions for the API have been accepted.
# Syntax
liff.isApiAvailable(apiName);
# Arguments
apiName
String
The name of the LIFF client API. You can currently specify these API names:
multipleLiffTransition
is a property which indicates whether it's possible to open another LIFF app without closing the current LIFF app (LIFF-to-LIFF transition). It is not the name of an API. For more information, see Opening a LIFF app from another LIFF app (LIFF-to-LIFF transition) in the LIFF documentation.
# Return value
Returns whether the specified API is available in the current environment.
Return value | Description |
---|---|
true | Available |
false | Unavailable. Returns false in these situations:
|
# Authentication
# liff.login()
Performs the login process in the LINE's in-app browser or external browser.
You can't use liff.login()
in a LIFF browser, as it is automatically executed when liff.init()
is executed.
The behavior of LINE Login authorization requests within the LIFF browser isn't guaranteed. Also, when opening LIFF apps from an external browser or LINE's in-app browser, make sure to use this method for the login process, not the authorization requests with LINE Login.
# Syntax
liff.login(loginConfig);
# Arguments
loginConfig
Object
Login configurations
loginConfig.redirectUri
String
URL to open in the LIFF app after logging in. The default value is the endpoint URL set when you added the LIFF app to the channel. For details on how to set the endpoint URL, see Adding a LIFF app to your channel.
If redirectUri
is specified, it will be verified whether the specified URL (e.g. https://example.com/path
) matches the domain name and path in Endpoint URL. If there is a mismatch, an error screen will be displayed, and the login process will fail.
if (!liff.isLoggedIn()) {
liff.login({ redirectUri: "https://example.com/path" });
// Verifies whether domain name and path of the specified URL
// (https://example.com/path) match the endpoint URL.
}
It will not be verified whether query parameters (?key=value
) and URL fragments (#URL-fragment
) match. For more information, see URL validation in the LIFF documentation.
# Return value
None
# liff.logout()
# Syntax
liff.logout();
# Arguments
None
# Return value
None
# liff.getAccessToken()
Gets the current user's access token.
You can use the access token obtained with this API to send user data from the LIFF app to the server. For more information, see Using user data in LIFF apps and servers in the LIFF documentation.
The access token is valid for 12 hours after being issued. When the user closes the LIFF app, the access token will be revoked even if it hasn't expired.
If the user starts the LIFF app in a LIFF browser, the LIFF SDK will get an access token when you call
liff.init()
If the user starts the LIFF app in an external browser, the LIFF SDK will get an access token when these steps are satisfied:
- You call
liff.login()
. - The user logs in.
- You call
liff.init()
.
- You call
# Syntax
liff.getAccessToken();
# Arguments
None
# Return value
Returns the current user's access token as a string.
# liff.getIDToken()
Get the raw ID token of the current user obtained by the LIFF SDK. An ID token is a JSON Web Token (JWT) that contains user data.
You can use the ID token obtained with this API when sending the user data from the LIFF app to the server. For more information, see Using user data in LIFF apps and servers in the LIFF documentation.
When adding a LIFF app to your channel, select the openid
scope. You can't get the ID tokens if you don't select the scope, or the users don't grant permission. The scope selections can be changed in the LIFF tab of the LINE Developers Console even after adding the LIFF app.
If the user starts the LIFF app in a LIFF browser, the LIFF SDK will get an ID token when you call
liff.init()
If the user starts the LIFF app in an external browser, the LIFF SDK will get an ID token when these steps are satisfied:
- You call
liff.login()
. - The user logs in.
- You call
liff.init()
.
- You call
To get the email addresses of users, select the email
scope when adding a LIFF app to your channel. You will get the email addresses once the users grant permission. The scope selections can be changed in the LIFF tab of the LINE Developers Console even after adding the LIFF app.
# Syntax
liff.getIDToken();
# Argument
None
# Return value
Returns a raw ID token.
# liff.getDecodedIDToken()
Gets the payload of the ID token that's acquired by the LIFF SDK. The payload includes information such as user display name, profile image URL, email address, etc.
Use this method when you want to use the display name of the user in the LIFF app.
Don't send the user data obtained by this method to the server. For more information, see Using user data in LIFF apps and servers in the LIFF documentation.
When adding a LIFF app to your channel, select the openid
scope. You can't get the ID tokens if you don't select the scope, or users don't grant permission. The scope selections can be changed in the LIFF tab of the LINE Developers Console even after adding the LIFF app.
If the user starts the LIFF app in a LIFF browser, the LIFF SDK will get an ID token when you call
liff.init()
If the user starts the LIFF app in an external browser, the LIFF SDK will get an ID token when these steps are satisfied:
- You call
liff.login()
. - The user logs in.
- You call
liff.init()
.
- You call
To get the email addresses of users, select the email
scope when adding a LIFF app to your channel. You will get the email addresses once the users grant permission. The scope selections can be changed in the LIFF tab of the LINE Developers Console even after adding the LIFF app.
# Syntax
liff.getDecodedIDToken();
# Arguments
None
# Return value
Gets the ID token payload.
For more information on ID token payloads, see the Payload section of Get profile information from ID tokens in the Integrate LINE Login documentation.
# liff.permission.query()
# Syntax
liff.permission.query(permission);
# Arguments
permission
String
The permission to be checked. Specify one of the following scopes:
# Return value
Promise
object returned.
When Promise
is resolved, an object containing the following properties is returned.
state
String
Contains one of the following values:
granted
: User has consented to the authorizationprompt
: User hasn't consented to authorizationunavailable
: Not available because the channel does not have the specified scope
# liff.permission.requestAll()
Displays the "Verification screen" for the permissions requested by LINE MINI Apps.
liff.permission.requestAll()
only operates on LINE MINI Apps.
To execute this method, you need to turn on Channel consent simplification in advance on the LINE Developers Console. For more information on setting up the Channel consent simplification feature, see The "Channel consent simplification" feature setup of the LINE MINI App documentation.
If the user has already consented to all the permissions and you execute liff.permission.requestAll()
, Promise
will be rejected and LiffError
will be returned. Therefore, use liff.permission.query()
to check whether the user has consented to all the permissions, and execute liff.permission.requestAll()
only if the user has unconsented permissions.
# Syntax
liff.permission.requestAll();
# Arguments
None
# Return value
Returns a Promise
object.
# Error response
If Channel consent simplification isn't turned on, and the user has already consented to all the permissions, Promise
will be rejected and LiffError
will be returned.
# Profile
# liff.getProfile()
Gets the current user's profile information.
Don't send the user data obtained by this method to the server. For more information, see Using user data in LIFF apps and servers in the LIFF documentation.
When adding a LIFF app to your channel, select the profile
scope. You can't get user profiles if you don't select the scope, or the user doesn't grant permission. The scope selections can be changed in the LIFF tab of the LINE Developers Console even after adding the LIFF app.
# Syntax
liff.getProfile();
# Arguments
None
# Return value
Returns a Promise
object.
When the Promise
is resolved, the object containing the user's profile information is passed.
userId
String
User ID
displayName
String
Display name
pictureUrl
String
Image URL. This property is not returned if it has not been set by the user.
statusMessage
String
Status message. This property is not returned if it has not been set by the user.
# Error response
When the Promise
is rejected, LiffError
is passed.
# liff.getFriendship()
Gets the friendship status between a user and a LINE Official Account.
However, you can only get the friendship status between a user and a LINE Official Account that has been linked to the same LINE Login channel to which your LIFF app has been added. To learn how to link a LINE Official Account to a LINE Login channel, see Add a LINE Official Account as a friend when logged in (bot link) in the LINE Login documentation.
When adding a LIFF app to your channel, select the profile
scope. You can't get the friendship statuses if you don't select the scope, or the users don't grant permission. The scope selections can be changed in the LIFF tab of the LINE Developers Console even after adding the LIFF app.
# Syntax
liff.getFriendship();
# Arguments
None
# Return value
Returns a Promise
object.
When acquiring the status of friendship, the Promise
is resolved and the information about friendship is passed.
friendFlag
Boolean
true
: The user has added the LINE Official Account as a friend and has not blocked it.- Otherwise,
false
.
# Error response
When the Promise
is rejected, LiffError
is passed.
# Window
# liff.openWindow()
Opens the specified URL in the LINE's in-app browser or external browser.
Use of liff.openWindow()
in an external browser isn't guaranteed.
In LINE for iOS and LIFF v2.16.1 or earlier, if the url
property doesn't contain a query parameter (?key=value
) but contains a URL fragment (#URL-fragment
), a URL with an unintended query parameter added to the end of the URL fragment will be opened.
These are example of URLs opened when executing the liff.openWindow()
method
LIFF SDK version | url property | URL opened |
---|---|---|
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 |
# Syntax
liff.openWindow(params);
# Arguments
params
Object
Parameter object
params.url
String
URL. Specify the absolute path to the URL.
params.external
Boolean
Whether to open the URL in an external browser. Specify one of the following values. The default value is false
.
true
: Opens the URL in an external browser.false
: Opens the URL in the LINE's in-app browser.
# Return value
None
# liff.closeWindow()
Closes the LIFF app.
To use the liff.closeWindow()
method before the initialization of the LIFF app by liff.init()
has finished, your LIFF SDK version must be v2.4.0 or later.
Use of liff.closeWindow()
in an external browser is not guaranteed.
# Syntax
liff.closeWindow();
# Arguments
None
# Return value
None
# Message
# liff.sendMessages()
Sends messages on behalf of the user to the chat screen where the LIFF app is opened. This feature is only available in a LIFF app launched from a one-on-one chat room.
When adding a LIFF app to your channel, select the chat_message.write
scope. Messages can't be sent if you don't select a scope or don't have user authorization. You can select the scope from the LIFF tab on the LINE Developers Console even after adding a LIFF app.
The liff.sendMessages()
method can only be used when the LIFF app is launched with the URL scheme for opening a LIFF app from a one-on-one chat room between users or between a user and a LINE Official Account.
Therefore, the liff.sendMessages()
method isn't available and user doesn't grant required permissions yet
error with error code 403
will occur in the following cases:
- When accessing the LIFF app using the Keep or Keep memo (opens new window) feature
- When accessing a URL scheme for opening a LIFF app through a website redirection process, etc.
- When opening a LIFF app from another LIFF app. For more information, see Opening a LIFF app from another LIFF app (LIFF-to-LIFF transition) in the LIFF documentation.
# Syntax
liff.sendMessages(messages);
# Arguments
messages
Array of objects
Message objects
Max: 5
You can send the following types of Messaging API messages:
- Text message. However, the
emojis
property isn't available. - Sticker message
- Image message
- Video message. However, the
trackingId
property isn't available. - Audio message
- Location message
- Template message. However, only a URI action can be set as an action.
- Flex Message. However, only a URI action can be set as an action.
When messages are sent to a chat that includes a LINE Official Account, the LINE Platform sends webhook events to the bot server. When image, video, and audio messages are sent using the liff.sendMessages()
method, resulting webhook events contain the contentProvider.type
property whose value is external
. For more information, see Message event in the Messaging API reference.
# Return value
Returns a Promise
object.
- If the message is sent successfully, the
Promise
is resolved. No value is passed. - If you fail to send the message, the
Promise
is rejected andLiffError
is passed.
# liff.shareTargetPicker()
Displays the target picker (screen for selecting a group or friend) and sends the message created by the developer to the selected target. This message appears to your group or friends as if you had sent it.
- To view the target picker, turn on the share target picker in the LINE Developers Console. For more information, see Using share target picker.
- When using an external browser, call
liff.login()
, complete the login process, then callliff.shareTargetPicker()
.
In order to protect user privacy, we neither collect nor provide information on how many people received a message from a user through the share target picker.
# Syntax
liff.shareTargetPicker(messages, options);
# Arguments
messages
Array of objects
Message objects
Max: 5
You can send the following types of Messaging API messages:
- Text message
- Image message
- Video message
- Audio message
- Location message
- Template message. However, only a URI action can be set as an action.
- Flex Message. However, only a URI action can be set as an action.
options
Object
Share target picker options
options.isMultiple
Boolean
Specifies whether or not to allow users to select multiple message recipients through the target picker, using either of these values. The default value is true
.
true
: Users can select multiple recipients from their groups, friends, and chats.false
: Users can select only one of their friends as the recipient.
Even if you set the isMultiple
property to false
, you can still send a message to multiple users by calling the share target picker multiple times, or by re-sharing the same message to different recipients. To strictly allow a user to send a message to one friend only once, add a restriction when implementing the LIFF app.
Here's an example of sending a message containing a URL and restricting access to the URL.
- Give the URL a unique token and send the message.
- When the URL in the message is accessed, the server side verifies the token and restricts access by multiple users.
# Return value
Returns a Promise
object.
If the message is sent correctly,
Promise
is resolved and an object with these properties will be passed.status
String
success
If the user cancels and closes the target picker before sending the message,
Promise
is resolved but the object isn't passed.If a problem occurs before the target picker is displayed,
Promise
is rejected andLiffError
is passed. For more information on the LiffError object, see LIFF SDK errors.
In the callback function where Promise
has been resolved and rejected, the LIFF app won't work on some devices if the developer uses alert()
.
# Camera
# liff.scanCodeV2()
Launch the 2D code reader and obtain string. To activate the 2D code reader, turn on Scan QR on the LINE Developers Console.
liff.scanCodeV2()
works in these environments.
- iOS: iOS 14.3 or later, and LINE version 11.7.0 or later
- Android: LINE version 11.7.0 or later
- External browser: Web browsers that support WebRTC API (opens new window)
OS | Version | LINE app version | External browser | |
---|---|---|---|---|
10.17.0-11.6.x | 11.7.0 or later | |||
iOS | 11-14.2 | ❌ | ❌ | ✅ *1 |
14.3 or later | ❌ | ✅ *2 | ✅ *1 | |
Android | All versions | ❌ | ✅ *2 | ✅ *1 |
PC | All versions | ❌ | ❌ | ✅ *1 |
*1 You can only use web browsers that support WebRTC API (opens new window).
*2 Only available when the screen size of the LIFF browser is Full
. For details, see Size of the LIFF browser in the LIFF documentation.
When Adding a LIFF app to your channel, turn on Scan QR. The Scan QR setting can be updated from the LIFF tab on the LINE Developers Console, even after adding a LIFF app to your channel.
liff.scanCodeV2()
internally uses an external library called jsQR (opens new window). Therefore, the 2D code reader to be launched when the liff.scanCodeV2()
method is executed depends on the operation specification of jsQR (opens new window). Libraries used may be updated or changed without notice.
# Syntax
liff.scanCodeV2();
# Arguments
None
# Return value
Returns a Promise
object.
When the string is read by the 2D code reader, Promise
is resolved and the object containing the character string is passed.
value
String
String scanned by the 2D code reader
# Error response
When the Promise
is rejected, LiffError
is passed.
# liff.scanCode()
The traditional liff.scanCode()
method has been deprecated. We recommend using the liff.scanCodeV2()
method for implementing a 2D code reader.
Starts a 2D code reader and gets the string read by the user. To start the 2D code reader, turn on ScanQR
on the LINE Developers Console.
liff.scanCode()
works in these environments.
OS | Version | LINE app version | External browser | |
---|---|---|---|---|
10.17.0-11.6.x | 11.7.0 or later | |||
iOS | All versions | ❌ | ❌ | ❌ |
Android | All versions | ✅ | ✅ | ❌ |
PC | All versions | ❌ | ❌ | ❌ |
Due to technical issues, liff.scanCode
is undefined
in LINE for iOS. Use it after confirming that the function exists, as shown in the sample code. To use the 2D code reader with LINE for iOS or external browsers, see liff.scanCodeV2()
.
- When Adding a LIFF app to your channel, turn on Scan QR. The Scan QR setting can be updated from the LIFF tab on the LINE Developers Console, even after adding a LIFF app to your channel.
- You can't use
liff.scanCode()
in an external browser.
# Syntax
liff.scanCode();
# Arguments
None
# Return value
Returns a Promise
object.
When reading a string by a 2D code reader, the Promise
is resolved and the object containing the string read is passed.
value
String
String read by the 2D code reader
# Permanent link
# liff.permanentLink.createUrlBy()
Get the permanent link of any page in the LIFF app.
Permanent link format:
https://liff.line.me/{liffId}/{path}?{query}#{URL fragment}
# Syntax
liff.permanentLink.createUrlBy(url);
# Arguments
url
String
URL to get the permanent link. Any query parameter can be added to it.
# Return value
Returns a Promise
object.
Returns the string of the permanent link when Promise
is resolved.
# Error responsee
If the URL to get the permanent link doesn't begin with the URL specified for Endpoint URL on the LINE Developers Console, Promise
will be rejected and LiffError
will be returned.
For example, if the URL to get the permanent link (e.g. https://example.com/
) is above Endpoint URL (e.g. https://example.com/path1?q1=v1
), Promise
will be rejected.
# liff.permanentLink.createUrl()
Due to technical issues, liff.permanentLink.createUrl()
may be deprecated in the next major version update. To get the permanent link of the current page, we recommend using liff.permanentLink.createUrlBy()
.
Gets the permanent link for the current page.
Permanent link format:
https://liff.line.me/{liffId}/{path}?{query}#{URL fragment}
# Syntax
liff.permanentLink.createUrl();
# Arguments
None
# Return value
Returns the current page's permanent link as a string.
A LiffError
exception is thrown if the current page URL doesn't start with the URL specified in Endpoint URL of the LINE Developers console.
# liff.permanentLink.setExtraQueryParam()
Due to technical issues, liff.permanentLink.setExtraQueryParam()
may be deprecated in the next major version update. To add any query parameter to a permanent link on the current page, we recommend using liff.permanentLink.createUrlBy()
.
You can add any query parameter to a permanent link on the current page.
Each time you execute liff.permanentLink.setExtraQueryParam()
, the query parameters added last time are overwritten.
- To delete the added query parameters, execute
liff.permanentLink.setExtraQueryParam("")
. - The added query parameters will be discarded when the user navigates to another page.
# Syntax
liff.permanentLink.setExtraQueryParam(extraString);
# Arguments
extraString
String
Query parameters to add
# Return value
None
# Bluetooth plugin
# liff.initPlugins()
Enable the plugins.
For example, if you enable the Bluetooth plugin, you can use the client API (liff.bluetooth.*
) provided by the Bluetooth plugin.
# Syntax
liff.initPlugins(pluginNames);
# Arguments
pluginNames
Array of String
Plugin name. Specify one of the following values:
bluetooth
*The Bluetooth plug-in can only be activated on LINE for Android. When using LINE for iOS, activation fails and a FORBIDDEN error is returned.
# Return value
Returns a Promise
object.
- If the plugin is enabled successfully, the
Promise
is resolved. - If you fail to enable the plugin, the
Promise
is rejected and the error information is passed.
# liff.bluetooth.getAvailability()
Due to a technical issue, liff.bluetooth.getAvailability()
has been suspended on LINE for iOS.
Check if the Bluetooth plugin can be used. Call this method to check the following conditions:
Bluetooth support for the LIFF app added to your channel is enabled
NoteYou must enable the Bluetooth® Low Energy function of the LIFF app added to your channel to initialize the Bluetooth plugin.
Smartphone has Bluetooth enabled
User has accepted the LINE Things Terms of Use
If using LINE on Android, user has granted permission to use smartphone location information
Enable the Bluetooth plugin by using liff.initPlugins() beforehand.
# Syntax
liff.bluetooth.getAvailability();
# Arguments
None
# Return value
Returns a Promise
object.
When the Bluetooth plugin is checked for availability, the Promise
is resolved and a Boolean
object indicating whether or not the Bluetooth plugin can be used is passed.
# liff.bluetooth.requestDevice()
Due to a technical issue, liff.bluetooth.requestDevice()
has been suspended on LINE for iOS.
Scans the linked device, and acquires the information.
You can use a filter to restrict the devices that receive the advertisement packets.
Make sure you first enable the Bluetooth plugin with liff.initPlugins().
# Syntax
liff.bluetooth.requestDevice(options);
# Arguments
options
Object
RequestDeviceOptions
object expressing the filter. Omit to retrieve advertisement packets from all devices.
# Data object
# RequestDeviceOptions object
filters
Array of Object
Array of the LINEBluetoothRequestDeviceFilter
object
# LINEBluetoothRequestDeviceFilter object
deviceId
String
Device ID of the device that receives the advertisement packet
# Return value
Returns a Promise
object.
When scanning linked devices and acquiring the information, the Promise
is resolved and the BluetoothDevice
object indicating information about the devices is passed.
# Data object
# BluetoothDevice object
id
String
Device ID
name
String
device name
gatt
Object
watchingAdvertisements
Boolean
Monitoring status of advertisement packet (*)
Method | Return value | Description |
---|---|---|
watchAdvertisements | Promise <void> | Starts the reception of the advertisement packet. (*) |
unwatchAdvertisements | void | Stops the reception of the advertisement packet. (*) |
addEventListener | void | Registers the event listener. You can register the event listener in advertisementreceived event(*) and gattserverdisconnected event. |
removeEventListener | void | Deletes the already-registered event listener. You can delete the event listener registered in advertisementreceived event(*) and gattserverdisconnected event. |
(*) These functions are implemented on experiment basis. These functions may be changed or stopped without notice.
# BluetoothRemoteGATTServer object
To communicate with devices, use the BluetoothRemoteGATTServer
object that expresses the GATT server (Generic Attribute Profile server).
If Promise
is resolved after executing liff.bluetooth.requestDevice()
, then BluetoothRemoteGATTServer
can be accessed from the gatt
property of the BluetoothDevice
object.
device
Object
connected
Boolean
true
if connected. false
if not connected
Method | Return value | Description |
---|---|---|
connect | Promise <BluetoothRemoteGATTService> | Connects with the device. |
disconnect | void | Disconnects from the GATT server of the device. |
getPrimaryService(serviceUUID) | Promise <BluetoothRemoteGATTService> | Acquires the primary service of the GATT server. Specify a 128-bit UUID as a string in the serviceUUID. Note: This method does not verify the UUID. The UUID is verified when the characteristics are read or written, and when a notification is started or stopped. |
# BluetoothRemoteGATTService object
The BluetoothRemoteGATTService
object is used to acquire the characteristics.
device
Object
uuid
String
GATT Service UUID
Method | Return value | Description |
---|---|---|
getCharacteristic(characteristicUUID) | Promise <BluetoothRemoteGATTCharacteristic> | Acquires the characteristics. Specify a 128-bit UUID as a string in the characteristicUUID. Note: This method does not verify the UUID. The UUID is verified when the characteristics are read or written, and when a notification is started or stopped. |
# BluetoothRemoteGATTCharacteristic object
The BluetoothRemoteGATTCharacteristic
object is used to read or write the characteristic of the devices, and also to start or stop a notification.
service
Object
uuid
String
UUID
value
Object
Method | Return value | Description |
---|---|---|
readValue | Promise <DataView (opens new window)> | Reads the value of the characteristic. |
writeValue(value) | Promise <void> | Writes the ArrayBuffer (opens new window), TypedArray (opens new window), or DataView (opens new window) value to the characteristic. |
startNotifications | Promise <BluetoothRemoteGATTCharacteristic> | Starts the notification of characteristic change. |
stopNotifications | Promise <BluetoothRemoteGATTCharacteristic> | Stops the notification of characteristic change. |
addEventListener | void | Registers the event listener. You can register the event listener in characteristicvaluechanged event containing the target property. |
removeEventListener | void | Deletes the already-registered event listener. You can delete the event listener registered in characteristicvaluechanged event. |
readValue()
method, writeValue()
method, startNotifications()
method, and stopNotifications()
method verify the UUID and properties. If a UUID or property that does not exist is specified, an error occurs.
# Events
# advertisementreceived event
If an advertisement packet is received, the advertisementreceived
event occurs.
The advertisementreceived
event is a function that is implemented on experiment basis. This function may be changed or stopped without notice.
device
Object
name
String
device name
rssi
Number
RSSI
manufacturerData
Object
Map<Number, DataView>object. Data in which the Company Identifier Code is mapped to the DataView
object.
# gattserverdisconnected event
If the Bluetooth connection is disconnected due to various reasons, the gattserverdisconnected
event occurs. Be sure to register the event listener.
# characteristicvaluechanged event
If a characteristic is changed, the characteristicvaluechanged
event occurs.
# liff.bluetooth.referringDevice
Due to a technical issue, liff.bluetooth.referringDevice
has been suspended on LINE for iOS.
When the LIFF app is launched via a device, liff.bluetooth.referringDevice is set to a BluetoothDevice
object that indicates device information.
# LIFF plugin
# liff.use()
Activates and initializes LIFF API in the pluggable SDK or a LIFF plugin.
# Syntax
liff.use(module, option);
# Arguments
module
Object
A LIFF API module in the pluggable SDK or a LIFF plugin.
If you pass a LIFF API module, you need to instantiate the LIFF API module. For more information, see How to use the pluggable SDK in the LIFF documentation.
If you pass a LIFF plugin and the LIFF plugin is a class, you need to instantiate the LIFF plugin. For more information, see Using a LIFF plugin in the LIFF documentation.
# Return value
Returns the liff
object.
# Internationalization
# liff.i18n.setLang()
# Syntax
liff.i18n.setLang(language);
# Arguments
language
String
Language tag as defined in RFC 5646 (BCP 47) (opens new window). If there is no translation for the specified language tag, en
is used as a fallback.
# Return value
Returns a Promise
object.
# Error response
When the Promise
is rejected, LiffError
is passed.