API Reference

Complete reference for all Tappd Web SDK methods and APIs.

Core Methods

identify(attributes)

Identify or update a customer using one or more identifiers. Automatically merges anonymous data if user was previously anonymous. The SDK generates an internal identifier automatically.

Parameters:

Parameter	Type	Required	Description
`attributes`	`CustomerAttributes`	Yes	User attributes - must include at least one identifier (`external_id`, `email`, `phone`, or `alias`)

Returns: Promise<void>

Identification Methods:

You can identify a user using any of the following methods (at least one is required):

1. External ID (Recommended)

javascript

await tappd.identify({
  external_id: 'ext_123',  // Your internal user ID from your database/system
  name: 'John Doe',
  email: 'john@example.com',
  phone: '+1234567890',
  // Custom attributes
  age: 28,
  plan: 'premium',
  company: 'Acme Corp'
});

2. Email Only

javascript

await tappd.identify({
  email: 'user@example.com',
  name: 'John Doe',
  // Custom attributes
  plan: 'free'
});

3. Phone Only

javascript

await tappd.identify({
  phone: '+1234567890',
  name: 'John Doe',
  // Custom attributes
  plan: 'free'
});

4. Alias

javascript

await tappd.identify({
  alias: {
    type: 'session_id',  // Custom alias type (e.g., 'session_id', 'legacy_user_id')
    value: '1234'
  },
  name: 'John Doe',
  // Custom attributes
  plan: 'free'
});

5. Multiple Identifiers (Recommended)

javascript

await tappd.identify({
  external_id: 'user_123',  // Primary identifier
  email: 'john@example.com',  // Additional identifier
  phone: '+1234567890',  // Additional identifier
  name: 'John Doe',
  // Custom attributes stored in attributes object
  attributes: {
    plan: 'premium',
    company: 'Acme Corp'
  }
});

Understanding Identifiers:

external_id: Your internal user identifier from your system/database (recommended)
- Used as the primary identifier when provided
- SDK automatically generates an internal userId based on your external_id
- Should be unique and stable (e.g., your database user ID)
email: User's email address
- Automatically normalized (lowercased and trimmed)
- Can be used as the sole identifier
phone: User's phone number
- Can be used as the sole identifier
alias: Custom identifier object with type and value
- Useful for legacy identifiers or custom identification schemes
- Standard alias types: 'email', 'phone', 'user_id', 'external_id'
- Custom types (like 'session_id') are stored as 'custom' type

Lookup Priority:

When identifying, the system tries to find existing customers in this order:

external_id (if provided)
email (if provided)
phone (if provided)
alias (if provided)

How it works:

Identification: Provide at least one identifier - SDK handles the rest
Customer Matching: SDK finds existing customer or creates new one
Event Tracking: All events tracked with track() are automatically associated with this user
Session Linking: All sessions are linked to the user
Data Merging: When you call identify(), any anonymous events tracked before identification are automatically merged to this user
User Lookup: Query and filter data by any identifier in the Tappd dashboard

Best Practices:

Use external_id when available (recommended for best results)
Include multiple identifiers when possible for better matching
Use a stable, unique identifier from your system (e.g., database user ID)
Call identify() after user login/signup to link events to the user
Keep identifiers consistent for a user across sessions and devices
Store custom attributes in the attributes object for better organization

CustomerAttributes Interface:

typescript

interface CustomerAttributes {
  external_id?: string;  // Optional: Your internal user ID
  email?: string;        // Optional: User email address
  phone?: string;        // Optional: User phone number
  alias?: {              // Optional: Custom alias identifier
    type: string;        // Alias type (e.g., 'session_id', 'legacy_user_id')
    value: string;       // Alias value
  };
  name?: string;
  attributes?: {         // Optional: Custom attributes object
    [key: string]: any;
  };
  [key: string]: any;    // Additional custom attributes (flat)
}

Note: At least one identifier (external_id, email, phone, or alias) is required. Custom attributes can be provided either in the attributes object or as top-level properties.

track(eventName, properties?)

Track a custom event with optional properties. Events can be tracked with various identifiers to associate them with customers.

Parameters:

Parameter	Type	Required	Description
`eventName`	`string`	Yes	Name of the event to track
`properties`	`EventProperties`	No	Additional event properties (can include identifiers)

Returns: Promise<void>

Event Tracking with Identifiers:

Events are automatically associated with customers based on identifiers in the properties or from the current session. You can track events using any of these identifiers:

1. Using userId (from identify response)

javascript

