SDKs de servidor: quickstart

Tudo abaixo usa a sua write key secreta (configurações do projeto → API keys). Mantenha-a numa variável de ambiente; ela nunca deve chegar a um browser.

Instalação

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

# Sem instalação — a API HTTP está documentada em /api/capture

Primeiro 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"
    }]
  }'

Os eventos entram numa fila em memória e são enviados em lotes. Chame close() quando o seu processo desligar (em PHP, Laravel, FPM e os shutdown hooks cuidam disso; em Go use defer client.Close()); o que continuar na fila após um prazo de 10 segundos é descartado em vez de travar o processo.

Identify

identify faz upsert dos traits da pessoa. O distinct_id é explícito em cada chamada — os SDKs de servidor não guardam estado de identidade.

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 é um evento $identify cujos traits viajam em 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"
    }]
  }'

Assine tokens de identidade

A verificação de identidade precisa que o seu backend assine um JWT de vida curta para o usuário logado. O IdentitySigner faz isso sem biblioteca de JWT — e o seu endpoint são três linhas. Assine somente um id que o seu backend autenticou: assinar um user id vindo do input da request permite que qualquer um se passe por qualquer outro, ainda por cima com selo de “verificado”.

PHP

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

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

Usa Laravel? O kilden/laravel traz uma rota POST /kilden/identity publicável atrás do seu middleware de auth — sem escrever código.

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}))

curl

# Não há atalho curl para assinar — o token é um JWT HS256 que o seu backend
# deve produzir. Use um SDK de servidor, ou veja o guia de verificação de
# identidade para o conjunto exato de claims e a forma canônica.

O plugin de WordPress expõe o mesmo em /wp-json/kilden/v1/identity, cache-safe por construção.

Feature flags

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

Avaliados pela Kilden server-side, com cache in-process de 30 segundos por distinct_id, uma tentativa com timeout duro e depois o seu default. A semântica completa está no guia de feature flags.

Para onde ir agora

• Verificação de identidade — o modelo de confiança ao qual estes tokens se conectam.
• API HTTP: capture — o formato de wire por baixo.
• O repositório da spec — os contratos contra os quais os cinco SDKs são testados.