planship
@planship/nuxt

用於 Nuxt 應用的權益、計量、套餐打包和訂閱管理。
95 次下載8 顆星v0.3.10
pwojnaropwojnaro

planship-nuxt

歡迎使用 @planship/nuxt，這是一個 Nuxt 模組，可讓您的 Nuxt 應用在 Planship 的支援下實現權益、計量、套餐打包以及客戶/訂閱管理。此模組基於 @planship/vue 外掛和 @planship/fetch 庫。

使用此模組的完整、可執行的 Nuxt 應用示例可在 https://github.com/planship/planship-nuxt-example 找到。

入門

使用 npm、yarn 或 pnpm 安裝 @planship/nuxt

npm install @planship/nuxt
# or
yarn add @planship/nuxt
# or
pnpm add @planship/nuxt

然後，將 @planship/nuxt 新增到您的 nuxt.config.ts 的 modules 部分

export default defineNuxtConfig({
  modules: ['@planship/nuxt']
})

最後，在 defineNuxtConfig 中或透過環境變數配置您的 Planship 產品 slug 和身份驗證憑據。

export default defineNuxtConfig({
  // ...
  planship: {
    productSlug: '<YOUR_PLANSHIP_PRODUCT_SLUG',
    clientId: '<YOUR_PLANSHIP_API_CLIENT_ID>',
    clientSecret: '<YOUR_PLANSHIP_API_CLIENT_SECRET>'
  }
}

配置選項

productSlug

您的 Planship 產品 slug。該 slug 也可以透過 PLANSHIP_PRODUCT_SLUG 環境變數定義。

clientId 和 clientSecret

您的 Planship 身份驗證憑據。它們也可以透過 PLANSHIP_API_CLIENT_ID 和 PLANSHIP_API_CLIENT_SECRET 環境變數定義。

使用

可組合項

@planship/nuxt 模組匯出了 @planship/vue 外掛實現的兩個可組合函式：usePlanshipCustomer 和 usePlanship。@planship/vue 外掛支援通用模式，這意味著這些可組合函式可用於伺服器端和客戶端渲染。

處理權益和其他客戶資料 - usePlanshipCustomer

在大多數渲染場景中，您的應用程式需要為特定客戶獲取和評估 Planship 權益。這可以透過 Planship 外掛和 usePlanshipCustomer 函式來實現，該函式為特定客戶初始化 Planship API 例項，持續獲取他們的 entitlements，並以響應式 Vue ref 物件的形式公開它們。

以下示例顯示瞭如何檢索客戶權益，以及如何使用名為 advanced-analytics 的簡單布林功能來有條件地渲染 Vue 元件中的 <NuxtLink> 元素。

<script setup>
  import { usePlanshipCustomer } from '@planship/nuxt'

  const { entitlements } = await usePlanshipCustomer('<CURRENT_CUSTOMER_ID>')
</script>

<template>
  <NuxtLink
    v-if="entitlements['advanced-analytics']"
    to="/analytics"
  >
    Analytics
  </NuxtLink>
</template>

當在客戶端使用 usePlanshipCustomer 時，每當權益發生變化時，它們都會透過 WebSocket 連線自動更新。

在通用渲染模式下使用時，資料按以下方式獲取

  1. 外掛在伺服器上初始化，並獲取 Planship 權益和訂閱資料，以便用於伺服器端渲染。
  2. 外掛在客戶端使用已在伺服器上獲取的資料進行初始化。
  3. 外掛在客戶端上重新水合，並啟動 WebSocket 連線以持續從 Planship 獲取權益更新。

sync 和 async 操作的複合返回值

usePlanshipCustomer 函式返回一個複合結果，它既是一個 Promise，也是 Promise 解析到的資料物件。這意味著該函式既可以作為同步函式呼叫，也可以使用 await（或 then/catch 鏈）作為非同步函式呼叫。

如果您想在從 Planship API 獲取客戶權益之前阻塞程式碼執行，請使用 await 呼叫該函式

const { entitlements } = await usePlanshipCustomer('<CURRENT_CUSTOMER_ID>')

如果您想立即返回並非同步獲取權益，只需不帶 await 呼叫 usePlanshipCustomer

const { entitlements } = usePlanshipCustomer('<CURRENT_CUSTOMER_ID>')

由於 entitlements 是一個響應式的 Vue Ref 物件，您可以在元件和頁面模板中使用它，並讓 Nuxt 在權益獲取後自動重新渲染。

從 Planship 獲取額外資料

您的應用程式可能需要從 Planship 獲取額外的客戶資料（例如客戶訂閱或使用資料）。要執行任何 Planship API 操作，請使用由 usePlanshipCustomer 函式返回的 Planship 客戶 API 客戶端例項。

以下是一個 Nuxt 設定指令碼示例，它使用 Nuxt 的 useAsyncData 檢索當前客戶的訂閱列表。

<script setup>
  import { usePlanshipCustomer } from '@planship/nuxt'

  const { planshipCustomerApiClient } = await usePlanshipCustomer('<CURRENT_CUSTOMER_ID>')

  const { data: subscriptions } = await useAsyncData('subscriptions', async () => {
    return await planshipCustomerApiClient.listSubscriptions()
  })
</script>

強型別權益物件

在使用 usePlanshipCustomer 返回的權益字典時，將其包裝在帶有單個槓桿的 getter 的物件中會很有用。這在像 VS Code 這樣的 IDE 中尤其有利，因為它支援 entitlements 的自動完成。

為此，請為您的產品定義一個權益類並將其傳遞給 usePlanshipCustomer。

<script setup>
  import { usePlanshipCustomer, EntitlementsBase } from '@planship/nuxt'

  class MyEntitlements extends EntitlementsBase {
    get apiCallsPerMonth(): number {
      return this.entitlementsDict?.['api-calls-per-month'].valueOf()
    }

    get advancedAnalytics(): boolean {
      return this.entitlementsDict?.['advanced-analytics']
    }
  }

  // entitlements is of Ref<MyEntitlements> type
  const { entitlements } = await usePlanshipCustomer('<CURRENT_CUSTOMER_ID>', MyEntitlements)
</script>

<template>
  <NuxtLink
    v-if="entitlements.advancedAnalytics"
    to="/analytics"
  >
    Analytics
  </NuxtLink>
</template>

處理套餐和其他產品資料 - usePlanship

如果當前客戶上下文未知，usePlanship 函式可以檢索 Planship API 客戶端。它公開了與 usePlanshipCustomer 提供的 Planship 客戶 API 客戶端相同的功能，但所有客戶操作（例如獲取權益和訂閱）都需要 Planship 客戶 ID 作為引數。

以下是一個 Nuxt 設定指令碼示例，它使用 Nuxt 的 useAsyncData 檢索 Planship 套餐列表。

<script setup>
  import { usePlanship } from '@planship/nuxt'

  const { planshipApiClient } = usePlanship()

  const { data: plans } = await useAsyncData('plans', async () => {
    return await planshipApiClient.listPlans()
  })
</script>

伺服器服務

由於 usePlanshipCustomer 和 usePlanship 可組合函式使用 Vue provide/inject 機制，因此它們只能在應用程式元件中使用。為了簡化在元件程式碼之外使用 Planship 資料（例如 伺服器路由），@planship/nuxt 模組提供了在 #planship/server 別名下可用的 useServerApiClient 伺服器服務。

以下是一個 Nuxt API 端點示例，它使用透過 useServerApiClient 伺服器服務函式檢索的 Planship API 客戶端向 Planship API 報告計量使用情況。

import { useServerApiClient } from '#planship/server'

export default defineEventHandler(async (event) => {
  const planship = useServerApiClient()
  const body = await readBody(event)

  // Report usage for api-call metering ID to Planship
  return planship.reportUsage(body.userId, 'api-call', body.count)
})

連結