Examples

Real-world examples of using the Tappd Web SDK.

E-commerce

Product Purchase Flow

import { TappdSDK } from '@tappd/web-sdk';

const tappd = new TappdSDK({ appId: 'YOUR_APP_ID' });

// 1. User views product
await tappd.track('ecommerce.product_viewed', {
  productId: 'prod_123',
  productName: 'iPhone 15',
  category: 'Electronics',
  price: 999.00,
  currency: 'USD'
});

// 2. User adds to cart
await tappd.track('ecommerce.add_to_cart', {
  productId: 'prod_123',
  productName: 'iPhone 15',
  quantity: 1,
  price: 999.00,
  currency: 'USD'
});

// 3. User starts checkout
await tappd.track('ecommerce.checkout_started', {
  cartValue: 999.00,
  currency: 'USD'
});

// 4. User completes purchase
await tappd.track('ecommerce.purchase', {
  orderId: 'ord_456',
  total: 999.00,
  currency: 'USD',
  items: [{
    productId: 'prod_123',
    name: 'iPhone 15',
    price: 999.00,
    quantity: 1
  }]
});

Cart Abandonment

// Track when user abandons cart
async function trackCartAbandonment(cartItems) {
  await tappd.track('ecommerce.cart_abandoned', {
    cartValue: calculateTotal(cartItems),
    itemCount: cartItems.length,
    items: cartItems,
    currency: 'USD'
  });
}

User Authentication

Sign Up Flow

async function handleSignUp(email, name) {
  // Track signup attempt
  await tappd.track('user.signup.started', {
    method: 'email'
  });

  try {
    // Create user account
    const user = await createAccount(email, name);
    
    // Identify user (merges anonymous data)
    await tappd.identify({
      external_id: user.id,  // Your internal user ID
      email: email,
      name: name,
      signupDate: new Date().toISOString()
    });

    // Track successful signup
    await tappd.track('user.signup.completed', {
      method: 'email'
      // Note: userId not needed - SDK automatically associates event with identified user
    });
  } catch (error) {
    // Track signup failure
    await tappd.track('user.signup.failed', {
      method: 'email',
      error: error.message
    });
  }
}

Login Flow

async function handleLogin(email) {
  // Track login attempt
  await tappd.track('user.login.started', {
    method: 'email'
  });

  try {
    const user = await authenticate(email);
    
    // Identify user
    await tappd.identify({
      external_id: user.id,  // Your internal user ID
      email: user.email,
      name: user.name,
      lastLogin: new Date().toISOString()
    });

    // Track successful login
    await tappd.track('user.login.completed', {
      method: 'email'
      // Note: userId not needed - SDK automatically associates event with identified user
    });
  } catch (error) {
    // Track login failure
    await tappd.track('user.login.failed', {
      method: 'email',
      error: error.message
    });
  }
}

Logout

function handleLogout() {
  // Track logout
  tappd.track('user.logout');
  
  // Reset SDK (clears user data)
  tappd.reset();
}

Form Tracking

Multi-Step Form

// Step 1: User views form
await tappd.track('form.viewed', {
  formId: 'checkout-form',
  formName: 'Checkout'
});

// Step 2: User starts filling
await tappd.track('form.started', {
  formId: 'checkout-form',
  formName: 'Checkout'
});

// Step 3: User completes step
await tappd.track('form.step_completed', {
  formId: 'checkout-form',
  formName: 'Checkout',
  step: 'shipping',
  stepNumber: 1
});

// Step 4: User submits form
await tappd.track('form.submitted', {
  formId: 'checkout-form',
  formName: 'Checkout',
  success: true,
  fieldsCompleted: 5
});

Subscription Management

Subscription Upgrade

async function handleUpgrade(newPlan, userId) {
  const currentPlan = getUserPlan();
  
  await tappd.track('subscription.upgrade', {
    fromPlan: currentPlan,
    toPlan: newPlan,
    upgradeDate: new Date().toISOString()
  });

  // Update user attributes (requires external_id)
  // Note: external_id must match the one used in identify()
  await tappd.setUserAttributes({
    external_id: userId,  // Required: Must match the external_id from identify()
    plan: newPlan,
    upgradedAt: new Date().toISOString()
  });
}

Subscription Cancellation

