npm package: @strimix/tracker-react
Description: React integration for Strimix analytics tracker
Author: Strimix OÜ
Latest version: 0.0.1

# @strimix/react

Official React library for integrating Strimix analytics into your application.

## 🚀 Installation

```bash
npm install @strimix/react
```

---

## 📖 Quick Start

```tsx
import { useEffect } from 'react'
import Strimix from '@strimix/react'

function App() {
  useEffect(() => {
    Strimix.init({ trackerId: 'S-XXXXXXXXXX' })
  }, [])

  return <YourApp />
}

// In any component - direct call
function MyButton() {
  const handleClick = () => {
    Strimix.trackEvent('button_click', {
      event_params: {
        button_name: 'buy_now',
        location: 'header',
      },
    })
  }

  return <button onClick={handleClick}>Buy Now</button>
}
```

---

## 🔧 API

### Initialization

```tsx
Strimix.init({
  trackerId: 'S-XXXXXXXXXX', // Required
  autoPageView: true, // Automatic page_view on load (default: true)
  debug: false, // Console logs (default: false)
})
```

### trackEvent() Method

Universal method for sending any events.

```typescript
Strimix.trackEvent(eventName: string, params?: {
  user_external_ids?: {
    crm_client_id?: string
    [key: string]: any
  }
  order?: {
    id?: string
    status?: string
    manager?: string
    value?: number
    paid_value?: number
    currency?: string
    payment_method?: string
    promo_action?: string
    custom_params?: Record<string, any>
  }
  deal?: {
    id?: string
    status?: string
    manager?: string
    value?: number
    paid_value?: number
    currency?: string
    payment_method?: string
    promo_action?: string
    custom_params?: Record<string, any>
  }
  event_params?: {
    [key: string]: string | number | boolean | null
  }
  [key: string]: any
})
```

---

## 💡 Usage Examples

### 1. Simple Event

```tsx
// Page view
Strimix.trackEvent('page_view')

// Button click
Strimix.trackEvent('button_click', {
  event_params: {
    button_name: 'subscribe',
    location: 'footer',
  },
})
```

### 2. Event with User Identifier

```tsx
Strimix.trackEvent('user_login', {
  user_external_ids: {
    crm_client_id: '655fd150deea972254b7b1d4',
  },
  event_params: {
    login_method: 'google',
    is_new_user: false,
  },
})
```

### 3. Order Event

```tsx
Strimix.trackEvent('order', {
  user_external_ids: {
    crm_client_id: '655fd150deea972254b7b1d4',
  },
  order: {
    id: 'order_12345',
    status: 'paid',
    manager: 'Dmitry Yatsenko',
    value: 100.0,
    paid_value: 50.0,
    currency: 'USD',
    payment_method: 'stripe',
    promo_action: 'Black Friday',
    custom_params: {
      offer_name: '50% discount',
      products_cost_price: 20.0,
      is_new_customer: true,
    },
  },
})
```

### 4. Deal Event

```tsx
Strimix.trackEvent('deal', {
  user_external_ids: {
    crm_client_id: '655fd150deea972254b7b1d4',
  },
  deal: {
    id: 'deal_67890',
    status: 'closed',
    manager: 'Dmitry Yatsenko',
    value: 200.0,
    paid_value: 100.0,
    currency: 'EUR',
    payment_method: 'bank_transfer',
    custom_params: {
      deal_source: 'website_form',
      priority: 'high',
    },
  },
})
```

### 5. Custom Event

```tsx
Strimix.trackEvent('video_watched', {
  user_external_ids: {
    crm_client_id: '655fd150deea972254b7b1d4',
  },
  event_params: {
    video_id: 'vid_123',
    video_title: 'Product Demo',
    duration_seconds: 120,
    completed: true,
  },
})
```

---

## 🛒 E-commerce Example

```tsx
import Strimix from '@strimix/react'

function CheckoutButton({ cart, user }) {
  const handleCheckout = async () => {
    try {
      const order = await processCheckout(cart)

      Strimix.trackEvent('order', {
        user_external_ids: {
          crm_client_id: user.crmId,
        },
        order: {
          id: order.id,
          status: 'paid',
          manager: order.assignedManager,
          value: order.total,
          paid_value: order.paidAmount,
          currency: 'USD',
          payment_method: order.paymentMethod,
          promo_action: order.promoCode,
          custom_params: {
            items_count: cart.items.length,
            shipping_method: order.shippingMethod,
            is_new_customer: user.isFirstPurchase,
          },
        },
        products: card.products.map((el) => ({
          id: el.id,
          name: el.name,
          brand: el.brand,
          category: el.category,
          sku: el.sku,
          quantity: el.quantity,
          value: el.value,
          currency: el.currency,
          promo_action: el.promo_action,
          discount_amount: el.discount_amount,
          discount_percentage: el.discount_percentage,
        })),
      })

      router.push('/success')
    } catch (error) {
      Strimix.trackEvent('order_error', {
        user_external_ids: {
          crm_client_id: user.crmId,
        },
        event_params: {
          error_message: error.message,
          cart_value: cart.total,
        },
      })
    }
  }

  return <button onClick={handleCheckout}>Checkout</button>
}
```

