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 连接自动更新。
在通用渲染模式下使用时,数据按以下方式获取
- 插件在服务器上初始化,并获取 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 客户 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)
})