📱 JavaScript SDK

Официальный SDK для браузеров, Node.js и популярных фреймворков

🎯 Что вы получите
  • Простой и удобный API для отправки событий
  • Автоматическое управление сессиями и идентификаторами
  • Поддержка популярных фреймворков (React, Vue, Angular)
  • Готовые методы для типовых событий
  • Автоматическая обработка ошибок и повторные попытки

Установка

# npm
npm install @instantbase/javascript-sdk

# yarn
yarn add @instantbase/javascript-sdk

# pnpm
pnpm add @instantbase/javascript-sdk
<!-- Подключение в браузере -->
<script src="https://cdn.instantbase.online/sdk/v1/instantbase.min.js"></script>

<!-- Или с конкретной версией -->
<script src="https://cdn.instantbase.online/sdk/v1/instantbase-1.0.0.min.js"></script>
// Для Node.js используйте npm пакет
const InstantBase = require('@instantbase/javascript-sdk');

// Или с импортом (ES modules)
import InstantBase from '@instantbase/javascript-sdk';

Быстрый старт

// Инициализация SDK
const ib = new InstantBase({
  apiKey: 'your_api_key',
  // Опциональные параметры
  environment: 'production', // 'production' или 'development'
  autoTrack: true, // автоматически отслеживать page_view
  sessionTimeout: 30, // минут неактивности для новой сессии
  debug: false // режим отладки
});

// Отправка простого события
ib.track('button_click', {
  button_id: 'signup',
  page: '/home'
});

// Отправка события с пользователем
ib.track('purchase', {
  order_id: 'ORD-001',
  amount: 1499.99
}, {
  user_id: 'user_123'
});

// Установка идентификатора пользователя
ib.identify('user_123', {
  email: 'user@example.com',
  name: 'Иван Петров',
  plan: 'premium'
});

Конфигурация SDK

constructor Параметры инициализации
Параметр Тип По умолчанию Описание
apiKey string — Обязательный. Ваш API-ключ
environment string 'production' Режим работы. 'development' для отладки
autoTrack boolean true Автоматически отслеживать page_view
sessionTimeout number 30 Минут неактивности для новой сессии
debug boolean false Включает логирование в консоль
batchSize number 10 Количество событий в батче
flushInterval number 5000 Интервал отправки батча (мс)
maxRetries number 3 Количество повторных попыток при ошибке

Основные методы

track() Отправка события

Основной метод для отправки событий.

// Синтаксис
ib.track(eventName, properties, options);

// Простое событие
ib.track('button_click', {
  button_id: 'submit'
});

// С метаданными
ib.track('purchase', {
  order_id: 'ORD-001',
  amount: 1499.99
}, {
  user_id: 'user_123',
  metadata: {
    is_order: true,
    funnel_sales_step: 4
  }
});

// С асинхронным ожиданием
await ib.track('signup', {
  method: 'email'
});
Параметр Тип Описание
eventName string Название события
properties object Свойства события (опционально)
options.user_id string ID пользователя (если отличается от текущего)
options.metadata object Метаданные события
options.timestamp string Время события (ISO 8601)
identify() Идентификация пользователя

Устанавливает идентификатор и атрибуты пользователя.

// Простая идентификация
ib.identify('user_123');

// С атрибутами
ib.identify('user_123', {
  email: 'user@example.com',
  name: 'Иван Петров',
  plan: 'premium',
  age: 30
});

// С метаданными атрибутов
ib.identify('user_123', {
  email: 'user@example.com',
  plan: 'premium'
}, {
  plan: {
    attribute_display_name: 'Тариф',
    attribute_category: 'Подписка'
  }
});
Параметр Тип Описание
userId string Уникальный ID пользователя
traits object Атрибуты пользователя (опционально)
metadata object Метаданные атрибутов (опционально)
alias() Связывание идентификаторов

Связывает анонимный ID с авторизованным пользователем.

// При авторизации
ib.alias('anonymous_123', 'user_123');

// Если текущий пользователь анонимный
ib.identify('user_123'); // автоматически свяжет с текущим anonymous_id
page() Отслеживание страницы

Отслеживает просмотр страницы. Автоматически вызывается при autoTrack: true.

// Ручной вызов
ib.page({
  page: '/products',
  title: 'Каталог товаров',
  referrer: document.referrer
});

// С метаданными
ib.page({
  page: '/checkout'
}, {
  funnel_sales_step: 3
});
reset() Сброс сессии

Сбрасывает текущую сессию и генерирует новый anonymous_id.

// При выходе пользователя
ib.reset();

// Принудительно с новым anonymous_id
ib.reset(true);

Работа с сессиями

// SDK автоматически управляет сессиями
// Сессия начинается при первом событии
// Новая сессия создается после 30 минут неактивности

// Ручное управление сессией
ib.startSession(); // принудительно начать новую сессию
ib.getSessionId(); // получить текущий session_id
ib.getAnonymousId(); // получить anonymous_id

// Пример: отслеживание времени сессии
const sessionStart = Date.now();

window.addEventListener('beforeunload', () => {
  const duration = Math.round((Date.now() - sessionStart) / 1000);
  ib.track('session_end', { duration });
});

