@chargespot/spjs v0.22.1

Spot JS SDK

Usage

ESM (recommanded)

Install from npm:

npm i @chargespot/spjs

Use it as a normal dependency:

import { showToast } from '@chargespot/spjs'

showToast({ title: 'Hello SPOT' })

Or you want to use it in a scope:

import * as sp from '@chargespot/spjs'

sp.showToast({ title: 'Hello SPOT' })

We write the SDK with TypeScript so all definations are out-of-box.

UMD

The Global module name is sp (window.sp).

You can find a basic UMD example here: https://3ji4i.csb.app/.

<script src="https://unpkg.com/@chargespot/spjs@latest/umd/index.min.js"></script>
<script>
  sp.showToast({ title: 'Hello SPOT' })
</script>

API

There are two styles of API:

• Promise style: Post a message and wait / not wait for the Payload Response.
• Event style: Listening to an event and unlistening with the same callback function.

Promise Style

Resolve with SuccesssPayload and reject with ErrorPayload.

getLocation().then(
  (payload: SuccessPayload) => {
    console.log(payload)
  },
  (error: ErrorPayload) => {
    console.log(error)
  }
)

ErrorPayload

Especially, the type of ErrorPayload is:

Event Style

Pass a callback function which will be called with the SuccessPayload.

Event style API name will always start with on like onFoo.

onLocationChange((payload: SuccessPayload) => {
  console.log(payload)
})

You can cancel the listening by passing same function later.

const handleLocationChange = (payload: SuccessPayload) => {
  console.log(payload)
}

onLocationChange(handleLocationChange)

setTimeout(() => {
  offLocationChange(handleLocationChange)
}, 1000)

Permission

There are many permision scopes related to API call.

SpotApp will show a pop-up asking for user permission for the first time, and return an error message if user deny.

Notice that you will not get the real reason behind the deny response from three of:

1. SpotApp does not have the permission from the native OS.
2. User deny the first time pop-up.
3. The pop-up will be only shown once, and the request will be auto rejected after first time.

Permission Deny ErrorPayload

permit

Pre-asking the specific scope permission, without really calling relatede API

Param

Setting

getSetting

Get the current mini-app scope setting.

SuccessPayload

openSetting

Open mini-app scope setting page, and get the result of setting.

SuccessPayload

import { getLocation, openSetting } from '@chargespot/spjs'

getLocation().catch((e) => {
  if (e.errCode === -2) {
    confirm('the mini-app needs location permission').then(() => {
      openSetting().then(({ permissionSetting }) => {
        if (permissionSetting['scope.userLocation']) {
          toast('thanks!')
          // re-execuate location flow
          // getLocation()
        }
      })
    })
  }
})

Base

canIUse

Check if a function or message name is available.

Both function name or message name are accpeted, JS SDK will convert the function name to the related message name

• function name: chooseCoupon
• message name (with scope): coupon/chooseCoupon

import { canIUse, chooseCoupon } from '@chargespot/spjs'

async function useCoupon() {
  const { available } = await canIUse('chooseCoupon')
  if (!available) return

  // continue
  const { couponId } = await chooseCoupon()
}

Param

SuccessPayload

getSystemInfo

Get the current enviroment information

SuccessPayload

Language will be one of:

enum Language {
  EnUS = 'en_US',
  JaJP = 'ja_JP',
  ThTH = 'th_TH',
  ZhCN = 'zh_CN',
  ZhHK = 'zh_HK',
  ZhTW = 'zh_TW',
}

getLaunchOptions

Get the environment information of how the mini-app launched.

The example below shows a scenario that the mini-app launched by a SpotApp camera scan result:

import { getLaunchOptions } from '@chargespot/spjs'

getLaunchOptions().then((launchOptions) => {
  if (launchOptions.scene === 1011) {
    // https://api.charge-spot.com/device?type=3&uuid=foo
    const launchUrl = launchOptions.query.result
    // uuid === 'foo'
    const { uuid } = parseDeviceUrl(launchUrl)
    window.location.href = `/devicePage/${uuid}`
  }
})

with TypeScript:

import { getLaunchOptions, Scene, ScanSceneQuery } from '@chargespot/spjs'

