Справочник Ingest API

npm install @tracklane/sdk

import { TrackLane } from '@tracklane/sdk';

export const tl = TrackLane.init({
  publishableKey: 'tl_pub_8Kq2vN4xR7mT1pLz',   // публичный ключ проекта
  signingKeyEndpoint: '/api/telemetry/key',     // выдаёт эфемерный ключ подписи
  service: 'storefront-web',
  environment: 'production',
  release: '2026.10.3',
  batch: { maxEvents: 500, maxDelayMs: 5000 },
});

{
  "protocol": 2,
  "batch_id": "bat_01JA8ZK4T3M9Q2XW7RVN5HCD6E",
  "sent_at": "2026-10-15T09:41:27.384Z",
  "resource": {
    "service": "storefront-web",
    "environment": "production",
    "release": "2026.10.3",
    "sdk": { "name": "@tracklane/sdk", "version": "4.12.0" }
  },
  "session": {
    "id": "ses_01JA8YQ7C5W2B8N4K6TXMZ3RFP",
    "started_at": "2026-10-15T09:32:04.112Z",
    "seq": 14,
    "page_views": 0,
    "device": { "type": "desktop", "os": "macOS 15.1", "browser": "Chrome 130" },
    "geo_hint": "DE"
  },
  "events": [
    {
      "type": "metric",
      "name": "web.lcp",
      "ts": "2026-10-15T09:41:22.051Z",
      "value": 1184.6,
      "unit": "ms",
      "attrs": { "route": "/catalog/:slug", "element": "img.hero", "connection": "4g" }
    },
    {
      "type": "metric",
      "name": "web.inp",
      "ts": "2026-10-15T09:41:24.907Z",
      "value": 96,
      "unit": "ms",
      "attrs": { "route": "/catalog/:slug", "interaction": "click", "target": "button.add-to-cart" }
    },
    {
      "type": "span",
      "name": "POST /api/cart/items",
      "ts": "2026-10-15T09:41:25.002Z",
      "duration_ms": 212.4,
      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
      "span_id": "00f067aa0ba902b7",
      "status": "ok",
      "attrs": { "http.status_code": 201, "http.response_size": 1840 }
    }
  ],
  "integrity": {
    "alg": "sha256",
    "canonicalization": "jcs",
    "events_count": 3,
    "events_hash": "8c1f0e6b42d7a95e3f60c2b18d4a7e19f53b0c86d2e17a4f9b3c05e81d6a2f74",
    "prev_batch_hash": "e3b4c2a17f9d05864b1ac7e02d93f58a6c41b70e2d895fa3c16e07b24d9a8c51"
  }
}

import { ulid } from 'ulid';

const TIMEOUT_MS = 30 * 60 * 1000;

let session = { id: `ses_${ulid()}`, startedAt: Date.now(), lastActive: Date.now(), seq: 0 };

export function currentSession() {
  const now = Date.now();
  if (now - session.lastActive > TIMEOUT_MS) {
    session = { id: `ses_${ulid()}`, startedAt: now, lastActive: now, seq: 0 };
  }
  session.lastActive = now;
  return session;
}

export function nextSeq() {
  return currentSession().seq++;
}

// Подпись и отправка пакета (браузер или Node.js 18+, Web Crypto API)
import canonicalize from 'canonicalize'; // RFC 8785

const enc = new TextEncoder();
const hex = (buf) => [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, '0')).join('');

async function sha256Hex(text) {
  return hex(await crypto.subtle.digest('SHA-256', enc.encode(text)));
}

