SDKs serveur : démarrage rapide

Tout ce qui suit utilise votre write key secrète (paramètres du projet → API keys). Gardez-la dans une variable d’environnement ; elle ne doit jamais atteindre un navigateur.

Installation

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

# Pas d'installation — l'API HTTP est documentée sur /api/capture

Premier événement

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

Les événements sont mis en file en mémoire et envoyés par lots. Appelez close() à l’arrêt du processus (en PHP, Laravel, FPM et les shutdown hooks s’en chargent ; en Go utilisez defer client.Close()) ; ce qui reste en file au-delà d’un délai de 10 secondes est abandonné plutôt que de bloquer votre processus.

Identify

identify fait un upsert des traits de la personne. Le distinct_id est explicite à chaque appel — les SDKs serveur ne gardent aucun état d’identité.

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 est un événement $identify dont les traits voyagent dans 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"
    }]
  }'

Signez des jetons d’identité

La vérification d’identité exige que votre backend signe un JWT de courte durée pour l’utilisateur connecté. IdentitySigner le fait sans bibliothèque JWT — et votre endpoint tient en trois lignes. Ne signez jamais qu’un id que votre backend a authentifié : signer un user id tiré de l’input de la requête permet à n’importe qui de se faire passer pour n’importe qui, avec en prime le sceau « vérifié ».

PHP

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

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

Vous utilisez Laravel ? kilden/laravel fournit une route POST /kilden/identity publiable derrière votre middleware d’auth, et @kildenScript dans votre layout Blade rend le SDK web déjà branché dessus — aucun code d’intégration à écrire :

routes/web.php

Kilden\Laravel\KildenRoutes::identity();

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

La directive lit KILDEN_PUBLIC_WRITE_KEY (la clé publique wk_ — la secrète n’atteint jamais une vue) et résout la route d’identité par nom (kilden.identity) : un chemin personnalisé comme KildenRoutes::identity('/api/kilden-token') est pris en compte automatiquement. Elle appelle aussi kilden.identify() pour l’utilisateur connecté.

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

# Pas de raccourci curl pour signer — le jeton est un JWT HS256 que votre
# backend doit produire. Utilisez un SDK serveur, ou consultez le guide de
# vérification d'identité pour l'ensemble exact des claims et la forme
# canonique.

Le plugin WordPress expose la même chose sur /wp-json/kilden/v1/identity, cache-safe par construction.

Feature flags

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

Évalués par Kilden côté serveur, mis en cache in-process 30 secondes par distinct_id, une tentative avec un timeout strict, puis votre default. La sémantique complète est dans le guide des feature flags.

Et ensuite

• Vérification d’identité — le modèle de confiance auquel ces jetons se branchent.
• API HTTP : capture — le format de wire sous-jacent.
• Le dépôt de la spec — les contrats contre lesquels les cinq SDKs sont testés.