Data4 Trial - Cat

Appearance

Cat 串接範例 ​

本頁面主要提供 Cat 使用前需要設定的環境以及啟動範例

環境準備 ​

html
// for i18n
// 支援中英文介面。將會依照產品端網頁 html 標籤的 lang 屬性自動切換顯示語系。
// `lang` 屬性值為 en 開頭時，會顯示英文介面。其餘都會顯示中文介面。

// for theme
// 並先加上 jtheme="dark" 在 html tag 上。 以此判斷是否為深色模式。 
// 以及加入 jtheme.css 在 head 中。
<html jtheme="dark" lang="zh-TW">
  <head>
    <link rel="stylesheet" href="https://public.hare200.com/theme/jkf/jtheme.css" />
  </head>
</html>

Cat 可以選擇以下方式安裝

bash
pnpm add @lctech-tw/f2e-cat
html
// 使用 Cat 更新公告時宣布的版本安裝
<script src="https://public.hare200.com/cat/v0.13.0/f2e-cat.loader.umd.cjs"></script>

串接範例 ​

請依照標記的數字順序執行串接 Cat 的步驟

  1. 請先設定好 catConfig.ts 內容提及之 Cat 相關設定
  2. 執行 useCatLoader.ts 的 startLoader 完成 Cat 的初始化。
  3. 後續再透過 useCat.ts 的 loaded() 完成後可以拿到 Cat
  4. 建立各項服務接口，例如：usePan，便可以使用 Pan相關服務。

在串接快速導航時遇到開啟位置定位 autoPosition: true 無法滿足定位需求時，請嘗試切換成 autoPosition: false, stickyPointPosition: {} 由產品端自行定義定位方式

ts
import type { RunMode, Data4Cat, CatConfig } from '@lctech-tw/f2e-cat'

/** Cat 實體 */
export let catInstance: Data4Cat

const accessToken = ref('')
const runMode = ref<RunMode>('production') // "alpha" | "beta" | "production"

/** 初始化 Cat */
export const initCat = async () => {
  const catConfig: CatConfig = {
    runMode: runMode.value,
    appId: 'jkforum',
    cookieDomain: 'localhost',
    cookieAppot: 'ap-pot',
    btnActiveColor: '#AA0D31',
    privacyPolicyUrl: 'https://account.jkforum.net/service',
    serviceTermsUrl: 'https://account.jkforum.net/service?tab=terms_and_conditions',
    stickyPointSelectors: {
      avatarCard: '#avatar-card-here',
      productCard: '#product-card-here',
    },
    emailOTCUrl: location.origin,
    resetPasswordEmailLink: 'https://account.jkforum.net',
    resetPasswordSuccessLink: location.origin,
    emailVerificationUrl: location.origin,
    enabledJKTalk: true,
    enabledJPay: true,
    enabledJPoints: true,
    enabledLoginLoading: true,
    allowJPayHandleHistory: true,
    listener: {
      onNoUserLogin() {
        console.log('onNoUserLogin - not logged in yet')
      },
      async onTokenUpdated(token: { auth: string; access: string; tokenFrom: string }) {
        console.groupCollapsed('onTokenUpdate')
        console.table(token)
        console.groupEnd()

        // 由產品端 處理 登入後的 logic，像是 更新產品端 PAT
        accessToken = token.access

        // 情境範例：
        // 產品端呼叫後端 API，耗時 2 秒
        await productLoginApi(2000)
        // 整體 onTokenUpdated resolve 後會自動關閉登入彈窗。
      },
      onMemberSwitch(authToken: string) {
        // 由產品端 處理 切換子帳號後的 logic，像是 更新 PAUT 到產品端
        console.groupCollapsed('onMemberSwitch')
        console.log('PAUT 已更新')
        console.table({ authToken })
        console.groupEnd()
      },
      onAccessTokenFailed(e: unknown): void {
        console.log('PAT 獲取失敗', e)
        // 由產品端 logic 處理 登出後的判斷，像是 更新 PAT
        accessToken.value = ''
      },
      onProductLoggedOut() {
        console.log('用戶已登出')
        // 由產品端 處理 登出後的 logic，像是 清空產品端 PAT 或是 reload
        accessToken.value = ''
      },
      onOauthLoggedOut() {
        console.log('用戶已登出')
        // 由產品端 處理 登出後的 logic，像是 清空產品端 PAT 或是 reload
        accessToken.value = ''
      },
      onLogoutCancel() {
        console.log('產品端 登出取消')
      },
      onLoginClose() {
        console.log('pan 登入器已關閉')
      },
      onUsePointImmediately() {
        console.log('point 觸發立即儲值')
      },
      onContactUs() {
        if (accessToken.value) {
          catInstance.jktalk().goToSpecificPage({
            specificPage: 'talkRoom',
            talkRoomUserHashUid: 'MRZN19KQ',
          })
        } else {
          window.open('https://line.me/R/ti/p/%40xtf9038y', '_blank')
        }
      },
      onNetworkReturnOnline() {
        console.log('觸發網路恢復連線')
      },
      onNetworkOffline() {
        console.log('觸發網路離線')
      },
    },
  }

  // @ts-expect-error
  catInstance = new window.Data4.Cat(catConfig)

  await catInstance.loaded()
}
ts
import type { Data4Cat } from '@lctech-tw/f2e-cat'
import { Data4CatLoader } from '@lctech-tw/f2e-cat/loader'
import { initCat } from '@/composables/catConfig'

/**
  * window.Data4.CatLoader
  * 可用來幫助載入同樣 major 和 minor 版本號，但是 patch 版本號為最新的版本。
  */
const startLoader = () => {
  return new Promise(resolve => {
    // 不填寫中版號時預設會判斷 loader 所在的中版號為主
    const loader = new Data4CatLoader()

    // 可選填指定中版號
    // const loader = new Data4CatLoader('v0.6')

    loader.onLoad(async () => {
      await initCat()

      resolve()
    })

    loader.load()
  })
}

export const loadCatPromise = startLoader()
ts
import type { Data4Cat } from '@lctech-tw/f2e-cat'
import { loadCatPromise } from '@/composables/useCatLoader'
import { catInstance } from '@/composables/catConfig'

const useCat = () => {
  return {
    loaded: async (): Promise<Data4Cat> => {
      await loadCatPromise
      return catInstance
    },
  }
}
ts
import { useCat } from '@/composables/useCat'

const { loaded } = useCat()

const helpers = {
  login: async () => {
    const catInstance = await loaded()
    catInstance.panTools().openOauthLogin()
  },
  logout: async () => {
    const catInstance = await loaded()
    catInstance.panCore().logout()
  },
}

export const usePan = () => {
  return {
    ...helpers,
  }
}

網路連線不穩定提醒 ​

背景情況下，Cat 會幫你偵測當前的網路狀態，當觸發 offline 事件時就會跳出提醒訊息，直到恢復 online 時才自動隱藏提醒訊息使用者也可以透過點擊該提示訊息將其隱藏

此外，當 offline/online 狀態變換時，都可以透過 Cat 設定相關 Callback (onNetworkOffline/onNetworkReturnOnline)