planship-nuxt

歡迎使用 @planship/nuxt，這是一個 Nuxt 模組，可讓您在由 Planship 驅動的 Nuxt 應用程式中啟用授權、計量、方案包裝和客戶/訂閱管理。此模組基於 @planship/vue 外掛程式和 @planship/fetch 函式庫。

您可以在 https://github.com/planship/planship-nuxt-example 找到使用此模組的 Nuxt 應用程式完整工作範例。

開始使用

使用 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。也可以透過 PLANSHIP_PRODUCT_SLUG 環境變數定義 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 連線自動更新授權。

在通用呈現模式中使用時，會以下列方式擷取資料

外掛程式會在伺服器上初始化，並擷取 Planship 授權和訂閱資料，以便將它們用於伺服器端呈現。
外掛程式會使用伺服器上已擷取的資料在用戶端上初始化。
外掛程式會在用戶端上重新啟用，並啟動 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 作業，請使用 Planship 客戶 API 用戶端的執行個體，該執行個體由 usePlanshipCustomer 函式傳回。

以下是使用 Nuxt 的 useAsyncData 擷取目前客戶訂閱清單的 Nuxt 設定指令碼範例。

<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 的 useAsyncData 擷取 Planship 方案清單的 Nuxt 設定指令碼範例。

<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 提供/注入機制，因此它們只能在應用程式元件中使用。為了簡化在元件程式碼外部使用 Planship 資料（例如，伺服器路由），@planship/nuxt 模組提供 useServerApiClient 伺服器服務，該服務可在 #planship/server 別名中使用。

以下是 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)
})