API Reference

Complete reference for all Tappd Mobile SDK methods and APIs.

Core Methods

identify(attributes)

Identify or update a customer using your internal user ID. 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 `external_id`

Returns: Promise<void>

Example:

javascript

await tappd.identify({
  external_id: 'ext_123',  // Required: 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'
});

Understanding external_id:

external_id ('ext_123'):
- Required - Your internal user identifier from your own system/database
- Used as the primary way to identify users (no need to pass userId)
- SDK automatically generates an internal userId based on your external_id
- Used to link all events, sessions, and data to this user
- Should be unique and stable (e.g., your database user ID)
- All future track() calls will be associated with this user

Simplified API:

The SDK now simplifies identification - you only need to provide your external_id:

javascript

// ✅ Simple - just pass your internal user ID
await tappd.identify({
  external_id: 'user_123',  // Your database user ID
  email: 'john@example.com',
  name: 'John Doe'
});

// SDK automatically:
// 1. Generates internal userId
// 2. Creates/finds customer by external_id
// 3. Links all events to this user

What happens if external_id is not provided?

If identify() is never called:
- User remains anonymous
- All events are tracked with an anonymousId (automatically generated)
- Events can be merged later when identify() is called with external_id
If identify() is called without external_id:
- SDK throws an error: "external_id is required in attributes"
- Event is not processed

How it works:

Identification: Pass your external_id - SDK handles the rest
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 external_id in the Tappd dashboard

Best Practices:

Always include external_id in your identify() call (it's required)
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 the same external_id for a user across sessions and devices

track(eventName, properties?)

Track a custom event with optional properties.

Parameters:

Parameter	Type	Required	Description
`eventName`	`string`	Yes	Name of the event to track
`properties`	`EventProperties`	No	Additional event properties

Returns: Promise<void>

Example:

javascript

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

trackScreen(screenName, properties?)

Track a screen view (equivalent to page view in web).

Parameters:

Parameter	Type	Required	Description
`screenName`	`string`	Yes	Name of the screen
`properties`	`EventProperties`	No	Additional screen properties

Returns: Promise<void>

Example:

javascript

await tappd.trackScreen('HomeScreen', {
  category: 'main',
  section: 'dashboard'
});

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

Push Notification Methods

registerPushToken(token, platform)

Parameters:

Parameter	Type	Required	Description
`token`	`string`	Yes	Push notification token (FCM)
`platform`	`'android' \| 'ios'`	Yes	Device platform

Returns: Promise<void>

Example:

javascript

import messaging from '@react-native-firebase/messaging';
import { Platform } from 'react-native';

const token = await messaging().getToken();
await tappd.registerPushToken(token, Platform.OS === 'ios' ? 'ios' : 'android');

Throws: Error if user is not identified

checkPushSubscription()

Check the push subscription status for the current user.

Returns: Promise<{ subscribed: boolean; status: string; deviceCount: number }>

Example:

javascript

const status = await tappd.checkPushSubscription();
console.log('Subscribed:', status.subscribed);
console.log('Status:', status.status); // 'subscribed', 'opted_in', or 'unsubscribed'
console.log('Device Count:', status.deviceCount);

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 | null

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
}

cleanup()

Cleanup SDK. Call when app is closing to send final events and remove listeners.

Returns: void

Example:

javascript

import { AppState } from 'react-native';

AppState.addEventListener('change', (nextAppState) => {
  if (nextAppState === 'background') {
    tappd.cleanup();
  }
});

In-App Messages

setMessageRenderCallback(callback)

Set a callback function that will be called when a message should be displayed. This is required for React Native apps to render messages.

Parameters:

Parameter	Type	Required	Description
`callback`	`(message: InAppMessage) => void`	Yes	Function called with the message to display

Returns: void

Example:

javascript

import { MessageRenderer } from '@tappd/mobile-sdk/src/renderers/MessageRenderer';

const [currentMessage, setCurrentMessage] = useState(null);

tappd.setMessageRenderCallback((message) => {
  setCurrentMessage(message);
});

// In your render:
{currentMessage && (
  <MessageRenderer
    message={currentMessage}
    onDismiss={(id) => {
      tappd.dismissMessage(id);
      setCurrentMessage(null);
    }}
  />
)}

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. This will call the render callback if set.

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.

Types

TappdConfig

SDK configuration interface.

typescript

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

CustomerAttributes

User attributes interface.

typescript

interface CustomerAttributes {
  name?: string;
  email?: string;
  phone?: string;
  external_id?: string;
  [key: string]: any; // Any custom attributes
}

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

In-App Messages - Complete guide to in-app messages
Push Notifications - Set up push notifications
React Navigation - Screen tracking with React Navigation
Examples - See API methods in action
Troubleshooting - Common issues and solutions

API Reference ​

Core Methods ​

identify(attributes) ​

track(eventName, properties?) ​

trackScreen(screenName, properties?) ​

setExternalId(externalId) ​

setUserAttributes(attributes) ​

setCustomAttributes(attributes) ​

Push Notification Methods ​

registerPushToken(token, platform) ​

checkPushSubscription() ​

Utility Methods ​

getSessionId() ​

getAnonymousId() ​

reset() ​

cleanup() ​

In-App Messages ​

setMessageRenderCallback(callback) ​

getInAppMessages() ​

displayInAppMessage(message) ​

displayPendingMessages() ​

dismissMessage(messageId) ​

trackMessageEvent(messageId, eventType, metadata) ​

Types ​

TappdConfig ​

CustomerAttributes ​

EventProperties ​

Error Handling ​

Next Steps ​

API Reference

Core Methods

identify(attributes)

track(eventName, properties?)

trackScreen(screenName, properties?)

setExternalId(externalId)

setUserAttributes(attributes)

setCustomAttributes(attributes)

Push Notification Methods

registerPushToken(token, platform)

checkPushSubscription()

Utility Methods

getSessionId()

getAnonymousId()

reset()

cleanup()

In-App Messages

setMessageRenderCallback(callback)

getInAppMessages()

displayInAppMessage(message)

displayPendingMessages()

dismissMessage(messageId)

trackMessageEvent(messageId, eventType, metadata)

Types

TappdConfig

CustomerAttributes

EventProperties

Error Handling

Next Steps