📨 Первое событие

Отправьте своё первое событие в InstantBase и увидьте данные в дашборде

💡 Перед началом: Убедитесь, что у вас есть API-ключ. Для тестирования используйте тестовый ключ.

Что такое событие?

В InstantBase событие — это любое действие пользователя в вашем приложении или на сайте. Каждое событие содержит:

Структура события

Поле Тип Обязательное Описание
event string ✅ Да Название события. Используйте понятные имена: purchase, page_view, add_to_cart
user_id string ⚠️* ID авторизованного пользователя в вашей системе
anonymous_id string ⚠️* ID неавторизованного пользователя (cookie, device ID)
timestamp string (ISO 8601) ❌ Нет Время события. Если не указано, используется серверное
properties object ❌ Нет Параметры события. Может содержать любые данные в формате JSON
session_id string ❌ Нет ID сессии для группировки событий

* Должен быть передан либо user_id, либо anonymous_id. Можно передавать оба — в этом случае они будут связаны в единый профиль.

Отправка первого события через curl

Самый простой способ протестировать интеграцию — отправить событие через терминал с помощью curl:

bash 
curl -X POST https://api.instantbase.online/v1/track \
  -H "X-API-Key: ваш_тестовый_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "test_event",
    "user_id": "test_user_123",
    "properties": {
      "source": "curl",
      "test_property": "Hello World!"
    }
  }'

Замените ваш_тестовый_ключ на реальный ключ из личного кабинета.

Ожидаемый ответ

json 
{
  "status": "ok",
  "message": "Event received",
  "queued": true
}

Ответ "queued": true означает, что событие успешно принято и поставлено в очередь на обработку.

Отправка события из JavaScript

Для отправки событий с веб-сайта используйте fetch API:

javascript 
// Функция для отправки события
async function trackEvent(eventName, userId, properties = {}) {
  try {
    const response = await fetch('https://api.instantbase.online/v1/track', {
      method: 'POST',
      headers: {
        'X-API-Key': 'ваш_тестовый_ключ',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        event: eventName,
        user_id: userId,
        properties: properties,
        timestamp: new Date().toISOString()
      })
    });
    
    const data = await response.json();
    console.log('Event tracked:', data);
    return data;
  } catch (error) {
    console.error('Failed to track event:', error);
  }
}

// Использование
trackEvent('page_view', 'user_123', {
  page: '/home',
  referrer: document.referrer
});
⚠️ Внимание: Никогда не используйте production-ключи в клиентском JavaScript — они будут видны всем. Для клиентской отправки используйте тестовые ключи или проксируйте запросы через свой бэкенд.

Отправка события из Node.js

javascript 
const axios = require('axios');

const API_KEY = process.env.INSTANTBASE_API_KEY;

async function trackEvent(event, userId, properties = {}) {
  try {
    const response = await axios.post('https://api.instantbase.online/v1/track', {
      event,
      user_id: userId,
      properties,
      timestamp: new Date().toISOString()
    }, {
      headers: {
        'X-API-Key': API_KEY
      }
    });
    
    console.log('Event tracked:', response.data);
    return response.data;
  } catch (error) {
    console.error('Failed to track event:', 
      error.response?.data || error.message
    );
  }
}

// Пример использования
trackEvent('user_signup', 'user_123', {
  email: 'user@example.com',
  source: 'google_ads'
});

Отправка события из Python

python 
import os
import requests
from datetime import datetime

API_KEY = os.environ.get('INSTANTBASE_API_KEY')

def track_event(event, user_id, properties=None):
    url = 'https://api.instantbase.online/v1/track'
    headers = {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json'
    }
    data = {
        'event': event,
        'user_id': user_id,
        'properties': properties or {},
        'timestamp': datetime.now().isoformat()
    }
    
    try:
        response = requests.post(url, json=data, headers=headers)
        response.raise_for_status()
        print('Event tracked:', response.json())
        return response.json()
    except requests.exceptions.RequestException as e:
        print('Failed to track event:', e)
        if hasattr(e.response, 'text'):
            print('Response:', e.response.text)

# Пример использования
track_event('purchase', 'user_123', {
    'order_id': 'ORD-001',
    'amount': 1499.99,
    'items': ['item1', 'item2']
})

Отправка события из PHP

php 
<?php
function trackEvent($event, $userId, $properties = []) {
    $apiKey = getenv('INSTANTBASE_API_KEY');
    
    $data = [
        'event' => $event,
        'user_id' => $userId,
        'properties' => $properties,
        'timestamp' => date('c')
    ];
    
    $ch = curl_init('https://api.instantbase.online/v1/track');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'X-API-Key: ' . $apiKey,
        'Content-Type: application/json'
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 200) {
        echo "Event tracked successfully\n";
        return json_decode($response, true);
    } else {
        echo "Failed to track event. HTTP code: $httpCode\n";
        echo "Response: $response\n";
        return null;
    }
}

// Пример использования
trackEvent('page_view', 'user_123', [
    'page' => '/products',
    'referrer' => 'google'
]);
?>

Проверка доставки события

После отправки события подождите 1-2 минуты и проверьте:

  1. Зайдите в личный кабинет InstantBase
  2. Перейдите в раздел "События"
  3. В ленте событий вы должны увидеть ваше тестовое событие
  4. Нажмите на событие, чтобы увидеть все переданные параметры
💡 Совет: Используйте фильтр по user_id или event, чтобы быстро найти нужное событие.

Примеры событий для разных ситуаций

Просмотр страницы

{
  "event": "page_view",
  "user_id": "user_123",
  "properties": {
    "page": "/products",
    "title": "Каталог товаров",
    "referrer": "https://google.com"
  }
}

Регистрация пользователя

{
  "event": "signup",
  "user_id": "user_123",
  "properties": {
    "method": "email",
    "source": "facebook_ads"
  },
  "attributes": {
    "email": "user@example.com",
    "name": "Иван Петров"
  }
}

Покупка

{
  "event": "purchase",
  "user_id": "user_123",
  "properties": {
    "order_id": "ORD-12345",
    "revenue": 5499,
    "items": [
      {"id": "prod_1", "name": "Футболка", "price": 1999, "quantity": 2},
      {"id": "prod_2", "name": "Джинсы", "price": 3500, "quantity": 1}
    ]
  },
  "_metadata": {
    "is_order": true
  }
}

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

Код Ошибка Причина Решение
400 Invalid JSON Неверный формат JSON Проверьте синтаксис JSON
400 Missing required field: event Не указано название события Добавьте поле event
400 Either user_id or anonymous_id is required Не указан идентификатор пользователя Добавьте user_id или anonymous_id
401 Invalid or missing API key Неверный или отсутствующий ключ Проверьте ключ в заголовке X-API-Key
429 Too many requests Превышен rate limit Подождите и повторите запрос
500 Internal server error Ошибка на сервере Повторите запрос позже

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

  • Именование событий: используйте snake_case (например, page_view, add_to_cart)
  • Не передавайте чувствительные данные: пароли, номера карт, персональные данные
  • Используйте тестовые ключи на этапе разработки
  • Группируйте события сессией для анализа пути пользователя
  • Передавайте все важные параметры — это поможет в будущем анализе

Что дальше?

📊 Дашборд

Как работать с полученными данными в интерфейсе

Перейти →

📋 API Reference

Полное описание всех эндпоинтов

Перейти →

Не работает?

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

support@instantbase.online Telegram