LINE Things API reference

This page will be available in English soon.

LIFF Bluetooth LE plugin API

liff.bluetooth.getAvailability()

以下の内容を確認し、Bluetoothプラグインが利用できるかどうかを調べます。

  • チャネルのBluetoothサポートの有無
  • Bluetooth設定
  • LINE Thingsの利用規約に同意していること
  • 位置情報の取得権限(Androidのみ)

構文

liff.bluetooth.getAvailability(): Promise<Boolean>

戻り値

Bluetoothプラグインが利用できるかどうか(Booleanオブジェクト)を含むPromiseオブジェクトが返されます。

// sample
liff.bluetooth.getAvailability().then(available => {
    alert('available?' + available);
});

liff.bluetooth.requestDevice()

デバイス連携済みのLINE Things対応デバイスをスキャンします。

条件に一致したデバイスからのアドバタイズメントパケットを受信すると、LINE Things対応デバイスの情報を取得できます。

構文

liff.bluetooth.requestDevice(options?: RequestDeviceOptions): Promise<BluetoothDevice>;

引数

プロパティ タイプ 必須 説明
options RequestDeviceOptions 任意 アドバタイズメントパケットを受け入れるデバイスを制限するためのRequestDeviceOptionsオブジェクト。省略したときは、すべてのデバイスからのアドバタイズメントパケットを受け入れます。

戻り値

LINE Things対応デバイスの情報(BluetoothDeviceオブジェクト)を含むPromiseオブジェクトが返されます。

requestDevice()(フィルタを指定しない場合)とBluetoothDeviceオブジェクトの使用例

liff.bluetooth.requestDevice().then(device => {
    const listener = (e) => {
      const key = e.manufacturerData.keys().next();
      console.log('compnay identifyer: 0x0' + id.value.toString(16) + ' rssi:' + e.rssi);
      const value = e.manufacturerData.get(key);
      device.removeEventListener('advertisementreceived', listener);
    };
    device.addEventListener('advertisementreceived', listener);

    device.watchAdvertisements();
}).catch(e => {
    console.log(e.code + ':' + e.message);
});

requestDevice()(フィルタを指定する場合)とBluetoothDeviceオブジェクトの使用例

liff.bluetooth.requestDevice({
        filters: [
            {
                deviceId: 't99137fe055dd4980b40f6ac526da7b0b' // ID of desired bluetooth device (BluetoothDevice.id)
            }
        ]
    }).then(device => {
    const listener = (e) => {
      const key = e.manufacturerData.keys().next();
      console.log('compnay identifyer: 0x0' + id.value.toString(16) + ' rssi:' + e.rssi);
      const value = e.manufacturerData.get(key);
      device.removeEventListener('advertisementreceived', listener);
    };
    device.addEventListener('advertisementreceived', listener);

    device.watchAdvertisements();
}).catch(e => {
    console.log(e.code + ':' + e.message);
});

Objects

RequestDeviceOptionsオブジェクト
プロパティ タイプ 必須 説明
filters LINEBluetoothRequestDeviceFilterの配列 必須 LINEBluetoothRequestDeviceFilterオブジェクトの配列

LINEBluetoothRequestDeviceFilterオブジェクト
プロパティ タイプ 必須 説明
deviceId string 必須 アドバタイズメントパケットを受け入れるデバイスのデバイスID

BluetoothDeviceオブジェクト
プロパティ タイプ 必須 説明
id string 必須 LINE Things対応デバイスのデバイスID
name string 任意 LINE Things対応デバイスがアドバタイズメントパケットで送信しているデバイス名
gatt BluetoothRemoteGATTServer 任意 BluetoothRemoteGATTServerオブジェクト
watchingAdvertisements boolean 必須 アドバタイズメントパケットの監視状況(※)
メソッド 戻り値 説明
watchAdvertisements Promise<void> アドバタイズメントパケットの受け入れを開始します。(※)
unwatchAdvertisements void アドバタイズメントパケットの受け入れを停止します。(※)
addEventListener イベントリスナーを登録します。advertisementreceivedイベント(※)とgattserverdisconnectedイベントの2つのイベントをサポートしています。
removeEventListener 登録済みのイベントリスナーを削除します。advertisementreceivedイベント(※)とgattserverdisconnectedイベントの2つのイベントをサポートしています。

watchingAdvertisementsプロパティ、watchAdvertisements()unwatchAdvertisements()advertisementreceivedイベントは、試験的に実装している機能です。これらの機能は予告なく変更、または停止される可能性があります。

