メインコンテンツまでスキップ

SDKのバックエンド

createSDKInstanceのbackendは、SDKが各APIの処理を委譲する先です。 通常のミニアプリでは指定する必要はなく、省略するとポケットサインアプリと通信する実機バックエンドが使われます。

実機バックエンド​

backendを省略したときに使われる既定のバックエンド（AppBackend）です。 ポケットサインアプリのミニアプリブラウザ内で動作し、SDKのすべての機能が利用できます。

import { createSDKInstance } from '@pocketsign/in-app-sdk'

const serviceId = '<YOUR_SERVICE_ID>'

const sdk = await createSDKInstance({ serviceId })

ポケットサインアプリ外で呼び出した場合は、APP_BACKEND_NOT_INSIDE_APPエラーでPromiseがrejectされます。

ヒント

実機バックエンドをモック環境で使用するには、開発版アプリが必要です。

モックバックエンド​

開発・テスト用のバックエンドです。 @pocketsign/in-app-sdk/mockが提供するcreateMockBackendをbackendに渡すと、ポケットサインアプリなしでSDKを動作させられます。 パソコンのブラウザでの開発や、Vitest / Jest でのユニットテスト、Playwright でのE2Eテストに利用してください。

モックバックエンドはポケットサインアプリやポケットサインのサーバーと通信しません。 既定では各APIが成功時のダミー値を返すため、実際のリソース値が必要な場合は明示的に上書きしてください。

import { createSDKInstance, readResourceRaw, MergedSourceResources } from '@pocketsign/in-app-sdk'
import { createMockBackend } from '@pocketsign/in-app-sdk/mock'

const serviceId = '<YOUR_SERVICE_ID>'

const mock = createMockBackend({
  responses: {
    // キーはSDKの関数名ではなくパケット種別です（readResourceRaw の場合は readResource）
    readResource: { result: 'success', value: JSON.stringify('山田 太郎') }
  }
})

const sdk = await createSDKInstance({ serviceId, backend: mock })

await readResourceRaw(sdk, { resourceId: MergedSourceResources.fullName })
// → { result: 'success', value: '"山田 太郎"' }

レスポンスは、Vitest / Jest 互換のAPIで後から差し替えたり、呼び出しを検証したりできます。 以下はVitestを使う場合の例です。

import { expect } from 'vitest'

mock.readResource.mockResolvedValueOnce({ result: 'success', value: null })
expect(mock.requestPermissionV1).toHaveBeenCalledTimes(1)
mock.reset() // 上書きした実装と呼び出し履歴を初期化
注意

モックのコードが本番のバンドルに含まれないように、動的インポートで読み込むことを推奨します。 以下は、Viteのimport.meta.envを利用した例です。

import { createSDKInstance } from '@pocketsign/in-app-sdk'

const serviceId = '<YOUR_SERVICE_ID>'

const backend =
  import.meta.env.VITE_BACKEND === 'mock'
    ? await import('@pocketsign/in-app-sdk/mock').then((m) => m.createMockBackend())
    : undefined

const sdk = await createSDKInstance({ serviceId, backend })

WebpackではDefinePluginが利用できます。

一部のAPIだけモックする​

実機バックエンドを活かしたまま特定のAPIだけ差し替える場合は、installMockを利用します。 モックしていないAPIは実機バックエンドにそのまま流れます。

import { createSDKInstance } from '@pocketsign/in-app-sdk'
import { installMock } from '@pocketsign/in-app-sdk/mock'

const serviceId = '<YOUR_SERVICE_ID>'

const sdk = await createSDKInstance({ serviceId })
const mock = installMock(sdk)
mock.requestLocalAuthentication.mockResolvedValue({ result: 'rejected' })

// テスト終了時に必ず元へ戻す
mock.restore()

同じSDKインスタンスに対してinstallMockを二回呼び出すとエラーになります。 また、createMockBackendとinstallMockは同時に利用できません。

1.x からの変更点​

In-App SDK 1.x のcreateAppBackendとcreateApiBackendは、2.0.0 で削除されました。

1.x2.x
backend: createAppBackend()backendを省略する
backend: createApiBackend({ accessToken })相当する機能はありません

APIバックエンドを利用した「パソコンのブラウザでデバッグユーザーのリソースを読み取る」開発方法は、2.x では利用できません。 パソコンのブラウザで動作確認する場合はモックバックエンドを、実際のユーザーのリソースで確認する場合は開発版アプリを利用してください。