Admiral SDK for NodeJS

Provides a simple interface for using Admiral's APIs for applications written in server-side JavaScript. Visit us at Admiral for more information.

Requirements

Node.js 16 or later (see engines in package.json).

Installation

Install the package to your project:

npm install @admiral-vrm/sdk-node
# or
yarn add @admiral-vrm/sdk-node

Configuration

• propertyID (required): Your Admiral property ID (e.g. "A-1234-1").
• tokenSecretKey (recommended when using Proxy): Secret used to sign visitor tokens. Set a strong, unique value in production; otherwise a default is used (not suitable for production). Can also be set via ADMIRAL_TOKEN_SECRET_KEY.
• proxy: Optional. When using proxyAdmiral: true, set proxy.host (and optionally scheme, prefix).
• protectOptions: Optional. For Protect/Partner API: partnerApiEndpoint, cacheTimeout. API credentials are configured inside the Protect integration (see examples).

Documentation

Admiral

The Admiral class is the main class for the Admiral SDK. It contains configuration for the Admiral object, such as the property ID, environment, enabling Protect and Proxy, and additional parameters.

export const admiral = new Admiral({
  propertyID: "A-1234-1",
  environment: "production",
  protect: true,
  proxyAdmiral: true,
  tokenSecretKey: process.env.ADMIRAL_TOKEN_SECRET_KEY, // recommended for production
  proxy: {
    host: "host.com",
    scheme: "https",
  },
});

The class provides the following methods:

getPossibleHandlers(): string[]

Returns an array of possible Admiral prefix handlers that can be used as prefixes when using the proxy functionality.

fetchSSRBootstraps(): Promise

Fetches Admiral bootstrap scripts for server-side rendering. Returns a promise containing:

• admiral: Array of bootstrap script strings, each of these should be script tags

fetchBootstraps(): Promise<string[]>

Fetches Admiral bootstrap scripts. Returns a promise containing an array of script strings.

renderSSRBootstraps(payload: AdmiralSSRBootstrapWrapper, format: "html" | "react" = "react"): React.ReactNode[]

Renders the Admiral bootstrap scripts for server-side rendering as React components. Takes a bootstrap wrapper payload from fetchSSRBootstraps and returns an array of React script elements.

Parameters:

• payload: Object containing array of bootstrap scripts under admiral key

handleRequestAsMiddleware(req: MiddlewareRequest): Promise

Handles Admiral middleware functionality including proxy requests and Protect functionality. Returns a promise containing the middleware response with:

• response: Response object (optional)
• headers: Headers object (optional)
• cookies: ResponseCookies object (optional)

Parameters:

• req: MiddlewareRequest object containing the incoming request details

Usage with Next.js and React

See the Next.js example for more information with a full example and documentation on how to use the Admiral SDK with Next.js.

The ProtectEmbed component is a React component that can be used to embed the Protect functionality into a React application.

Usage with Express.js / Node.js

See the Express.js example for more information with a full example and documentation on how to use the Admiral SDK with Express.

The ProtectHTMLEmbed library allows embedding HTML with Protect functionality into your application without using React.