// After identifying a user, events are automatically associated
await tappd.identify({
  external_id: 'user_123',
  email: 'john@example.com'
});

// Events are automatically tracked for this user
await tappd.track('purchase', {
  amount: 99.99,
  currency: 'USD',
  productId: 'prod_123'
});

2. Using external_id in properties

javascript

await tappd.track('button_clicked', {
  external_id: 'user_123',  // Associate event with user
  button: 'checkout',
  page: '/cart'
});

3. Using email in properties

javascript

await tappd.track('email_sent', {
  email: 'user@example.com',  // Associate event with user
  template: 'welcome_email',
  subject: 'Welcome to our platform'
});

4. Using phone in properties

javascript

await tappd.track('sms_sent', {
  phone: '+1234567890',  // Associate event with user
  message: 'verification_code',
  carrier: 'att'
});

5. Using alias in properties

javascript

await tappd.track('session_event', {
  alias: {
    type: 'session_id',
    value: '1234'
  },
  event: 'page_view',
  page: '/dashboard'
});

6. Multiple identifiers (for better matching)

javascript

await tappd.track('checkout_started', {
  userId: 'usr_ext123_abc123',  // Primary identifier
  external_id: 'ext_12345',     // Fallback identifier
  email: 'user@example.com',    // Additional identifier
  cartValue: 149.99,
  items: 3
});

Lookup Priority:

When tracking events, the system tries to find the customer in this order:

userId / user_id (if provided)
external_id / externalId (if provided)
email (if provided)
phone (if provided)
alias (if provided)

Basic Example:

javascript

await tappd.track('purchase', {
  amount: 99.99,
  currency: 'USD',
  productId: 'prod_123',
  productName: 'Pro Plan'
});

EventProperties Interface:

typescript

interface EventProperties {
  // Identifiers (optional - at least one recommended for customer association)
  userId?: string;        // Internal user ID from identify response
  user_id?: string;       // Alternative field name
  external_id?: string;   // External user identifier
  externalId?: string;    // Alternative field name (camelCase)
  email?: string;         // User email address
  phone?: string;         // User phone number
  alias?: {               // Custom alias identifier
    type: string;         // Alias type
    value: string;        // Alias value
  };
  sessionId?: string;     // Session ID for linking events
  [key: string]: any;     // Additional event properties
}

Best Practices:

Include at least one identifier when tracking events (for customer association)
Use the same identifier format you used in identify() for consistency
Include sessionId to link events to sessions
If user is already identified, identifiers are optional (events will use the current user)

trackPageView(url?, properties?)

Manually track a page view. Page views are automatically tracked if autoTrack: true.

Parameters:

Parameter	Type	Required	Description
`url`	`string`	No	Page URL (defaults to current URL)
`properties`	`EventProperties`	No	Additional page view properties

Returns: Promise<void>

Example:

javascript

// Track current page
await tappd.trackPageView();

// Track specific URL
await tappd.trackPageView('https://example.com/pricing', {
  referrer: 'google.com'
});

setExternalId(externalId)

Set the external ID for the current user. User must be identified first.

Parameters:

Parameter	Type	Required	Description
`externalId`	`string`	Yes	External user identifier

Returns: Promise<void>

Example:

javascript

await tappd.setExternalId('ext_user_123');

Throws: Error if user is not identified

setUserAttributes(attributes)

Update user attributes for the current user. User must be identified first.

Parameters:

Parameter	Type	Required	Description
`attributes`	`CustomerAttributes`	Yes	Attributes to update

Returns: Promise<void>

Example:

javascript

await tappd.setUserAttributes({
  plan: 'enterprise',
  lastLogin: new Date().toISOString(),
  status: 'active'
});

Throws: Error if user is not identified

setCustomAttributes(attributes)

Set custom user attributes. User must be identified first.

Parameters:

Parameter	Type	Required	Description
`attributes`	`Record<string, any>`	Yes	Custom attributes object

Returns: Promise<void>

Example:

javascript

await tappd.setCustomAttributes({
  preferences: {
    theme: 'dark',
    language: 'en'
  },
  customField: 'value'
});

Throws: Error if user is not identified

Utility Methods

getSessionId()

Get the current session ID.

Returns: string | null

Example:

javascript

const sessionId = tappd.getSessionId();
console.log('Session ID:', sessionId);
// Output: sess_abc123def456

getAnonymousId()

Get the anonymous ID (persists across sessions until user is identified).

Returns: string

Example:

javascript