BluetoothRemoteGATTServerオブジェクト

LINE Things対応デバイスと通信するには、GATTサーバー(汎用アトリビュートプロファイルサーバー)を表すBluetoothRemoteGATTServerオブジェクトを使用します。

liff.bluetooth.requestDevice()実行後、Promiseが解決(resolve)すると、BluetoothDeviceオブジェクトのgattプロパティから、BluetoothRemoteGATTServerにアクセスできます。

プロパティ タイプ 必須 説明
device BluetoothDevice 必須 BluetoothDeviceオブジェクト
connected boolean 必須 接続している場合はtrue。接続していない場合はfalse
メソッド 戻り値 説明
connect Promise<BluetoothRemoteGATTService> LINE Things対応デバイスと接続します。
disconnect void LINE Things対応デバイス(GATTサーバー)から切断します。
getPrimaryService(serviceUUID: string) Promise<BluetoothRemoteGATTService> GATTサーバーのプライマリサービスを取得します。serviceUUIDには、128ビットのUUIDを指定します。
注:このメソッドはUUIDを検証しません。UUIDの検証は、characteristicの読み込み、書き込み、通知の開始、通知の停止を実行する際に行われます。

BluetoothRemoteGATTServiceオブジェクト

BluetoothRemoteGATTServiceオブジェクトは、characteristicを取得するためのオブジェクトです。

プロパティ タイプ 必須 説明
device BluetoothDevice 必須 BluetoothDeviceオブジェクト
uuid string 必須 GATT Service UUID
メソッド 戻り値 説明
getCharacteristic(characteristicUUID: string) Promise<BluetoothRemoteGATTCharacteristic> characteristicを取得します。characteristicUUIDには、128ビットのUUIDを指定します。
注:このメソッドはUUIDを検証しません。UUIDの検証は、characteristicの読み込み、書き込み、通知の開始、通知の停止を実行する際に行われます。

BluetoothRemoteGATTCharacteristicオブジェクト

BluetoothRemoteGATTCharacteristicオブジェクトは、LINE Things対応デバイスのcharacteristicの読み込み、書き込み、通知の開始、通知の停止を実行するためのオブジェクトです。

プロパティ タイプ 必須 説明
service BluetoothRemoteGATTService 任意 BluetoothRemoteGATTServiceオブジェクト
uuid string 必須 UUID
value DataView 任意 DataView
メソッド 戻り値 説明
readValue Promise<DataView> characteristicの値を読み取ります。
writeValue(value: BufferSource) Promise<void> characteristicに値を書き込みます。
startNotifications Promise<BluetoothRemoteGATTCharacteristic> characteristic変更の通知を開始します。
stopNotifications Promise<BluetoothRemoteGATTCharacteristic> characteristic変更の通知を停止します。
addEventListener イベントリスナーを登録します。targetプロパティを含むcharacteristicvaluechangedイベントをサポートしています。
removeEventListener 登録済みのイベントリスナーを削除します。characteristicvaluechangedイベントをサポートしています。

注:readValue()writeValue()startNotifications()stopNotifications()は、UUIDとプロパティを検証します。存在しないUUIDやプロパティを指定した場合は、エラーが発生します。

characteristicの値を読み込み、書き込みする例

device.gatt
    .connect()
    .then(async () => {
        const service = await device.gatt.getPrimaryService(
            '01234567-0123-0123-0123-012345678901'
        );
        const characteristic = await service.getCharacteristic(
            '01234567-0123-0123-0123-012345678902'
        );
        const value = await characteristic.readValue();

        // suppose we know it is a string, we can decode it
        // here we use TextDecoder for simplicity, you should add a polyfill for compatibility
        const stringValue = new TextDecoder().decode(value);

        // to write string 'liff' into the characteristic
        // here we use TextEncoder for simplicity, you should add a polyfill for compatibility
        await characteristic.writeValue(new TextEncoder().encode('liff'));
    })
    .catch(e => {
        console.log(e.code + ':' + e.message);
    });

characteristicの値の変更を通知させる例