Интеграция с React

React Hooks

// instantbase.js - создание клиента
import InstantBase from '@instantbase/javascript-sdk';

const client = new InstantBase({
  apiKey: process.env.REACT_APP_INSTANTBASE_KEY,
  debug: process.env.NODE_ENV === 'development'
});

export default client;
// hooks/useTracking.js
import { useEffect } from 'react';
import ib from '../instantbase';

export function useTracking() {
  const track = (event, properties) => {
    ib.track(event, properties);
  };
  
  const identify = (userId, traits) => {
    ib.identify(userId, traits);
  };
  
  return { track, identify };
}

// components/ProductPage.jsx
import { useTracking } from '../hooks/useTracking';

function ProductPage({ product }) {
  const { track } = useTracking();
  
  useEffect(() => {
    track('product_view', {
      product_id: product.id,
      product_name: product.name,
      price: product.price
    });
  }, [product]);
  
  const handleBuy = () => {
    track('purchase', {
      product_id: product.id,
      price: product.price
    });
  };
  
  return (
    <div>
      <h1>{product.name}</h1>
      <button onClick={handleBuy}>Купить</button>
    </div>
  );
}

React Context

// TrackingContext.js
import React, { createContext, useContext } from 'react';
import ib from '../instantbase';

const TrackingContext = createContext(null);

export function TrackingProvider({ children }) {
  const track = (event, properties) => ib.track(event, properties);
  const identify = (userId, traits) => ib.identify(userId, traits);
  
  return (
    <TrackingContext.Provider value={{ track, identify }}>
      {children}
    </TrackingContext.Provider>
  );
}

export const useTracking = () => {
  const context = useContext(TrackingContext);
  if (!context) {
    throw new Error('useTracking must be used within TrackingProvider');
  }
  return context;
};

// App.jsx
function App() {
  return (
    <TrackingProvider>
      <Router>
        <Routes>
          <Route path="/" element={<HomePage />} />
        </Routes>
      </Router>
    </TrackingProvider>
  );
}

Интеграция с Vue

// plugins/instantbase.js
import InstantBase from '@instantbase/javascript-sdk';

export default {
  install: (app, options) => {
    const client = new InstantBase({
      apiKey: options.apiKey,
      debug: options.debug
    });
    
    // Добавляем глобальные методы
    app.config.globalProperties.$track = client.track.bind(client);
    app.config.globalProperties.$identify = client.identify.bind(client);
    
    // Добавляем в provide для composition API
    app.provide('tracking', {
      track: client.track.bind(client),
      identify: client.identify.bind(client)
    });
  }
};

// main.js
import { createApp } from 'vue';
import App from './App.vue';
import InstantBasePlugin from './plugins/instantbase';

const app = createApp(App);
app.use(InstantBasePlugin, {
  apiKey: import.meta.env.VITE_INSTANTBASE_KEY,
  debug: import.meta.env.DEV
});
app.mount('#app');
<!-- components/ProductPage.vue -->
<template>
  <div>
    <h1>{{ product.name }}</h1>
    <button @click="handleBuy">Купить</button>
  </div>
</template>

<script setup>
import { inject, onMounted } from 'vue';

const props = defineProps(['product']);
const { track } = inject('tracking');

onMounted(() => {
  track('product_view', {
    product_id: props.product.id,
    product_name: props.product.name,
    price: props.product.price
  });
});

const handleBuy = () => {
  track('purchase', {
    product_id: props.product.id,
    price: props.product.price
  });
};
</script>

Интеграция с Angular

// services/tracking.service.ts
import { Injectable } from '@angular/core';
import InstantBase from '@instantbase/javascript-sdk';

@Injectable({
  providedIn: 'root'
})
export class TrackingService {
  private client: InstantBase;
  
  constructor() {
    this.client = new InstantBase({
      apiKey: environment.instantbaseKey,
      debug: !environment.production
    });
  }
  
  track(event: string, properties?: any) {
    return this.client.track(event, properties);
  }
  
  identify(userId: string, traits?: any) {
    return this.client.identify(userId, traits);
  }
  
  page(properties?: any) {
    return this.client.page(properties);
  }
}
// app.component.ts
import { Component, OnInit } from '@angular/core';
import { TrackingService } from './services/tracking.service';

@Component({
  selector: 'app-root',
  template: `
    <h1>{{ product.name }}</h1>
    <button (click)="buy()">Купить</button>
  `
})
export class AppComponent implements OnInit {
  product = { id: 'prod_1', name: 'Футболка', price: 1999 };
  
  constructor(private tracking: TrackingService) {}
  
  ngOnInit() {
    this.tracking.page({
      page: '/product',
      title: this.product.name
    });
    
    this.tracking.track('product_view', {
      product_id: this.product.id,
      product_name: this.product.name,
      price: this.product.price
    });
  }
  
  buy() {
    this.tracking.track('purchase', {
      product_id: this.product.id,
      price: this.product.price
    });
  }
}

Автоматический сбор данных

Автоматические события

При включенном autoTrack: true SDK автоматически отслеживает:

Событие Описание Свойства
page_view Просмотр страницы url, title, referrer
click Клик по элементу (опционально) element, text, id
form_submit Отправка формы form_id, form_name
error JavaScript ошибка message, source, line 
// Отключение автоматических событий
const ib = new InstantBase({
  apiKey: 'your_key',
  autoTrack: false
});

// Включение только нужных авто-событий
const ib = new InstantBase({
  apiKey: 'your_key',
  autoTrack: {
    page: true,
    clicks: false,
    forms: true,
    errors: false
  }
});

Пакетная отправка

SDK поддерживает пакетную отправку событий для оптимизации сети:

// Настройка батчинга
const ib = new InstantBase({
  apiKey: 'your_key',
  batchSize: 20,        // отправлять по 20 событий
  flushInterval: 10000,  // или каждые 10 секунд
  maxRetries: 3          // повторять при ошибке
});

// Ручная отправка батча
await ib.flush();

// Отключение батчинга (отправлять сразу)
const ib = new InstantBase({
  apiKey: 'your_key',
  batchSize: 1
});

Обработка ошибок

// Подписка на ошибки
ib.on('error', (error) => {
  console.error('Tracking error:', error);
});

// Подписка на успешную отправку
ib.on('success', (event) => {
  console.log('Event sent:', event);
});

// Подписка на все события
ib.on('*', (type, data) => {
  console.log(`${type}:`, data);
});

// Ручная обработка ошибок
try {
  await ib.track('purchase', { amount: 100 });
} catch (error) {
  if (error.code === 'RATE_LIMIT') {
    // Подождать и повторить
  } else if (error.code === 'INVALID_KEY') {
    // Проблема с API ключом
  }
}

Режим отладки

// Включение отладки
const ib = new InstantBase({
  apiKey: 'your_key',
  debug: true
});

// В консоли будут отображаться:
// ✓ Инициализация SDK
// ✓ Отправляемые события
// ✓ Ответы от сервера
// ✓ Ошибки (если есть)

// Пример вывода:
// [InstantBase] Initialized with key: prod_xxx
// [InstantBase] Tracking event: purchase
// [InstantBase] Event sent: { status: 'ok', queued: true }

Типы данных и валидация

Тип Пример Валидация
string "user_123" Автоматически
number 1499.99 Автоматически
boolean true Автоматически
array ["item1", "item2"] Автоматически
object { key: "value" } Автоматически

SDK автоматически валидирует обязательные поля и типы данных.

Сравнение методов

Метод Когда использовать Автоматический session_id Автоматический timestamp
track() Любые пользовательские события ✅ ✅
identify() При авторизации или обновлении профиля ✅ ✅
page() Просмотр страниц (SPA) ✅ ✅
alias() Связывание анонимного и авторизованного ID ✅ ✅

Примеры для разных случаев

E-commerce

// Просмотр товара
ib.track('product_view', {
  product_id: 'prod_123',
  product_name: 'Футболка',
  price: 1999,
  category: 'Одежда'
}, {
  metadata: {
    funnel_sales_step: 1
  }
});

// Добавление в корзину
ib.track('add_to_cart', {
  product_id: 'prod_123',
  quantity: 2,
  price: 1999
}, {
  metadata: {
    funnel_sales_step: 2
  }
});

// Покупка
ib.track('purchase', {
  order_id: 'ORD-001',
  total: 5499,
  items: [
    { id: 'prod_123', quantity: 2, price: 1999 }
  ]
}, {
  metadata: {
    funnel_sales_step: 4,
    is_order: true
  }
});

SaaS

// Регистрация
ib.identify('user_123', {
  email: 'user@example.com',
  name: 'Иван Петров',
  company: 'ООО Ромашка'
});

// Активация (ключевое действие)
ib.track('project_created', {
  project_name: 'Мой проект',
  template: 'blank'
}, {
  metadata: {
    funnel_sales_step: 2,
    is_activation: true
  }
});

// Начало триала
ib.track('trial_started', {
  plan: 'pro',
  trial_days: 14
});

// Апгрейд
ib.track('subscription_upgraded', {
  old_plan: 'basic',
  new_plan: 'pro',
  amount: 9900
}, {
  metadata: { is_order: true }
});

Рекомендации

  • Инициализируйте SDK сразу после загрузки страницы — чтобы не пропустить события
  • Используйте identify() при авторизации — для связывания анонимных действий с пользователем
  • Включайте debug: true в разработке — для отладки интеграции
  • Не храните API-ключи в клиентском коде — используйте прокси-сервер для production ключей
  • Используйте батчинг для высоконагруженных проектов — снижает нагрузку на сеть
  • Подписывайтесь на ошибки — для мониторинга проблем с интеграцией
⚠️ ВАЖНО: Production API-ключи не должны использоваться в клиентском коде. Используйте тестовые ключи для разработки или проксируйте запросы через свой бэкенд.

Что дальше?

🐍 Python SDK

Для серверных приложений на Python

Перейти →

🐘 PHP SDK

Для проектов на PHP

Перейти →

Нужна помощь с JavaScript SDK?

Напишите нам, и мы поможем настроить интеграцию

support@instantbase.online Telegram