getLaunchOptions().then((launchOptions) => {
  if (launchOptions.scene === Scene.Scan) {
    const query = launchOptions.query as ScanSceneQuery
    // https://api.charge-spot.com/device?type=3&uuid=foo
    const launchUrl = launchOptions.query.result
    // uuid === 'foo'
    const { uuid } = parseDeviceUrl(launchUrl)
    window.location.href = `/devicePage/${uuid}`
  }
})

SuccessPayload

Scene and SceneQuery

ScanSceneQuery

Notice: You have to register the QR code format (e.g URL prefix) to SpotApp first

CouponSceneQuery

You could use the coupon ID here as the defaultValue of chooseCoupon()

UrlSchemeSceneQuery

You will get the whole url scheme and should parse its query by yourself.

You could launch your mini app by two ways:

• Universal Links: https://sharespot.jp/miniapp?appId=${YOUR_MINI_APP_ID}
• Spot App URL Scheme: spotapp://miniapp?appId=${YOUR_MINI_APP_ID}

Add the launch query on the launchData url query parameter like:

• Universal Links: https://sharespot.jp/miniapp?appId=${YOUR_MINI_APP_ID}&launchData=${encodeURIComponent('fooBar?')}
• Spot App URL Scheme: spotapp://miniapp?appId=${YOUR_MINI_APP_ID}&launchData=${encodeURIComponent('fooBar?')}

And you will obtain the whole value of launchData.

Note: only the value on launchData will be accpeted.

MapSceneQuery

OrderSceneQuery

OrderStatus

ReservationSceneQuery

openAction

Redirect to ShareSPOT Native Page with url and related launch options.

URL provided in other documents.

Param

ErrorPayload

UI

showToast

Show a native toast.

Param

setNavigationBarColor

Change color of the Top Navigation Bar.

Param

Auth

login

Get the code for the auth flow. A basic auth flow is like:

1. Your Web Application: When the miniapp launching, call the login() and send the code to your backend.
2. Your Backend Service: Send the code with other information to the SPOT Open API.
3. Your Backend Service: Get the SPOT User Identity for your service. Register or obtain the User in your service.
4. Your Web Application: Get your user information.

Check the SPOT Open API Document for more detailed information.

// Call the login() when the miniapp launched
async function getUser() {
  const localUserString = window.localStorage.getItem('user')
  if (localUserString) return JSON.parse(localUserString)
  const {code} = await login()

  // pass the code to your back-end
  const user = fetch(`/user/login?spot_login_code=${code}`)

  // save to the local
  window.localStorage.setItem('user', JSON.stringify(user))
  return user
}

Code Expired

The code you recevied:

1. Could only be used one time.
2. Should be used in 5 minutes.

Therefore, the code will be expired (You will get 401 from our SPOT Open API) when:

1. The code has been used once time.
2. The code is issued 5 miniutes ago.

SuccessPayload

getUserProfile

Get non-sensitive user info in the Spot App.

SuccessPayload

UserInfo

Device

scanCode

Call a native QR code reader and get the result

SuccessPayload

setClipboardData

Set string data into the clipboard

Param

makePhoneCall

Make a phone call like tel: URI in <a> tag.

Param

makePhoneCall({ phoneNumber: '+81-90-0000-0000' })

sendMail

