npm package: @gonderai/sdk
Description: Official Gönder SDK for tracking user events and conversions
Author: Gönder
Latest version: 1.0.3

# Gönder SDK

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

## Installation

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

## Quick Start

```typescript
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: "user@example.com", 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

```typescript
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

```typescript
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

```typescript
// 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

```typescript
// 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

```typescript
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:
   ```javascript
   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:
   ```javascript
   // 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

```javascript
// 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