device.gatt.connect().then(async () => {
    const service = await device.gatt.getPrimaryService('01234567-0123-0123-0123-012345678901');
    const characteristic = await service.getCharacteristic('01234567-0123-0123-0123-012345678903');
    characteristic.addEventListener('characteristicvaluechanged', (e) => {
        // suppose we know it is a 16-bit integer value
        console.log('value changed to:' + e.target.value.getInt16();
    });

    await characteristic.startNotifications();
}).catch(e => {
    console.log(e.code + ':' + e.message);
});

Events

advertisementreceivedイベント

アドバタイズメントパケットを受信すると、advertisementreceivedイベントが発生します。

注:advertisementreceivedイベントは、試験的に実装している機能です。この機能は予告なく変更、または停止される可能性があります。

プロパティ タイプ 必須 説明
device BluetoothDevice 必須 BluetoothDeviceオブジェクト
name string 任意 LINE Things対応デバイス名
rssi number 任意 RSSI
manufacturerData Map<number, DataView> 任意 LINE Things対応デバイスが設定したデータ

gattserverdisconnectedイベント

さまざまな理由でBluetooth接続が切断されると、gattserverdisconnectedイベントが発生します。必ずイベントリスナーを登録してください。

gattserverdisconnectedイベントのイベントリスナーを登録する例

liff.bluetooth
    .requestDevice()
    .then(device => {
        device.addEventListener('gattserverdisconnected', () => {
            console.log('device gatt is disconnected');
        });

        window.gatt.connect();
    })
    .catch(e => {
        console.log(e.code + ':' + e.message);
    });

characteristicvaluechangedイベント

characteristicが変更されると、characteristicvaluechangedイベントが発生します。

Errors

LIFF Bluetooth LEプラグインAPIのエラーは、LIFFErrorオブジェクトで返されます。

LiffErrorオブジェクト

プロパティ タイプ 必須 説明
code String 必須 コード
message String 任意 メッセージ。定義されたメッセージが存在する場合に返されます。

エラー内容

コード メッセージ 説明
INIT_FAILED Failed to init LIFF SDK LIFF SDKのJavaScriptリソースをロードできませんでした。
INIT_FAILED Could not authenticate LIFF app JWTトークンが無効または存在しません。LINEでLIFFを起動してください。また、JWTトークンは必ず指定してください。
INVALID_ARGUMENT - 引数が無効です。
INTERNAL_ERROR - 内部エラーです。
THINGS_NO_LINKED_DEVICES There are no linked devices. LINE Things対応デバイスがありません。
BLUETOOTH_CONNECT_FAILED Failed to connect to device. LINE Things対応デバイスとの接続に失敗しました。
BLUETOOTH_ALREADY_CONNECTED The device is already connected. LINE Things対応デバイスは接続済みです。
BLUETOOTH_CONNECTION_LOST The device has been disconnected. LINE Things対応デバイスが接続されていません。
BLUETOOTH_UNSUPPORTED_OPERATION The operation is not supported on this characteristic. 指定したcharacteristicでは、指定した操作がサポートされていません。
BLUETOOTH_SERVICE_NOT_FOUND The service is not found in the GATT server. 指定したサービスが、GATTサーバーに存在しません。
BLUETOOTH_CHARACTERISTIC_NOT_FOUND The charactersitic is not found in the service. 指定したcharacteristicが、サービスに存在しません。

{
  "code":"INIT_FAILED",
  "message":"Failed to init LIFF SDK"
}

LINE Things-compatible device management API

注:Windows 10を使用している場合など、curlコマンドを使用できないときは、他のコマンドで代用します。詳しくは、「REST APIを利用する」を参照してください。

Get product ID and PSDI by device ID

デバイスIDを指定して、プロダクトIDとPSDIを取得します。デバイス連携イベントやデバイス連携解除イベントで取得したデバイスIDから、プロダクトIDとPSDIを取得するときに使います。

デバイスID、プロダクトID、PSDIについては、「作業の流れ」を参照してください。

HTTPリクエスト

GET https://api.line.me/things/v1/devices/{deviceId}

リクエストヘッダー

リクエストヘッダー 説明
Authorization Bearer {channel access token}

パスパラメータ

パラメータ 説明
deviceId デバイスID

リクエストの例

curl -X GET https://api.line.me/things/v1/devices/{deviceId} \
-H "Authorization: Bearer {channel access token}" \

レスポンス

ステータスコード200と以下のプロパティを含むJSONオブジェクトを返します。

プロパティ タイプ 説明
id String デバイスID
productId Number プロダクトID
productSpecificDeviceId String PSDI。PSDIは、LINE Things対応デバイスの開発者が、デバイスごとに設定した値です。

レスポンスの例

{
  "id": "{deviceId}",
  "productId": {productId},
  "productSpecificDeviceId": "{PSDI}"
}

エラーレスポンス

以下のいずれかのステータスコードを返します。

ステータスコード 説明
401 認証に失敗しました。
404 以下のどちらかです。
  • デバイスが見つかりません。
  • アクセス権がありません。

Get device information by device ID and user ID

デバイスIDとユーザーIDを指定して、デバイスの情報を取得します。

HTTPリクエスト

GET https://api.line.me/things/v1/devices/{deviceId}/users/{userId}/link

リクエストヘッダー

リクエストヘッダー 説明
Authorization Bearer {channel access token}

パスパラメータ

パラメータ 説明
deviceId デバイスID
userId ユーザーID
ユーザーIDの値は、U[0-9a-f]{32}の正規表現にマッチする文字列です。

リクエストの例

curl -X GET https://api.line.me/things/v1/devices/{deviceId}/users/{userId}/link \
-H "Authorization: Bearer {channel access token}" \

レスポンス

ステータスコード200と以下のプロパティを含むJSONオブジェクトを返します。

プロパティ タイプ 説明
userId String ユーザーID
ユーザーIDの値は、U[0-9a-f]{32}の正規表現にマッチする文字列です。
device.id String デバイスID
device.productId Number プロダクトID
device.productSpecificDeviceId String PSDI
PSDIは、LINE Things対応デバイスの開発者が、デバイスごとに設定した値です。
deviceDisplayName String プロダクト名
LINE Things Developer Trialでは、「トライアルプロダクトを作成する」で設定したトライアルプロダクト名です。

レスポンスの例

{
  "userId": "{userId}",
  "device": {
    "id": "{deviceId}",
    "productId": {productId},
    "productSpecificDeviceId": "{PSDI}"
  },
  "deviceDisplayName": "{Product Name}"
}

エラーレスポンス

以下のいずれかのステータスコードを返します。

ステータスコード 説明
401 認証に失敗しました。
404 以下のどちらかです。
  • デバイスが見つかりません。
  • アクセス権がありません。

Get device information by product ID and user ID

プロダクトIDとユーザーIDを指定して、デバイスの情報を取得します。

HTTPリクエスト

GET https://api.line.me/things/v1/products/{productId}/users/{userId}/links

リクエストヘッダー

リクエストヘッダー 説明
Authorization Bearer {channel access token}

パスパラメータ

パラメータ 説明
productId プロダクトID
userId ユーザーID。ユーザーIDの値は、U[0-9a-f]{32}の正規表現にマッチする文字列です。

リクエストの例

curl -X GET https://api.line.me/things/v1/products/{productId}/users/{userId}/links \
-H "Authorization: Bearer {channel access token}" \

レスポンス

ステータスコード200と以下のプロパティを含むJSONオブジェクトを返します。

プロパティ タイプ 説明
items[].userId String ユーザーID
ユーザーIDの値は、U[0-9a-f]{32}の正規表現にマッチする文字列です。
items[].device.id String デバイスID
items[].device.productId Number プロダクトID
items[].device.productSpecificDeviceId String PSDI
PSDIは、LINE Things対応デバイスの開発者が、デバイスごとに設定した値です。
items[].deviceDisplayName String プロダクト名
LINE Things Developer Trialでは、「トライアルプロダクトを作成する」で設定したトライアルプロダクト名です。

レスポンスの例

{
  "items": [
    {
      "userId": "{userId}",
      "device": {
        "id": "{deviceId}",
        "productId": {productId},
        "productSpecificDeviceId": "{PSDI}"
      },
      "deviceDisplayName": "{Product Name}"
    },
    {
      "userId": "{userId}",
      "device": {
        "id": "{deviceId}",
        "productId": {productId},
        "productSpecificDeviceId": "{PSDI}"
      },
      "deviceDisplayName": "{Product Name}"
    }
  ]
}

エラーレスポンス

以下のいずれかのステータスコードを返します。

ステータスコード 説明
401 認証に失敗しました。
404 以下のどちらかです。
  • デバイスが見つかりません。
  • アクセス権がありません。

Create trial product information

プロダクト名とLIFFアプリIDを指定して、トライアルプロダクトを作成します。

HTTPリクエスト

POST https://api.line.me/things/v1/trial/products

リクエストヘッダー

リクエストヘッダー 説明
Authorization Bearer {channel access token}
Content-Type application/json

リクエストボディ

フィールド タイプ 説明
name String プロダクト名
liffId String LIFFアプリID

リクエストの例

curl -X POST https://api.line.me/things/v1/trial/products \
-H "Authorization: Bearer {channel access token}" \
-H "Content-Type: application/json" \
-d '{
  "name": "{trial product name}",
  "liffId": "{LIFF APP ID}"
}'

