Перейти к основному содержимому

SDK (Software Development Kit)

Используйте официальные SDK для удобной интеграции Metriox в ваше приложение.

Доступные SDK​

JavaScript/TypeScript​

Для Node.js, Deno и браузера.

Установка​

npm install @metriox/sdk
# или
yarn add @metriox/sdk
# или
pnpm add @metriox/sdk

Использование​

import { MetrioxClient } from "@metriox/sdk";

const client = new MetrioxClient({
  apiKey: "YOUR_API_KEY",
  botId: "your_bot_id", // опционально
});

// Отправка события
await client.track({
  event_name: "button_click",
  platform_user_id: "123456789",
  props: {
    button_name: "checkout",
    price: 299,
    currency: "RUB",
  },
});

API​

track(event)​

Отправить одно событие.

await client.track({
  event_name: "purchase_completed",
  platform_user_id: "123456789",
  session_id: "session-id-123",
  props: {
    amount: 299,
    currency: "RUB",
  },
});
trackBatch(events)​

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

await client.trackBatch([
  {
    event_name: "page_view",
    platform_user_id: "123456789",
    props: { page: "/home" },
  },
  {
    event_name: "button_click",
    platform_user_id: "123456789",
    props: { button: "checkout" },
  },
]);
setUserId(userId)​

Установить ID пользователя для всех последующих событий.

client.setUserId("123456789");

await client.track({
  event_name: "page_view",
  // platform_user_id не требуется, будет взято из setUserId
  props: { page: "/products" },
});
flush()​

Отправить все оставшиеся события.

await client.flush();

Примеры​

React:

import { useEffect } from "react";
import { MetrioxClient } from "@metriox/sdk";

const client = new MetrioxClient({
  apiKey: "YOUR_API_KEY",
});

export function Button() {
  const handleClick = async () => {
    await client.track({
      event_name: "button_click",
      platform_user_id: "user-id",
      props: { button_name: "subscribe" },
    });
  };

  return <button onClick={handleClick}>Subscribe</button>;
}

Next.js:

import { MetrioxClient } from "@metriox/sdk";

const client = new MetrioxClient({
  apiKey: process.env.NEXT_PUBLIC_METRIOX_API_KEY,
});

export default async function Home() {
  await client.track({
    event_name: "page_view",
    platform_user_id: "user-id",
    props: { page: "home" },
  });

  return <div>Hello World</div>;
}

C#/.NET​

Для приложений на C# и .NET.

Установка​

dotnet add package Metriox.Sdk

или через NuGet Package Manager:

Install-Package Metriox.Sdk

Использование​

using Metriox;

var client = new MetrioxClient(
  apiKey: "YOUR_API_KEY",
  botId: "your_bot_id"  // опционально
);

// Отправка события
await client.TrackAsync(new Event
{
    EventName = "button_click",
    PlatformUserId = "123456789",
    Props = new Dictionary<string, object>
    {
        { "button_name", "checkout" },
        { "price", 299 },
        { "currency", "RUB" }
    }
});

API​

TrackAsync(event)​

Отправить одно событие.

await client.TrackAsync(new Event
{
    EventName = "purchase_completed",
    PlatformUserId = "123456789",
    SessionId = "session-id-123",
    Props = new Dictionary<string, object>
    {
        { "amount", 299 },
        { "currency", "RUB" }
    }
});
TrackBatchAsync(events)​

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

var events = new List<Event>
{
    new Event
    {
        EventName = "page_view",
        PlatformUserId = "123456789",
        Props = new Dictionary<string, object> { { "page", "/home" } }
    },
    new Event
    {
        EventName = "button_click",
        PlatformUserId = "123456789",
        Props = new Dictionary<string, object> { { "button", "checkout" } }
    }
};

await client.TrackBatchAsync(events);
SetUserId(userId)​

Установить ID пользователя.

client.SetUserId("123456789");

await client.TrackAsync(new Event
{
    EventName = "page_view",
    Props = new Dictionary<string, object> { { "page", "/products" } }
});
FlushAsync()​

Отправить все оставшиеся события.

await client.FlushAsync();

Примеры​

ASP.NET Core:

using Metriox;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
public class CheckoutController : ControllerBase
{
    private readonly MetrioxClient _metrioxClient;

    public CheckoutController(MetrioxClient metrioxClient)
    {
        _metrioxClient = metrioxClient;
    }

    [HttpPost("complete")]
    public async Task<IActionResult> CompleteCheckout(int amount)
    {
        await _metrioxClient.TrackAsync(new Event
        {
            EventName = "purchase_completed",
            PlatformUserId = "user-id",
            Props = new Dictionary<string, object>
            {
                { "amount", amount },
                { "currency", "RUB" }
            }
        });

        return Ok();
    }
}

Dependency Injection (Startup):

public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton(new MetrioxClient(
        apiKey: Configuration["Metriox:ApiKey"]
    ));

    services.AddControllers();
}

Лучшие практики​

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

Никогда не hardcodируйте API ключ. Используйте переменные окружения:

JavaScript:

const client = new MetrioxClient({
  apiKey: process.env.METRIOX_API_KEY,
});

C#:

var apiKey = Configuration["Metriox:ApiKey"];
var client = new MetrioxClient(apiKey);

Отправка при завершении​

Всегда вызывайте flush() перед завершением приложения:

process.on("exit", async () => {
  await client.flush();
});

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

try {
  await client.track(event);
} catch (error) {
  console.error("Failed to track event:", error);
  // Логируйте ошибку или отправьте в систему мониторинга
}

Что дальше?​