const anonymousId = tappd.getAnonymousId();
console.log('Anonymous ID:', anonymousId);
// Output: anon_xyz789ghi012

reset()

Reset the SDK state. Clears user data and starts a new session. Useful for logout.

Returns: void

Example:

javascript

// On user logout
function handleLogout() {
  tappd.reset();
  // User is now anonymous again
}

In-App Messages

getInAppMessages()

Fetch pending in-app messages for the current user.

Returns: Promise<InAppMessage[]>

Example:

javascript

const messages = await tappd.getInAppMessages();
messages.forEach(message => {
  console.log(`Message: ${message.config.messageType}`);
  console.log(`Status: ${message.status}`);
});

displayInAppMessage(message)

Display a specific in-app message.

Parameters:

Parameter	Type	Required	Description
`message`	`InAppMessage`	Yes	The message object to display

Returns: Promise<void>

Example:

javascript

const messages = await tappd.getInAppMessages();
if (messages.length > 0) {
  await tappd.displayInAppMessage(messages[0]);
}

displayPendingMessages()

Fetch and display all pending messages that are ready to be shown.

Returns: Promise<void>

Example:

javascript

// Manually trigger message display
await tappd.displayPendingMessages();

dismissMessage(messageId)

Dismiss a message and track the dismissal event.

Parameters:

Parameter	Type	Required	Description
`messageId`	`string`	Yes	The ID of the message to dismiss

Returns: Promise<void>

Example:

javascript

await tappd.dismissMessage('message_id_123');

trackMessageEvent(messageId, eventType, metadata)

Track a custom message interaction event.

Parameters:

Parameter	Type	Required	Description
`messageId`	`string`	Yes	The ID of the message
`eventType`	`string`	Yes	Event type (e.g., 'viewed', 'clicked', 'dismissed')
`metadata`	`object`	No	Additional event metadata

Returns: Promise<void>

Example:

javascript

await tappd.trackMessageEvent('message_id_123', 'clicked', {
  buttonText: 'Get Started',
  buttonLink: '/signup'
});

See also: In-App Messages Guide for detailed documentation.

Push Notifications

getVapidPublicKey()

Get the VAPID public key for web push subscriptions.

Returns: Promise<string> - VAPID public key

Example:

javascript

const publicKey = await tappd.getVapidPublicKey();
console.log('VAPID Public Key:', publicKey);

isSubscribed()

Check if the current user is subscribed to push notifications.

Returns: Promise<boolean> - true if subscribed, false otherwise

Example:

javascript

const isSubscribed = await tappd.isSubscribed();
if (isSubscribed) {
  console.log('User is subscribed to push notifications');
} else {
  console.log('User is not subscribed');
}

subscribeToPush(options?)

Subscribe the current user to push notifications. User must be identified first.

Parameters:

Parameter	Type	Required	Description
`options`	`PushSubscriptionOptions`	No	Optional subscription options

Returns: Promise<PushSubscription> - Push subscription object

Throws: Error if:

Push notifications are not supported
Notification permission is denied
User is not identified

Example:

javascript

// Identify user first (required)
await tappd.identify({
  external_id: 'user_123',
  email: 'john@example.com'
});

// Subscribe to push notifications
try {
  const subscription = await tappd.subscribeToPush();
  console.log('Successfully subscribed:', subscription.endpoint);
} catch (error) {
  console.error('Subscription failed:', error);
}

unsubscribeFromPush()

Unsubscribe the current user from push notifications.

Returns: Promise<void>

Example:

javascript

try {
  await tappd.unsubscribeFromPush();
  console.log('Successfully unsubscribed from push notifications');
} catch (error) {
  console.error('Unsubscribe failed:', error);
}

showPermissionPrompt(type)

Show a permission prompt to the user. Supported types: 'slidedown', 'bell', or 'native'.

Parameters:

Parameter	Type	Required	Description
`type`	`'slidedown' \| 'bell' \| 'native'`	Yes	Type of permission prompt

Returns: Promise<void>

Example:

javascript

// Show native browser prompt
await tappd.showPermissionPrompt('native');

// Show slidedown prompt
await tappd.showPermissionPrompt('slidedown');

// Show bell icon prompt
await tappd.showPermissionPrompt('bell');

Note: After showing the prompt, you should call subscribeToPush() when the user grants permission.

hidePermissionPrompt()

Hide any active permission prompt.

Returns: Promise<void>

Example:

javascript

// Hide active prompt
await tappd.hidePermissionPrompt();

Types

