API Reference

Complete reference for all Tappd Mobile 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

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',
  screen: 'CartScreen'
});

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: 'screen_view',
  screen: 'DashboardScreen'
});

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)

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

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) ​

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) ​

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)

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)

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