---

## 📊 CRM Integration

```tsx
import Strimix from '@strimix/react'

function DealManager({ client, dealData }) {
  const handleCreateDeal = async () => {
    const deal = await createDealInCRM(dealData)

    Strimix.trackEvent('deal', {
      user_external_ids: {
        crm_client_id: client.id,
      },
      deal: {
        id: deal.id,
        status: 'open',
        manager: deal.assignedManager,
        value: deal.estimatedValue,
        paid_value: 0,
        currency: 'USD',
        custom_params: {
          source: 'website_form',
          priority: deal.priority,
          expected_close_date: deal.expectedCloseDate,
          lead_score: deal.leadScore,
        },
      },
    })
  }

  return <button onClick={handleCreateDeal}>Create Deal</button>
}
```

---

## 🎯 React Router Integration

```tsx
import { useEffect } from 'react'
import { useLocation } from 'react-router-dom'
import Strimix from '@strimix/react'

function RouteTracker() {
  const location = useLocation()

  useEffect(() => {
    Strimix.trackEvent('page_view')
  }, [location.pathname])

  return null
}

function App() {
  useEffect(() => {
    Strimix.init({ trackerId: 'S-XXXXXXXXXX', autoPageView: false })
  }, [])

  return (
    <BrowserRouter>
      <RouteTracker />
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/products" element={<Products />} />
      </Routes>
    </BrowserRouter>
  )
}
```

---

## 🔍 Debugging

Enable debug mode to see all events in the console:

```tsx
Strimix.init({
  trackerId: 'S-XXXXXXXXXX',
  debug: true, // ← Enable logs
})
```

In the console you will see:

```
[Strimix] Script loaded and initialized with tracker: S-XXXXXXXXXX
[Strimix] Event pushed: { event: 'page_view' }
[Strimix] Event pushed: { event: 'order', user_external_ids: {...}, order: {...} }
```

---

## 🛡️ TypeScript

The library is fully typed:

```typescript
import Strimix, {
  StrimixConfig,
  StrimixUserExternalIds,
  StrimixOrderDeal,
  StrimixEventParams,
} from '@strimix/react'

const config: StrimixConfig = {
  trackerId: 'S-XXXXXXXXXX',
  autoPageView: true,
  debug: false,
}

const userIds: StrimixUserExternalIds = {
  crm_client_id: '655fd150deea972254b7b1d4',
}

const orderData: StrimixOrderDeal = {
  id: 'order_123',
  status: 'paid',
  value: 100.0,
  currency: 'USD',
}

Strimix.trackEvent('order', {
  user_external_ids: userIds,
  order: orderData,
})
```

---

## 📦 Single Way to Use

```tsx
import Strimix from '@strimix/react'
Strimix.init({ trackerId: 'S-XXXXXXXXXX' })
Strimix.trackEvent('order', {...})
```

---

## 📚 Additional Documentation

- **[QUICKSTART.md](./QUICKSTART.md)** - Quick start in 2 minutes
- **[SINGLETON_VS_CONTEXT.md](./SINGLETON_VS_CONTEXT.md)** - Approach comparison
- **[JAVASCRIPT_USAGE.md](./JAVASCRIPT_USAGE.md)** - JavaScript examples
- **[INTEGRATION_EXAMPLES.md](./INTEGRATION_EXAMPLES.md)** - Next.js, Remix, Gatsby and more
- **[DEVELOPMENT.md](./DEVELOPMENT.md)** - Developer guide
- **[PUBLISHING.md](./PUBLISHING.md)** - How to publish to npm

---

## 📄 License

MIT © Strimix OÜ

---

## 🤝 Support

- 📧 Email: support@strimix.io
- 🐛 Issues: [GitHub Issues](https://github.com/strimix/strimix-react/issues)
- 📚 Documentation: [docs.strimix.io](https://docs.strimix.io)