Gönder SDK

Official JS Gönder SDK for tracking user events and conversions on your website.

Installation

npm install @gonderai/sdk
# or
yarn add @gonderai/sdk
# or
pnpm add @gonderai/sdk

Quick Start

import { Gonder } from "@gonderai/sdk";

// Initialize with your API key
Gonder.init({
  apiKey: "gnd_your_api_key_here",
  debug: true, // Optional: enable debug logging
});

// Track page views
Gonder.pages.view();

// Track user events
Gonder.users.signup({ email: "[email protected]", name: "John Doe" });
Gonder.users.login({ userId: "user_123" });

// Track commerce events
Gonder.commerce.viewProduct({
  productId: "SKU123",
  productName: "T-Shirt",
  price: 29.99,
});
Gonder.commerce.addToCart({ productId: "SKU123", price: 29.99, quantity: 2 });
Gonder.commerce.checkout({ value: 59.98, currency: "USD" });
Gonder.commerce.paymentCompleted({
  orderId: "ORD-001",
  value: 59.98,
  currency: "USD",
});

// Track custom events
Gonder.events.send({
  event: "newsletter_signup",
  payload: { source: "footer_form" },
});

API Reference

Initialization

Gonder.init({
  apiKey: string;     // Required: Your API key from the Gönder dashboard
  endpoint?: string;  // Optional: Custom API endpoint
  debug?: boolean;    // Optional: Enable console logging
});

Page Tracking

Gonder.pages.view({
  url?: string;      // Page URL (auto-detected if not provided)
  title?: string;    // Page title (auto-detected if not provided)
  referrer?: string; // Referrer URL (auto-detected if not provided)
});

User Tracking

// Track login
Gonder.users.login({
  userId?: string;
  email?: string;
  method?: string; // 'email', 'google', 'facebook', etc.
});

// Track logout
Gonder.users.logout({
  userId?: string;
});

// Track signup
Gonder.users.signup({
  userId?: string;
  email?: string;
  name?: string;
  method?: string;
  source?: string;
});

Commerce Tracking

// Product view
Gonder.commerce.viewProduct({
  productId: string;
  productName?: string;
  price?: number;
  currency?: string;
  category?: string;
});

// Add to cart
Gonder.commerce.addToCart({
  productId: string;
  productName?: string;
  price?: number;
  quantity?: number;
  currency?: string;
});

// Remove from cart
Gonder.commerce.removeFromCart({
  productId: string;
  quantity?: number;
});

// Checkout
Gonder.commerce.checkout({
  value: number;       // Required: Cart total
  currency?: string;
  orderId?: string;
  itemCount?: number;
  couponCode?: string;
});

// Payment completed
Gonder.commerce.paymentCompleted({
  orderId: string;     // Required: Order ID
  value: number;       // Required: Amount paid
  currency?: string;
  paymentMethod?: string;
  transactionId?: string;
});

Custom Events

Gonder.events.send({
  event: string;       // Required: Event name
  payload?: {
    userId?: string;
    email?: string;
    value?: number;    // For conversion tracking
    currency?: string;
    properties?: Record<string, unknown>;
  };
});

Campaign Attribution Tracking

The SDK automatically tracks campaign attribution when users click links in your email campaigns. No additional code is required!

How It Works

1. Email Links: All links in your campaigns are automatically injected with tracking parameters:

   https://yoursite.com/products?sid=contact-id&cid=campaign-id

2. Automatic Capture: When users land on your site, the SDK captures these parameters on initialization:

   Gonder.init({ apiKey: 'your-key' });
   // Automatically extracts sid and cid from URL
   // Stores in sessionStorage for persistence

3. Attribution Included: All subsequent events automatically include the attribution:

   // User browses and converts
   Gonder.commerce.paymentCompleted({
     orderId: 'ORD-123',
     value: 99.99,
     currency: 'USD'
   });
   // SDK automatically sends: subscriberId, campaignId

4. Dashboard Attribution: Conversions are attributed back to the originating campaign in your Gönder dashboard.

Check Attribution

// Get current attribution
const attribution = Gonder.getAttribution();
console.log(attribution);
// { subscriberId: 'contact-id', campaignId: 'campaign-id' }

Session Persistence

• Attribution persists across page navigation (stored in sessionStorage)
• Cleared when browser tab is closed (privacy-friendly)
• Works without cookies or localStorage

License

MIT