async function handleCancellation(reason, userId) {
  await tappd.track('subscription.cancelled', {
    reason: reason,
    cancelledAt: new Date().toISOString()
  });

  await tappd.setUserAttributes({
    external_id: userId,  // Required: Must match the external_id from identify()
    planStatus: 'cancelled',
    cancellationDate: new Date().toISOString()
  });
}

React Integration

React Hook

import { useEffect, useState } from 'react';
import { TappdSDK } from '@tappd/web-sdk';

function useTappd() {
  const [tappd] = useState(() => {
    return new TappdSDK({
      appId: process.env.REACT_APP_TAPPD_APP_ID
    });
  });

  return tappd;
}

// Usage
function ProductPage({ productId }) {
  const tappd = useTappd();

  useEffect(() => {
    tappd.track('product_viewed', { productId });
  }, [productId]);

  const handleAddToCart = async () => {
    await tappd.track('add_to_cart', { productId });
  };

  return <button onClick={handleAddToCart}>Add to Cart</button>;
}

React Context

import React, { createContext, useContext } from 'react';
import { TappdSDK } from '@tappd/web-sdk';

const TappdContext = createContext(null);

export function TappdProvider({ children }) {
  const tappd = new TappdSDK({
    appId: process.env.REACT_APP_TAPPD_APP_ID
  });

  return (
    <TappdContext.Provider value={tappd}>
      {children}
    </TappdContext.Provider>
  );
}

export function useTappd() {
  return useContext(TappdContext);
}

Vue.js Integration

Vue Composable

import { ref, onMounted } from 'vue';
import { TappdSDK } from '@tappd/web-sdk';

export function useTappd() {
  const tappd = ref(null);

  onMounted(() => {
    tappd.value = new TappdSDK({
      appId: import.meta.env.VITE_TAPPD_APP_ID
    });
  });

  return tappd;
}

// Usage
<script setup>
import { useTappd } from '@/composables/useTappd';

const tappd = useTappd();

const handleClick = async () => {
  await tappd.value?.track('button_click', { buttonId: 'cta' });
};
</script>

Next.js Integration

App Router

// app/layout.tsx
'use client';

import { useEffect } from 'react';
import { TappdSDK } from '@tappd/web-sdk';

export default function RootLayout({ children }) {
  useEffect(() => {
    const tappd = new TappdSDK({
      appId: process.env.NEXT_PUBLIC_TAPPD_APP_ID
    });

    window.tappd = tappd;

    return () => {
      tappd.reset();
    };
  }, []);

  return <html>{children}</html>;
}

Pages Router

// pages/_app.js
import { useEffect } from 'react';
import { TappdSDK } from '@tappd/web-sdk';

function MyApp({ Component, pageProps }) {
  useEffect(() => {
    const tappd = new TappdSDK({
      appId: process.env.NEXT_PUBLIC_TAPPD_APP_ID
    });

    window.tappd = tappd;
  }, []);

  return <Component {...pageProps} />;
}

export default MyApp;

Error Tracking

Track Errors

window.addEventListener('error', (event) => {
  tappd.track('error', {
    message: event.message,
    filename: event.filename,
    lineno: event.lineno,
    colno: event.colno,
    error: event.error?.stack
  });
});

window.addEventListener('unhandledrejection', (event) => {
  tappd.track('error.unhandled_promise_rejection', {
    reason: event.reason,
    error: event.reason?.stack
  });
});

A/B Testing

Track Experiment Variants

const variant = getExperimentVariant('homepage-cta');

await tappd.track('experiment.viewed', {
  experimentId: 'homepage-cta',
  variant: variant
  // Note: userId not needed - SDK automatically associates event with identified user
});

// Track conversion
await tappd.track('experiment.converted', {
  experimentId: 'homepage-cta',
  variant: variant,
  conversionType: 'signup'
});

Video Tracking

Track Video Engagement

const video = document.querySelector('video');

video.addEventListener('play', () => {
  tappd.track('video.played', {
    videoId: 'intro-video',
    videoTitle: 'Product Introduction'
  });
});

video.addEventListener('pause', () => {
  tappd.track('video.paused', {
    videoId: 'intro-video',
    currentTime: video.currentTime,
    duration: video.duration
  });
});

video.addEventListener('ended', () => {
  tappd.track('video.completed', {
    videoId: 'intro-video',
    duration: video.duration
  });
});

Next Steps

• API Reference - Complete method documentation
• Configuration - Customize SDK behavior
• Troubleshooting - Common issues and solutions