async function hmacHex(keyHex, message) {
  const raw = Uint8Array.from(keyHex.match(/../g), (h) => parseInt(h, 16));
  const key = await crypto.subtle.importKey('raw', raw, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
  return hex(await crypto.subtle.sign('HMAC', key, enc.encode(message)));
}

export async function sendBatch({ batch, signingKey, publishableKey, prevHash }) {
  const eventsHash = await sha256Hex(canonicalize(batch.events));
  batch.integrity = {
    alg: 'sha256',
    canonicalization: 'jcs',
    events_count: batch.events.length,
    events_hash: eventsHash,
    prev_batch_hash: prevHash ?? '0'.repeat(64),
  };

  const t = Math.floor(Date.now() / 1000);
  const signature = await hmacHex(signingKey, `${t}.${batch.batch_id}.${batch.session.id}.${eventsHash}`);

  const res = await fetch('https://in.tracklane.space/v1/ingest', {
    method: 'POST',
    keepalive: true,
    headers: {
      Authorization: `Bearer ${publishableKey}`,
      'Content-Type': 'application/json',
      'X-TL-Session': batch.session.id,
      'X-TL-Signature': `t=${t},v1=${signature}`,
    },
    body: JSON.stringify(batch),
  });

  if (res.status === 202) return eventsHash;          // станет prev_batch_hash следующего пакета
  if (res.status === 409) return eventsHash;          // дубликат — пакет уже принят ранее
  throw Object.assign(new Error(`ingest failed: ${res.status}`), { retryAfter: res.headers.get('Retry-After') });
}

# pip install tracklane-python httpx rfc8785
import hashlib, hmac, json, time

import httpx
import rfc8785

INGEST_URL = "https://in.tracklane.space/v1/ingest"


def send_batch(batch: dict, secret_key: str, signing_key_hex: str, prev_hash: str | None) -> str:
    events_hash = hashlib.sha256(rfc8785.dumps(batch["events"])).hexdigest()
    batch["integrity"] = {
        "alg": "sha256",
        "canonicalization": "jcs",
        "events_count": len(batch["events"]),
        "events_hash": events_hash,
        "prev_batch_hash": prev_hash or "0" * 64,
    }

    t = int(time.time())
    message = f"{t}.{batch['batch_id']}.{batch['session']['id']}.{events_hash}".encode()
    signature = hmac.new(bytes.fromhex(signing_key_hex), message, hashlib.sha256).hexdigest()

    resp = httpx.post(
        INGEST_URL,
        content=json.dumps(batch, separators=(",", ":")),
        headers={
            "Authorization": f"Bearer {secret_key}",
            "Content-Type": "application/json",
            "X-TL-Session": batch["session"]["id"],
            "X-TL-Signature": f"t={t},v1={signature}",
        },
        timeout=5.0,
    )
    if resp.status_code in (202, 409):
        return events_hash
    resp.raise_for_status()
    return events_hash

package telemetry

import (
	"bytes"
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"net/http"
	"time"

	"github.com/gowebpki/jcs"
)

func SignAndSend(client *http.Client, body []byte, events []byte, batchID, sessionID, apiKey string, signingKey []byte) error {
	canonical, err := jcs.Transform(events) // RFC 8785
	if err != nil {
		return fmt.Errorf("canonicalize events: %w", err)
	}
	sum := sha256.Sum256(canonical)
	eventsHash := hex.EncodeToString(sum[:])

	t := time.Now().Unix()
	mac := hmac.New(sha256.New, signingKey)
	fmt.Fprintf(mac, "%d.%s.%s.%s", t, batchID, sessionID, eventsHash)

	req, _ := http.NewRequest(http.MethodPost, "https://in.tracklane.space/v1/ingest", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-TL-Session", sessionID)
	req.Header.Set("X-TL-Signature", fmt.Sprintf("t=%d,v1=%s", t, hex.EncodeToString(mac.Sum(nil))))

	resp, err := client.Do(req)
	if err != nil {
		return err
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusAccepted && resp.StatusCode != http.StatusConflict {
		return fmt.Errorf("ingest: unexpected status %d", resp.StatusCode)
	}
	return nil
}

# Подпись вычислена заранее; тело сжато zstd
curl -X POST https://in.tracklane.space/v1/ingest \
  -H "Authorization: Bearer $TRACKLANE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Content-Encoding: zstd" \
  -H "X-TL-Session: ses_01JA8YQ7C5W2B8N4K6TXMZ3RFP" \
  -H "X-TL-Signature: t=1760521287,v1=5d41c2f8a0b3e967d18c4f02ab7e95c36d0f1a8b2e4c7d93f6a05b18c2e9d740" \
  --data-binary @batch.json.zst

{
  "status": "accepted",
  "batch_id": "bat_01JA8ZK4T3M9Q2XW7RVN5HCD6E",
  "events_accepted": 3,
  "events_rejected": 0,
  "edge": "fra1-07",
  "received_at": "2026-10-15T09:41:27.402Z",
  "chain": { "expected_seq": 15, "gap_detected": false }
}