PinpointClient Usage Guide

A general TypeScript class for AWS Amplify Pinpoint configuration using AWS Amplify v6.

Features

• 🎯 Singleton Pattern: Ensures a single instance across your application
• 🔒 Type-Safe: Full TypeScript support with proper type definitions
• 🔌 Proxy Access: Direct access to all AWS Amplify methods through the client instance
• 📊 Auto-enrichment: Automatically adds common browser attributes to events
• 🎨 Simple API: Clean, intuitive methods for common Pinpoint operations

Installation

npm install @luminpdf/browser-pinpoint
# or
yarn add @luminpdf/browser-pinpoint
# or
pnpm add @luminpdf/browser-pinpoint

Basic Usage

import { PinpointClient } from "@luminpdf/browser-pinpoint";

// Use the static factory method to get the singleton instance
// All AWS Amplify members are exposed through the proxied instance
const pinpointClient = PinpointClient.create({
  region: "us-east-1",
  identityPoolId: process.env.IDENTITY_POOL_ID,
  pinpointAppId: process.env.PINPOINT_APP_ID,
  disableInDevelopment: true,
  allowGuestAccess: true,
});

// Configure page view tracking
pinpointClient.configurePageViewTracking({
  enable: true,
  eventName: "pageView",
  attributes: () => {
    // Your custom attributes (can be sync or async)
    return {
      page: globalThis.location.pathname,
      // ... other attributes
    };
  },
  onAttributesGenerated: (attributes) => {
    // Optional: Integrate with other services (e.g., Braze)
    // braze.logCustomEvent('pageView', attributes);
  },
});

// Configure session tracking
pinpointClient.configureSessionTracking({
  enable: true,
});

// Configure event tracking
pinpointClient.configureEventTracking({
  enable: true,
});

// Access all aws-amplify members directly from the client instance
// All members from 'aws-amplify' and 'aws-amplify/analytics' are exposed
pinpointClient.Amplify.configure(/* ... */);
pinpointClient.configureAutoTrack(/* ... */);
pinpointClient.record(/* ... */);
// Any other AWS Amplify method is also available

Note: Calling PinpointClient.create() multiple times will always return the same singleton instance, ensuring consistent configuration across your application.

Advanced Usage

Recording Custom Events

// Record a custom event
await pinpointClient.recordEvent("buttonClicked", {
  buttonId: "submit-button",
  page: "/checkout",
});

Resetting the Instance (Testing Only)

For testing purposes, you can reset the singleton instance:

// Reset the singleton (typically only used in tests)
PinpointClient.resetInstance();

// Now you can create a new instance with different config
const newClient = PinpointClient.create({
  /* different config */
});

API Reference

Static Methods

PinpointClient.create(config: PinpointClientConfig): PinpointClientType

Returns the singleton instance of PinpointClient wrapped in a Proxy that exposes all AWS Amplify members. Subsequent calls return the same instance.

PinpointClient.resetInstance(): void

Resets the singleton instance. Useful for testing purposes only.

Instance Methods

configurePageViewTracking(config?: PageViewTrackingConfig): void

Configures automatic page view tracking.

configureSessionTracking(config?: SessionTrackingConfig): void

Configures automatic session tracking.

configureEventTracking(config?: EventTrackingConfig): void

Configures automatic event tracking.

recordEvent(eventName: string, attributes?: Record<string, string>): Promise<void>

Records a custom event with optional attributes. Automatically includes common attributes.

getConfig(): Readonly<Required<PinpointClientConfig>>

Returns the current configuration.

isClientConfigured(): boolean

Returns whether the client has been configured.

Configuration Options

PinpointClientConfig

| Option | Type | Default | Description | | ---------------------- | --------- | ------------- | -------------------------------- | | region | string | 'us-east-1' | AWS Region | | identityPoolId | string | '' | Cognito Identity Pool ID | | pinpointAppId | string | '' | Pinpoint App ID | | disableInDevelopment | boolean | true | Disable analytics in development | | allowGuestAccess | boolean | true | Allow guest access |

PageViewTrackingConfig

| Option | Type | Default | Description | | ----------------------- | ---------- | ------------ | ----------------------------------------------------- | | enable | boolean | true | Enable/disable tracking | | eventName | string | 'pageView' | Custom event name | | attributes | function | undefined | Function to get attributes (can return sync or async) | | getUrl | function | default | Function to get current URL | | immediate | boolean | true | Track immediately on load | | onAttributesGenerated | function | undefined | Callback for integrations (e.g., Braze) |

Exposed AWS Amplify Members

When using PinpointClient.create(), the returned instance is a Proxy that exposes all members from both aws-amplify and aws-amplify/analytics namespaces, in addition to the PinpointClient methods.

This means you can access any AWS Amplify method directly from the client instance:

const client = PinpointClient.create({
  /* ... */
});

// PinpointClient methods
client.configurePageViewTracking({
  /* ... */
});
client.recordEvent("eventName", {
  /* ... */
});

// All AWS Amplify members are also available
client.Amplify.configure(/* ... */);
client.configureAutoTrack(/* ... */);
client.record(/* ... */);
// Any other method from aws-amplify or aws-amplify/analytics

The Proxy pattern ensures that:

• PinpointClient methods take precedence
• All AWS Amplify members are accessible
• Function bindings are preserved correctly
• Singleton pattern maintains a single instance across the application

Migration Examples

From bananasign-web/pinpoint.js

// Before
import { Amplify } from "aws-amplify";
import { configureAutoTrack } from "aws-amplify/analytics";

const amplifyConfig = {
  Auth: {
    Cognito: {
      identityPoolId: process.env.IDENTITY_POOL_ID,
      allowGuestAccess: true,
    },
  },
  Analytics: {
    disabled: process.env.NODE_ENV === "development",
    Pinpoint: {
      appId: process.env.PINPOINT_APP_ID,
      region: "us-east-1",
      mandatorySignIn: false,
    },
  },
};

Amplify.configure(amplifyConfig);
configureAutoTrack({
  type: "pageView",
  eventName: "pageView",
  attributes: () => getPageViewAttributes(),
  getUrl: () => window.location.origin + window.location.pathname,
  immediate: true,
});

// After
import { PinpointClient } from "@luminpdf/browser-pinpoint";

const client = PinpointClient.create({
  region: "us-east-1",
  identityPoolId: process.env.IDENTITY_POOL_ID,
  pinpointAppId: process.env.PINPOINT_APP_ID,
  disableInDevelopment: process.env.NODE_ENV === "development",
  allowGuestAccess: true,
});
client.configurePageViewTracking({
  enable: true,
  eventName: "pageView",
  attributes: () => getPageViewAttributes(),
  immediate: true,
});

License

MIT