planship-nuxt

歡迎使用 @planship/nuxt，這是一個 Nuxt 模組，可在您的 Nuxt 應用程式中啟用由 Planship 驅動的權限管理、計量、方案包裝和客戶/訂閱管理。此模組基於 @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。slug 也可以透過 PLANSHIP_PRODUCT_SLUG 環境變數定義。

clientId 和 clientSecret

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

用法

Composables

@planship/nuxt 模組匯出由 @planship/vue 外掛程式實作的兩個 composables：usePlanshipCustomer 和 usePlanship。@planship/vue 外掛程式與通用模式相容，表示這些 composables 可以用於伺服器端和用戶端渲染。

使用權限管理和其他客戶資料 - `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 操作，請使用 usePlanshipCustomer 函式傳回的 Planship Customer API 用戶端實例。

以下是使用 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 傳回的權限管理字典時，將其包裝在具有個別 levers 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 customer 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 composables 使用 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)
})