SDKs de servidor: quickstart

Todo lo de abajo usa tu write key secreta (configuración del proyecto → API keys). Guárdala en una variable de entorno; jamás debe llegar a un browser.

Instalación

PHP

composer require kilden/kilden-php

Node.js

npm install @kilden-io/node

Python

pip install kilden

Ruby

gem install kilden --pre

Go

go get go.kilden.io/sdk

curl

# Sin instalación — la API HTTP está documentada en /api/capture

Primer evento

PHP

$kilden = new Kilden\Client(getenv('KILDEN_SECRET_KEY'));

$kilden->track('user_42', 'order_completed', [
    'revenue' => 99.9,
    'currency' => 'CLP',
]);

Node.js

import { Client } from "@kilden-io/node";

const kilden = new Client(process.env.KILDEN_SECRET_KEY!);

kilden.track("user_42", "order_completed", { revenue: 99.9, currency: "CLP" });

Python

from kilden import Client

kilden = Client(os.environ["KILDEN_SECRET_KEY"])
kilden.track("user_42", "order_completed", {"revenue": 99.9, "currency": "CLP"})

Ruby

require "kilden"

kilden = Kilden::Client.new(ENV["KILDEN_SECRET_KEY"])
kilden.track("user_42", "order_completed", { "revenue" => 99.9, "currency" => "CLP" })

Go

client, err := kilden.New(os.Getenv("KILDEN_SECRET_KEY"))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

client.Track("user_42", "order_completed", map[string]any{
  "revenue": 99.9, "currency": "CLP",
})

curl

curl -X POST https://ingest.kilden.io/capture \
  -H 'Content-Type: application/json' \
  -d '{
    "write_key": "'$KILDEN_SECRET_KEY'",
    "sent_at": "2026-07-14T12:00:00.500Z",
    "batch": [{
      "uuid": "0197fa10-7a2b-7c3d-8e4f-5a6b7c8d9e0f",
      "event": "order_completed",
      "distinct_id": "user_42",
      "properties": {"revenue": 99.9, "currency": "CLP"},
      "timestamp": "2026-07-14T12:00:00.000Z"
    }]
  }'

Los eventos se encolan en memoria y se envían en batches. Llama a close() cuando tu proceso se apaga (en PHP lo cubren Laravel, FPM y los shutdown hooks; en Go usa defer client.Close()); lo que siga encolado pasado un deadline de 10 segundos se descarta en lugar de colgar tu proceso.

Identify

identify hace upsert de los traits de la persona. El distinct_id es explícito en cada llamada — los SDKs de servidor no guardan estado de identidad.

PHP

$kilden->identify('user_42', ['plan' => 'pro', 'email' => '[email protected]']);

Node.js

kilden.identify("user_42", { plan: "pro", email: "[email protected]" });

Python

kilden.identify("user_42", {"plan": "pro", "email": "[email protected]"})

Ruby

kilden.identify("user_42", { "plan" => "pro", "email" => "[email protected]" })

Go

client.Identify("user_42", map[string]any{"plan": "pro", "email": "[email protected]"})

curl

# identify es un evento $identify cuyos traits viajan en properties.$set
curl -X POST https://ingest.kilden.io/capture \
  -H 'Content-Type: application/json' \
  -d '{
    "write_key": "'$KILDEN_SECRET_KEY'",
    "sent_at": "2026-07-14T12:00:00.500Z",
    "batch": [{
      "uuid": "0197fa10-7a2b-7c3d-8e4f-5a6b7c8d9e10",
      "event": "$identify",
      "distinct_id": "user_42",
      "properties": {"$set": {"plan": "pro", "email": "[email protected]"}},
      "timestamp": "2026-07-14T12:00:00.000Z"
    }]
  }'

Firma tokens de identidad

La verificación de identidad necesita que tu backend firme un JWT de vida corta para el usuario logueado. IdentitySigner lo hace sin librería de JWT — y tu endpoint son tres líneas. Firma únicamente un id que tu backend haya autenticado: firmar un user id tomado del input del request permite que cualquiera se haga pasar por cualquiera, y encima con sello de “verificado”.

PHP

$signer = new Kilden\IdentitySigner(getenv('KILDEN_IDENTITY_SECRET'), ['kid' => 'k1']);

$token = $signer->sign($user->id, [
    'traits' => ['plan' => $user->plan],
]);

¿Usas Laravel? kilden/laravel trae una ruta POST /kilden/identity publicable detrás de tu middleware de auth, y @kildenScript en tu layout de Blade renderiza el SDK web ya conectado a ella — sin escribir código de integración:

routes/web.php

Kilden\Laravel\KildenRoutes::identity();

{{-- resources/views/layouts/app.blade.php --}}
<head>
    @kildenScript
</head>

La directiva lee KILDEN_PUBLIC_WRITE_KEY (la key pública wk_ — la secreta jamás llega a una vista) y resuelve la ruta de identidad por nombre (kilden.identity), así que un path custom como KildenRoutes::identity('/api/kilden-token') se toma automáticamente. También llama kilden.identify() para el usuario logueado.

Node.js

import { IdentitySigner } from "@kilden-io/node";

const signer = new IdentitySigner(process.env.KILDEN_IDENTITY_SECRET!, { kid: "k1" });

app.post("/kilden/identity", (req, res) => {
  const user = req.user;
  res.json({
    distinct_id: String(user.id),
    token: signer.sign(String(user.id), { traits: { plan: user.plan } }),
  });
});

Python

from kilden import IdentitySigner

signer = IdentitySigner(os.environ["KILDEN_IDENTITY_SECRET"], kid="k1")

@app.route("/kilden/identity", methods=["POST"])
@login_required
def kilden_identity():
    token = signer.sign(current_user.id, traits={"plan": current_user.plan})
    return {"distinct_id": current_user.id, "token": token}

Ruby

signer = Kilden::IdentitySigner.new(ENV["KILDEN_IDENTITY_SECRET"], kid: "k1")

token = signer.sign(current_user.id.to_s, traits: { "plan" => current_user.plan })

Go

signer, err := kilden.NewIdentitySigner(os.Getenv("KILDEN_IDENTITY_SECRET"), "k1")
if err != nil {
  log.Fatal(err)
}

token, err := signer.Sign(userID, kilden.WithTraits(map[string]any{"plan": plan}))
if err != nil {
  log.Fatal(err)
}

curl

# No hay atajo curl para firmar — el token es un JWT HS256 que tu backend
# debe producir. Usa un SDK de servidor, o mira la guía de verificación de
# identidad para el set exacto de claims y la forma canónica.

El plugin de WordPress expone lo mismo en /wp-json/kilden/v1/identity, cache-safe por construcción.

Feature flags

isEnabled(flag_key, distinct_id, { person_properties?, default? })
getFeatureFlag(flag_key, distinct_id, { person_properties?, default? })

Los evalúa Kilden server-side, con cache in-process de 30 segundos por distinct_id, un intento con timeout duro y después tu default. La semántica completa está en la guía de feature flags.

Adónde seguir

• Verificación de identidad — el modelo de confianza al que se enchufan estos tokens.
• API HTTP: capture — el formato de wire por debajo.
• El repo del spec — los contratos contra los que se testean los cinco SDKs.