レスポンス

ステータスコード200と以下のプロパティを含むJSONオブジェクトを返します。

プロパティ タイプ 説明
id Number プロダクトID
LINEプラットフォームに作成したトライアルプロダクトを識別するためのIDです。
name String プロダクト名
type String プロダクトタイプ("BLE"のみ)
channelId Number プロダクトに関連付けられているMessaging APIのチャネルのチャネルID
actionUri String LIFFアプリのURL
serviceUuid String サービス探索用service UUID
LINE Things対応デバイスがペアリングのためにアドバタイズするパケットに含めてください。このUUIDは、自動採番されます。
psdiServiceUuid String プロダクト単位でデバイスを識別する値を持つ、(characteristicが所属する)デバイス特定用service UUID ※
psdiCharacteristicUuid String プロダクト単位でデバイスを識別する値を持つ、デバイス特定用characteristic UUID ※

※LINE Things対応デバイスは、psdiServiceUuidpsdiCharacteristicUuidで特定できるcharacteristicに、プロダクト単位でデバイスを一意に識別する値を記録してください。

レスポンスの例

{
  "id": {productId},
  "name": "{trial product name}",
  "actionUri": "{LIFF APP URL}",
  "channelId": {channelId},
  "type": "BLE",
  "serviceUuid": "{serviceUuid}",
  "psdiServiceUuid": "{psdiServiceUuid}",
  "psdiCharacteristicUuid": "{psdiCharacteristicUuid}"
}

