planship
@planship/nuxt

Nuxtアプリ向けに、エンタイトルメント、メータリング、プランパッケージング、サブスクリプション管理を提供します。
95ダウンロード8スターv0.3.10
pwojnaropwojnaro

planship-nuxt

Planship(https://planship.io)を利用してNuxtアプリでエンタイトルメント、メータリング、プランパッケージング、顧客/サブスクリプション管理を可能にするNuxtモジュール、@planship/nuxtへようこそ。このモジュールは、@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の製品スラッグと認証情報を設定します。

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

設定オプション

productSlug

Planshipの製品スラッグ。このスラッグは、PLANSHIP_PRODUCT_SLUG環境変数で定義することもできます。

clientIdとclientSecret

Planshipの認証情報。これらは、PLANSHIP_API_CLIENT_IDおよびPLANSHIP_API_CLIENT_SECRET環境変数で定義することもできます。

使用方法

コンポーザブル

@planship/nuxtモジュールは、@planship/vueプラグインによって実装された2つのコンポーザブル、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. プラグインはクライアントで自身を再ハイドレートし、Planshipからの継続的なエンタイトルメント更新のためにwebsocket接続を開始します。

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によって返されるエンタイトルメント辞書を操作する場合、個々のレバーのゲッターを持つオブジェクトにラップすると便利です。これは、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のprovide/injectメカニズムを使用しているため、アプリケーションコンポーネント内でのみ使用できます。コンポーネントコードの外（例：サーバー・ルート）でPlanshipデータを簡単に使用できるように、@planship/nuxtモジュールは#planship/serverエイリアス内で利用可能なuseServerApiClientサーバーサービスを提供します。

以下は、useServerApiClientサーバーサービス関数を介して取得したPlanship APIクライアントを使用して、計測された使用量をPlanship APIに報告するNuxt 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)
})

リンク