Tappd SDK Documentation

Appearance

Banners ​

The Tappd Web SDK supports displaying banners created in your Tappd dashboard. Banners are placement-based content that can be attached to specific DOM elements using CSS selectors or data attributes, with support for targeting, scheduling, frequency capping, and A/B testing.

Overview ​

Banners are different from in-app messages:

  • Placement-based: Banners are attached to specific DOM elements (CSS selectors or data attributes)
  • Targeting: Support for customer segments, rules, and targeting conditions
  • Scheduling: Start/end dates, active hours, and timezone support
  • Frequency Capping: Control how often banners are shown to users
  • A/B Testing: Multiple variants with traffic allocation
  • Analytics: Track displays, clicks, dismissals, and conversions

Quick Start ​

The SDK handles all API calls, rendering, and event tracking automatically:

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

const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  apiUrl: 'https://sdk.gotappd.com/api/v1/sdk'
});

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

// SDK handles everything - fetch, render, and track
await tappd.getBanners('#header-banner');

That's it! The SDK will:

  1. Fetch eligible banners from the API
  2. Render them in the specified DOM element
  3. Automatically track display, click, and dismiss events

Banners use a placement system to attach to specific DOM elements. There are three placement types:

1. CSS Selector Placement ​

Banners can be placed using CSS selectors:

html
<!-- Your HTML -->
<header id="header-banner">
  <!-- Banner will be injected here automatically -->
</header>
javascript
// SDK automatically finds and renders in #header-banner
await tappd.getBanners('#header-banner');

2. Data Attribute Placement ​

Banners can be placed using data attributes:

html
<!-- Your HTML -->
<div data-tappd-banner="promo">
  <!-- Banner will be injected here automatically -->
</div>
javascript
// SDK automatically finds and renders in data-tappd-banner="promo"
await tappd.getBanners('data-tappd-banner="promo"');

3. Both Placement Types ​

Banners can match both CSS selector and data attribute:

javascript
// Banner configured with placement.type: 'both'
// Matches both CSS selector and data attribute

Auto-Rendering (Default) ​

By default, getBanners() automatically renders banners in the target element:

javascript
// Auto-render banners (default behavior)
await tappd.getBanners('#header-banner');

// Explicitly enable auto-render
await tappd.getBanners('#header-banner', { autoRender: true });

The SDK will:

  • Find the target element using the selector
  • Create and style the banner element
  • Add content (title, message, image, CTA button)
  • Add close button if dismissible
  • Apply animations (fade/slide)
  • Track display event automatically
  • Handle click and dismiss events automatically

Custom UI Rendering ​

If you want to render banners with your own UI, you can disable auto-render and use the returned banner data:

javascript
// Fetch banners without auto-rendering
const banners = await tappd.getBanners('#header-banner', { autoRender: false });

// Render with custom UI
banners.forEach(({ banner, variant }) => {
  // Create your custom banner element
  const customBanner = document.createElement('div');
  customBanner.innerHTML = `
    <h3>${variant.content.title}</h3>
    <p>${variant.content.message}</p>
    <button onclick="handleClick('${banner._id}')">${variant.content.cta.text}</button>
  `;
  
  // Track display manually
  tappd.banners.display(banner._id, variant._id, '#header-banner')
    .then(displayId => {
      // Store displayId for click/dismiss tracking
      customBanner.dataset.displayId = displayId;
    });
  
  document.querySelector('#header-banner').appendChild(customBanner);
});

// Handle click with manual tracking
async function handleClick(bannerId) {
  const bannerEl = document.querySelector(`[data-banner-id="${bannerId}"]`);
  const displayId = bannerEl.dataset.displayId;
  await tappd.banners.click(bannerId, displayId);
  // Handle CTA action...
}

Manual Event Tracking ​

For custom UI implementations, you can manually track banner events:

Track Display ​

javascript
// Track banner display and get displayId
const displayId = await tappd.banners.display(
  bannerId,      // Banner ID
  variantId,     // Variant ID
  selector       // Placement selector (e.g., '#header-banner')
);

Track Click ​

javascript
// Track banner click
await tappd.banners.click(bannerId, displayId);

Track Dismiss ​

javascript
// Track banner dismiss
await tappd.banners.dismiss(bannerId, displayId);

The getBanners() method returns an array of banner objects:

javascript
[
  {
    banner: {
      _id: "banner_id_123",
      name: "Summer Sale Banner",
      placement: {
        type: "css_selector",
        cssSelector: "#header-banner",
        dataAttribute: null,
        dataAttributeValue: null
      }
    },
    variant: {
      _id: "variant_id_456",
      name: "Variant A",
      content: {
        title: "Summer Sale",
        message: "Get 50% off on all items!",
        imageUrl: "https://example.com/banner.jpg",
        link: "https://example.com/sale",
        cta: {
          text: "Shop Now",
          link: "https://example.com/sale",
          action: "link"
        }
      },
      design: {
        position: "top",
        layout: "horizontal",
        backgroundColor: "#ffffff",
        textColor: "#000000",
        ctaBackgroundColor: "#007bff",
        ctaTextColor: "#ffffff",
        fontFamily: "Arial, sans-serif",
        fontSize: "16px",
        padding: "16px",
        margin: "0",
        borderRadius: "4px"
      },
      config: {
        dismissible: true,
        autoHide: false,
        autoHideDelay: 5000,
        animation: "fade",
        closeButton: true
      }
    }
  }
]

Complete Examples ​

Example 1: Auto-Render on Page Load ​

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