Send email like mailto: in <a> tag, but only few fields (in https://datatracker.ietf.org/doc/html/rfc6068) are supported.

Only one recipent is supported, separators like , or ; in to field are not working.

Param

Share

setShareInfo

Set the information for twitter / facebook share.

Param

showShareMenu

Show Share Bottom Menu, value from setShareInfo

shareTo

Directly call the native share method, it behaviours equivalent to call showShareMenu() and click the platform

setShareInfo({ title: 'my mini app' })

function onTwitterButtonClick() {
  shareTo({ platform: 'twitter' })
}

function onShareButtonClick() {
  showShareMenu()
}

Param

SharePlatform will be one of:

type SharePlatform =
  | 'line'
  | 'twitter'
  | 'facebook'
  | 'messenger'
  | 'mail'
  | 'wechatMessage'
  | 'wechatMoments'
  | 'copyLink'
  | 'system'

Coupon

chooseCoupon

Open a native dialog to guide user choose their coupon.

There are 4 scenes of calling the method:

1. SuccessPayload with couponId: User has coupon and select a coupon.
2. SuccessPayload with no couponId: User has coupon and decide not using.
3. ErrorPayload with -1 ErrCode: User close the native dialog with exit current flow.
4. SuccessPayload with no couponId: User has no coupon. native dialog will not be shown.

A typical code example will be:

async function makePayment() {
  const { couponId } = await chooseCoupon({ defaultCouponId: 'foo' })
  // if an cancel error occur, the flow will not continue
  await request('/make-my-mini-app-payment', { data: { couponId } })
}

Param

SuccessPayload

ErrorPayload

Payment

requestBindPayment

Call a native Popover to help user add / bind or update a legal payment method.

You should call this method after your back-end request SPOT payment failed, and:

• Re-call your back-end after this method successed
• Show error message after this method failed

ErrorPayload

Location

getLocation

Get current location.

SuccessPayload

ErrorPayload

startLocationUpdate

Enable location real-time updating feature

stopLocationUpdate

Disable location real-time updating feature

onLocationChange

Get the real-time location result

SuccessPayload

As same as getLocation

offLocationChange

Stop listening location change event

navigateLocation

Navigate to specific location, from current location.

Param

navigateLocation({
  latitude: 35.680323,
  longitude 139.764582,
  name: 'Yurakucho',
})

Bluetooth

A simplest Bluetooth flow is:

1. openBluetoothAdapter()
2. startBluetoothDevicesDiscovery()
3. getBluetoothDevices()
4. createBLEConnection()
5. getBLEDeviceServices()
6. getBLEDeviceCharacteristics()
7. readBLECharacteristicValue()
8. writeBLECharacteristicValue()

openBluetoothAdapter

Open Bluetooth adpater.

closeBluetoothAdapter

Close Bluetooth adapter

getBluetoothAdapterState

Get current bluetooth adapter state

SuccessPayload

AdapterState

onBluetoothAdapterStateChange

Listen Bluetooth adapter state change event

SuccessPayload

offBluetoothAdapterStateChange

Unlisten Bluetooth adapter state change event

startBluetoothDevicesDiscovery

Start discovering devices

Param

startBluetoothDevicesDiscovery({
  allowDuplicatesKey: false,
  interval: 300,
}).catch((error: ErrorPayload) => {
  console.log(error)
})

stopBluetoothDevicesDiscovery

Stop discv

Error Payload

TBD.

getBluetoothDevices

Get discovered devices during start and end

SuccessPayload

Device

Example

async function getDevices() {
  await startBluetoothDevicesDiscovery()

  const { devices } = await getBluetoothDevices()
  devices.map((device) => {
    console.log(device.name) // 'My MacBook Pro'
  })
}

onBluetoothDeviceFound

New devices found event

SuccessPayload

offBluetoothDeviceFound

Pair with onBluetoothDeviceFound

createBLEConnection

Create BLE Connection with device

Param

Example

createBLEConnection({ deviceId: '629FA080-FACC-8DEB-8C57-40985EC4A153' })

closeBLEConnection

close connection with the specific device.

Param

onBLEConnectionStateChange

Listen to the connection state change event

SuccessPayload

Example

createBLEConnection({ deviceId: '629FA080-FACC-8DEB-8C57-40985EC4A153' })

onBLEConnectionStateChange((payload) => {
  console.log(payload.deviceId) // '629FA080-FACC-8DEB-8C57-40985EC4A153'
  console.log(payload.connected) // true
})

offBLEConnectionStateChange

Pair with onBLEConnectionStateChange

getBLEDeviceRSSI

Get device RSSI

Param

SuccessPayload

getBLEDeviceServices

Get device service list

Param

SuccessPayload

DeviceService

getBLEDeviceCharacteristics

Get device service list

Param

SuccessPayload

DeviceCharacteristic

DeviceCharacteristicProperty

readBLECharacteristicValue

Read characteristic value.

Notice: You will get response on onBLECharacteristicValueChange event

Param

onBLECharacteristicValueChange

Listen characteristic changing.

SuccessPayload

Example

readBLECharacteristicValue({
  deviceId: 'foo',
  serviceId: 'bar',
  characteristicId: 'baz',
})

// get the read result from the event
onBLECharacteristicValueChange(
  ({ deviceId, serviceId, characteristicId, value }) => {
    console.log(deviceId) // 'foo'
    console.log(serviceId) // 'bar'
    console.log(characteristicId) // 'baz'
    console.log(value) // 'YmFzZTY0IGRlY29kZXI='
  }
)

offBLECharacteristicValueChange

Pair with onBLECharacteristicValueChange

writeBLECharacteristicValue

Param

notifyBLECharacteristicValueChange