エラーレスポンス

以下のいずれかのステータスコードを返します。

ステータスコード 説明
400 リクエストに無効な値が含まれています。
401 認証に失敗しました。
403 すでにトライアルプロダクトの上限個数(最大10個)に達しています。不要なトライアルプロダクトを削除してください。

Get trial product information

トライアルプロダクトを取得します。

HTTPリクエスト

GET https://api.line.me/things/v1/trial/products

リクエストヘッダー

リクエストヘッダー 説明
Authorization Bearer {channel access token}

リクエストの例

curl -X GET https://api.line.me/things/v1/trial/products \
-H "Authorization: Bearer {channel access token}" \

レスポンス

ステータスコード200と以下のプロパティを含むJSONオブジェクトを返します。

プロパティ タイプ 説明
[].id Number プロダクトID
[].name String プロダクト名
[].actionUri String LIFFアプリのURLです。
[].channelId Number プロダクトに関連付けられているMessaging APIのチャネルのチャネルID
[].type String プロダクトタイプ("BLE"のみ)
[].serviceUuid String プロダクトのサービス探索用service UUID。このUUIDは、自動採番されます。
[].psdiServiceUuid String プロダクト単位でデバイスを識別する値を持つ、(characteristicが所属する)デバイス特定用service UUID ※
[].psdiCharacteristicUuid String プロダクト単位でデバイスを識別する値を持つ、デバイス特定用characteristic UUID ※

※LINE Things対応デバイスは、psdiServiceUuidpsdiCharacteristicUuidで特定できるcharacteristicに、プロダクト単位でデバイスを一意に識別する値を記録してください。

レスポンスの例

[
  {
    "id": {productId},
    "name": "{trial product name}",
    "actionUri": "{LIFF APP URL}",
    "channelId": {channelId},
    "type": "BLE",
    "serviceUuid": "{serviceUuid}",
    "psdiServiceUuid": "{psdiServiceUuid}",
    "psdiCharacteristicUuid": "{psdiCharacteristicUuid}"
  }
]

エラーレスポンス

以下のいずれかのステータスコードを返します。

ステータスコード 説明
401 認証に失敗しました。

Delete trial product information

プロダクトIDを指定して、トライアルプロダクトを削除します。

HTTPリクエスト

DELETE https://api.line.me/things/v1/trial/products/{productId}

リクエストヘッダー

リクエストヘッダー 説明
Authorization Bearer {channel access token}

パスパラメータ

パラメータ 説明
productId プロダクトID

リクエストの例

curl -X DELETE https://api.line.me/things/v1/trial/products/{productId} \
-H "Authorization: Bearer {channel access token}" \

レスポンス

ステータスコード204を返します。

エラーレスポンス

以下のいずれかのステータスコードを返します。

ステータスコード 説明
401 認証に失敗しました。
404 以下のどちらかです。
  • トライアルプロダクトが見つかりません。
  • アクセス権がありません。