TappdConfig

SDK configuration interface.

typescript

interface TappdConfig {
  appId: string;                    // Required
  apiUrl?: string;                  // Optional
  autoTrack?: boolean;              // Optional, default: true
  sessionTimeout?: number;          // Optional, default: 30
  enableAutoCapture?: boolean;      // Optional, default: false
  debug?: boolean;                  // Optional, default: false
  enableInAppMessages?: boolean;    // Optional, default: true
  autoDisplayMessages?: boolean;    // Optional, default: true
  messagePollingInterval?: number;  // Optional, default: 30 (seconds)
  messageContainerId?: string;      // Optional: Custom DOM container ID
}

CustomerAttributes

User attributes interface.

typescript

interface CustomerAttributes {
  external_id?: string;  // Optional: Your internal user ID
  email?: string;        // Optional: User email address
  phone?: string;        // Optional: User phone number
  alias?: {              // Optional: Custom alias identifier
    type: string;        // Alias type (e.g., 'session_id', 'legacy_user_id')
    value: string;       // Alias value
  };
  name?: string;
  attributes?: {         // Optional: Custom attributes object
    [key: string]: any;
  };
  [key: string]: any;    // Additional custom attributes (flat)
}

Note: At least one identifier (external_id, email, phone, or alias) is required. Custom attributes can be provided either in the attributes object or as top-level properties.

EventProperties

Event properties interface.

typescript

interface EventProperties {
  [key: string]: any; // Any properties
}

Error Handling

All async methods return promises and can throw errors. Always use try-catch:

javascript

try {
  await tappd.identify({
    external_id: 'user_123',
    email: 'john@example.com'
  });
} catch (error) {
  console.error('Identification failed:', error);
}

try {
  await tappd.track('purchase', { amount: 99.99 });
} catch (error) {
  console.error('Tracking failed:', error);
}

Common errors:

Network errors: API request failed
Invalid App ID: App ID not found or invalid
User not identified: Calling methods that require identification before identify() is called

Next Steps

Push Notifications - Complete guide to web push notifications
In-App Messages - Complete guide to in-app messages
Session Management - Learn about session tracking
Examples - See API methods in action
Troubleshooting - Common issues and solutions

API Reference ​

Core Methods ​

identify(attributes) ​

1. External ID (Recommended) ​

2. Email Only ​

3. Phone Only ​

4. Alias ​

5. Multiple Identifiers (Recommended) ​

track(eventName, properties?) ​

1. Using userId (from identify response) ​

2. Using external_id in properties ​

3. Using email in properties ​

4. Using phone in properties ​

5. Using alias in properties ​

6. Multiple identifiers (for better matching) ​

trackPageView(url?, properties?) ​

setExternalId(externalId) ​

setUserAttributes(attributes) ​

setCustomAttributes(attributes) ​

Utility Methods ​

getSessionId() ​

getAnonymousId() ​

reset() ​

In-App Messages ​

getInAppMessages() ​

displayInAppMessage(message) ​

displayPendingMessages() ​

dismissMessage(messageId) ​

trackMessageEvent(messageId, eventType, metadata) ​

Push Notifications ​

getVapidPublicKey() ​

isSubscribed() ​

subscribeToPush(options?) ​

unsubscribeFromPush() ​

showPermissionPrompt(type) ​

hidePermissionPrompt() ​

Types ​

TappdConfig ​

CustomerAttributes ​

EventProperties ​

Error Handling ​

Next Steps ​

API Reference

Core Methods

identify(attributes)

1. External ID (Recommended)

2. Email Only

3. Phone Only

4. Alias

5. Multiple Identifiers (Recommended)

track(eventName, properties?)

1. Using userId (from identify response)

2. Using external_id in properties

3. Using email in properties

4. Using phone in properties

5. Using alias in properties

6. Multiple identifiers (for better matching)

trackPageView(url?, properties?)

setExternalId(externalId)

setUserAttributes(attributes)

setCustomAttributes(attributes)

Utility Methods

getSessionId()

getAnonymousId()

reset()

In-App Messages

getInAppMessages()

displayInAppMessage(message)

displayPendingMessages()

dismissMessage(messageId)

trackMessageEvent(messageId, eventType, metadata)

Push Notifications

getVapidPublicKey()

isSubscribed()

subscribeToPush(options?)

unsubscribeFromPush()

showPermissionPrompt(type)

hidePermissionPrompt()

Types

TappdConfig

CustomerAttributes

EventProperties

Error Handling

Next Steps