@amplifyup/sdk

AmplifyUp Tracking SDK - CDP-agnostic event tracking library.

Overview

This SDK provides event tracking that sends events directly to AWS API Gateway. All URLs are hardcoded in the SDK - no configuration needed except trackingId.

Installation

npm install @amplifyup/sdk

Usage

Basic Setup

import { init } from '@amplifyup/sdk';

// Initialize the SDK (URLs are hardcoded)
await init({
  trackingId: 'your-tracking-id',
  debug: true, // Optional, enables debug logging
});

Track Events

import { 
  page, 
  track, 
  trackClick, 
  trackFormSubmit,
  trackContentView,
  identify 
} from '@amplifyup/sdk';

// Track page view
page('/home');

// Track custom event
track('Product Viewed', {
  productId: '123',
  productName: 'Widget',
  price: 29.99
});

// Track button click
trackClick('add-to-cart', 'Add to Cart', {
  productId: '123'
});

// Track form submission
trackFormSubmit('newsletter-signup', {
  email: '[email protected]'
});

// Track content view
trackContentView('product-123', 'product', {
  productName: 'Widget',
  category: 'Electronics'
});

// Identify user
identify('user-123', {
  email: '[email protected]',
  name: 'John Doe'
});

Get Instance ID

import { getInstanceId } from '@amplifyup/sdk';

const instanceId = getInstanceId();

Architecture

The SDK sends events directly to AWS API Gateway:

• Events are sent to /v1/track or /v1/page endpoints
• All URLs are hardcoded in the SDK
• No write keys or configuration needed
• Personalization requests go to AWS Decision API Gateway

Development

# Build
npm run build

# Watch mode
npm run dev

# Lint
npm run lint

Publishing (maintainers)

CI publishes via npm Trusted Publishing (GitHub ↔ npm, no long-lived token).

One-time setup on npm:

1. If the package has never been published: Publish once with a token so the package exists: add NPM_TOKEN (Automation token) in repo Secrets, run the workflow, then remove the token and continue below.
2. On npmjs.com: sign in → Packages → @amplifyup/sdk → Settings → Trusted publishing.
3. Under “Select your publisher” choose GitHub Actions and set:
   • Workflow filename: publish-sdk.yml (must match exactly)
   • Repository/owner as prompted.
4. Save. Future runs publish with no NPM_TOKEN secret.

Requires Node 22.14+ and npm 11.5.1+ (workflow uses Node 22).

License

MIT