const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  apiUrl: 'https://sdk.gotappd.com/api/v1/sdk'
});

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

// Auto-render banners when page loads
document.addEventListener('DOMContentLoaded', async () => {
  // Render banners for header
  await tappd.getBanners('#header-banner');
  
  // Render banners for data attribute placement
  await tappd.getBanners('data-tappd-banner="promo"');
});

Example 2: Custom UI with Manual Tracking ​

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

const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  apiUrl: 'https://sdk.gotappd.com/api/v1/sdk'
});

await tappd.identify({
  external_id: 'user_123',
  email: 'john@example.com'
});

// Fetch banners without auto-rendering
const banners = await tappd.getBanners('#header-banner', { autoRender: false });

// Render with custom UI
banners.forEach(async ({ banner, variant }) => {
  const container = document.querySelector('#header-banner');
  const bannerEl = document.createElement('div');
  bannerEl.className = 'custom-banner';
  bannerEl.innerHTML = `
    <img src="${variant.content.imageUrl}" alt="${variant.content.title}">
    <div>
      <h3>${variant.content.title}</h3>
      <p>${variant.content.message}</p>
      <button class="cta-btn">${variant.content.cta.text}</button>
      <button class="close-btn">×</button>
    </div>
  `;
  
  // Track display
  const displayId = await tappd.banners.display(banner._id, variant._id, '#header-banner');
  bannerEl.dataset.displayId = displayId;
  bannerEl.dataset.bannerId = banner._id;
  
  // Handle CTA click
  bannerEl.querySelector('.cta-btn').addEventListener('click', async () => {
    await tappd.banners.click(banner._id, displayId);
    window.location.href = variant.content.cta.link;
  });
  
  // Handle dismiss
  bannerEl.querySelector('.close-btn').addEventListener('click', async () => {
    await tappd.banners.dismiss(banner._id, displayId);
    bannerEl.remove();
  });
  
  container.appendChild(bannerEl);
});

Targeting ​

Banners support customer targeting:

  • Segments: Target specific customer segments
  • Rules: Custom targeting rules based on customer attributes
  • Enabled/Disabled: Toggle targeting on/off

Banners with targeting enabled will only be returned if the customer matches the targeting criteria.

Scheduling ​

Banners support scheduling:

  • Start/End Dates: Set when banners should be active
  • Active Hours: Define specific hours when banners should display
  • Active Days: Define specific days of the week
  • Timezone: Set timezone for schedule calculations

Frequency Capping ​

Control how often banners are shown:

  • Max Displays: Maximum number of times to show a banner
  • Period: Time period (session, hour, day, week, month)
  • Enabled/Disabled: Toggle frequency capping

A/B Testing ​

Banners support A/B testing with variants:

  • Multiple Variants: Create multiple banner variants
  • Traffic Allocation: Control percentage of traffic for each variant
  • Experiment Assignment: Automatic variant assignment based on customer ID

Analytics ​

Banners track comprehensive analytics automatically:

  • Views: Number of times banner was displayed (auto-tracked)
  • Clicks: Number of times banner was clicked (auto-tracked)
  • Dismissals: Number of times banner was dismissed (auto-tracked)
  • Conversions: Number of conversions from banner
  • CTR: Click-through rate (clicks / views)

Best Practices ​

  1. Identify Users Early: Call identify() before fetching banners to enable targeting
  2. Handle Missing Elements: SDK handles missing elements gracefully (logs warning)
  3. Auto-Tracking: SDK automatically tracks all interactions - no manual tracking needed for auto-rendered banners
  4. Custom UI: Use manual tracking methods only when implementing custom UI
  5. Error Handling: SDK handles API errors gracefully and logs warnings
  6. Multiple Banners: SDK supports multiple banners in the same placement
  7. Mobile Responsive: Ensure your target elements are responsive on mobile devices

Troubleshooting ​

Banners not displaying ​

  1. Check that user is identified (identify() has been called)
  2. Verify placement element exists in DOM
  3. Check browser console for warnings/errors
  4. Verify banner is active and published in dashboard
  5. Check targeting conditions are met
  6. Verify schedule is active
  7. Check frequency capping hasn't been reached

Banners displaying incorrectly ​

  1. Check CSS selector or data attribute matches
  2. Verify banner styles are applied correctly
  3. Check for CSS conflicts with your site styles
  4. Ensure container element has proper dimensions

Tracking not working ​

  1. Verify API endpoints are correct (check apiUrl config)
  2. Check that displayId is stored and passed correctly (for custom UI)
  3. Check browser console for network errors
  4. Verify App ID is correct

API Reference ​

getBanners(selector, options?) ​

Fetch and optionally auto-render banners for a placement.

Parameters:

  • selector (string): CSS selector or data attribute selector
  • options (object, optional):
    • autoRender (boolean): Auto-render banners (default: true)

Returns: Promise<Banner[]> - Array of banner data

banners.display(bannerId, variantId, selector) ​

Manually track banner display.

Parameters:

  • bannerId (string): Banner ID
  • variantId (string): Variant ID
  • selector (string): Placement selector

Returns: Promise<string> - Display ID for use with click/dismiss

banners.click(bannerId, displayId) ​

Manually track banner click.

Parameters:

  • bannerId (string): Banner ID
  • displayId (string): Display ID from banners.display()

Returns: Promise<void>

banners.dismiss(bannerId, displayId) ​

Manually track banner dismiss.

Parameters:

  • bannerId (string): Banner ID
  • displayId (string): Display ID from banners.display()

Returns: Promise<void>

Released under the MIT License.

Copyright © 2025 Tappd