CitationLab-pakken til Umbraco

Krav

Tjek dette, før du installerer.

• Umbraco 13 LTS på .NET 8

  Det er den version, pakken er bygget til.

• Umbraco 14 og nyere: ikke endnu

  Umbraco 14 ændrede, hvordan udvidelser til backoffice bygges, så dashboardet skal skrives om, før pakken understøtter det. API-delen påvirkes ikke af den ændring.

• Udgående HTTPS

  Webserveren skal kunne nå manager.citationlab.ai over HTTPS, ellers mislykkes forbindelsen.

• En administrator

  Forbindelse og funktionskontakter ligger i et dashboard, som kun brugere i Umbracos admin-gruppe kan se.

1. Installer

Føj pakken til det projekt, der kører jeres Umbraco-website.

1. 1

   Tilføj pakken

   Kør dotnet add package CitationLab.Umbraco fra mappen med jeres Umbraco-webprojekt.

2. 2

   Byg igen

   Byg løsningen, som I plejer, og udrul den.

3. 3

   Genstart websitet

   Ved opstart opretter pakken sine egne databasetabeller. Intet indhold og ingen skabeloner bliver rørt.

Valgfri konfiguration

Konfiguration er kun nødvendig, hvis pakken skal tale med en anden Manager, for eksempel et testmiljø. Uden den bruger pakken manager.citationlab.ai.

{
  "CitationLab": {
    "ManagerUrl": "https://manager.citationlab.ai"
  }
}

Fejl fra pakken skrives til den almindelige Umbraco-log med præfikset [citationlab], så du kan filtrere på dem.

2. Forbind med AI Marketing Manager

Forbindelsen giver websitet en permanent API-nøgle og fortæller Manager, hvor websitet ligger. Du skal bruge et token fra Manager og ét klik i Umbracos backoffice.

1. 1

   Opret et forbindelsestoken i Manager

   Åbn projektet i AI Marketing Manager, gå til Integrations → Umbraco → Connect, og vælg “Generate pairing token”.

2. 2

   Åbn CitationLab-dashboardet

   Log ind i Umbracos backoffice som administrator, åbn sektionen Content, og vælg dashboardet “CitationLab”.

3. 3

   Indsæt tokenet, og klik på “Pair”

   Websitet sender tokenet, sin egen URL og grundlæggende oplysninger om websitet til Manager og får sin API-nøgle tilbage. Dashboardet viser derefter websitet som forbundet.

• Et token virker én gang og udløber efter 15 minutter. Opret et nyt, hvis det når at udløbe.
• Forbind fra backoffice på det offentlige værtsnavn. Manager gemmer den adresse, du var på, da du klikkede på Pair, så en forbindelse fra localhost eller et internt navn giver Manager en adresse, den ikke kan bruge.
• Forbindelsen kræver login i backoffice med vilje: den afgør, hvem der må læse og skrive hele websitet, så det er ikke nok at kende websitets URL.
• Ét Umbraco-website pr. projekt. Forbinder du et projekt, der allerede har en forbindelse, erstattes URL og nøgle i den forbindelse.
• Afbryd med “Disconnect” i dashboardet, som fjerner den nøgle, der er gemt på websitet, eller fjern forbindelsen i Manager, som sletter forbindelsen og Managers cachede kopi af indholdet. At fjerne den i Manager ændrer intet på Umbraco-websitet.

3. Vælg, hvad pakken skal gøre

Installationen ændrer ingen sider på websitet. Kun synkroniseringsgruppen er slået til fra start, så Manager kan læse indholdet. Alt, der ville ændre jeres HTML, håndtere forespørgsler eller indsamle besøgsdata, er slået fra, indtil du slår det til.

Hvor du slår funktioner til og fra

En administrator slår funktioner til og fra under Features i CitationLab-dashboardet. Udviklere kan gøre det samme via API'et med PUT features. Manager læser, hvad der er slået til, via GET capabilities, der rapporterer både, hvad installationen kan, og hvad der er aktiveret. Et kald til en funktion, der er slået fra, svarer 403 med koden feature_disabled.

4. API-reference

Pakken stiller et REST API til rådighed fra jeres eget Umbraco-website. Det er det API, Manager bruger efter forbindelsen, og jeres udviklere kan også bruge det. Det er adskilt fra Managers eget REST API, som er beskrevet under Ressourcer → API.

Basis-URL

Alle ruter ligger under denne sti på websitets eget domæne:

Godkendelse

• Send nøglen fra forbindelsen som bearer-token: Authorization: Bearer cl_um_… Nøglen er cl_um_ efterfulgt af 40 hexadecimale tegn.
• GET health er åben og kræver ingen nøgle.
• Forbindelsesruterne (pair, pairing-status, disconnect) accepterer ikke nøglen. De kræver en logget ind backoffice-session.

Konventioner

• Forespørgselsparametre skrives i snake_case: per_page, document_type_alias, parent_id, order_by, include_properties.
• Forespørgsels- og svarkroppe er JSON i camelCase.
• Lister pagineres og returnerer items, total, page, perPage og totalPages. per_page er 100 som standard og højst 500.
• Læsning og skrivning af indhold tager en valgfri culture-parameter. Ét sprog kan udgives alene med POST content/{id}/translations/{culture}/publish.
• En nodes {id} er dens GUID-nøgle eller dens numeriske id.

Fejl

Alle fejl har samme form: error er en læsbar besked, code er en af værdierne nedenfor, og details er med, når der er mere at sige.

HTTP/1.1 403 Forbidden

{
  "error": "Feature 'redirects' is disabled on this site",
  "code": "feature_disabled",
  "details": { "feature": "redirects" }
}

Endpoints

De vigtigste ruter i hver gruppe, relativt til basis-URL'en. Hver gruppe nævner også flere ressourcer, den indeholder.

Umbraco Forms og Umbraco Commerce læses gennem en bro, der leder efter dem, mens websitet kører, så pakken kan installeres og køre på websites uden de licenser. Ruterne svarer da med unsupported.

Filer, der leveres fra websitets rod

Med de tilhørende kontakter for sideoutput slået til svarer pakken også på disse adresser på jeres domæne:

/robots.txt/sitemap.xml/llms.txt/llms-full.txt/ai.json/.well-known/ai.json/ai-info

Eksempler

curl https://your-site.example/umbraco/citationlab/v1/capabilities \
  -H "Authorization: Bearer cl_um_YOUR_API_KEY"

curl "https://your-site.example/umbraco/citationlab/v1/content?page=2&per_page=50&status=published&culture=en-US" \
  -H "Authorization: Bearer cl_um_YOUR_API_KEY"

{
  "items": [ … ],
  "total": 412,
  "page": 2,
  "perPage": 50,
  "totalPages": 9
}

curl -X PUT "https://your-site.example/umbraco/citationlab/v1/seo-meta/NODE_KEY?culture=en-US" \
  -H "Authorization: Bearer cl_um_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Plumbing services in Oslo",
    "description": "Emergency and planned plumbing, 24/7.",
    "canonical": "https://your-site.example/services/plumbing/",
    "noindex": false
  }'

5. Webhooks

Pakken kan sende en signeret besked til et HTTPS-endpoint, I vælger, når indhold eller medier ændres: jeres egen tjeneste eller et automatiseringsværktøj som Zapier, Make eller n8n.

1. 1

   Slå kontakten webhooks til

   Funktionen webhooks er slået fra som standard.

2. 2

   Angiv modtageren

   PUT settings/webhook med url (http eller https) og secret. GET settings/webhook viser url og hasSecret, aldrig selve hemmeligheden.

3. 3

   Send en test

   POST settings/webhook/test leverer en signeret testhændelse, så du kan tjekke modtageren før en rigtig ændring.

Intet sendes, før kontakten er slået til, og både url og secret er angivet. Forbindelsen til Manager peger allerede webhooken mod CitationLab Manager med sin egen hemmelighed, så det er nok at slå kontakten til, for at Manager ser en publiceret ændring inden for få sekunder. Opsætter I jeres egen modtager, lader Manager den være.

curl -X PUT https://your-site.example/umbraco/citationlab/v1/settings/webhook \
  -H "Authorization: Bearer cl_um_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://hooks.example.com/umbraco", "secret": "a-long-random-string" }'

Hændelser

Sådan ser en levering ud

En JSON-POST med event, siteUrl, timestamp (Unix-sekunder) og data. Felter, der er null, udelades. X-CL-Event gentager hændelsens navn, og X-CL-Signature bærer signaturen.

POST /umbraco HTTP/1.1
Host: hooks.example.com
Content-Type: application/json; charset=utf-8
X-CL-Event: content.published
X-CL-Signature: 3f1c…e9a0

{
  "event": "content.published",
  "siteUrl": "https://your-site.example",
  "timestamp": 1760000000,
  "data": { "id": "NODE_KEY", … }
}

Verificér signaturen

X-CL-Signature er HMAC-SHA256 af den nøjagtige, rå forespørgselskrop med jeres hemmelighed som nøgle, som hexadecimal med små bogstaver. Beregn den over de rå bytes, før du parser JSON'en, og sammenlign med en funktion, der bruger konstant tid. Serialiserer du den parsede krop igen, ændres bytene, og tjekket fejler.

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.CL_WEBHOOK_SECRET;

// Keep the raw bytes: the signature covers the body exactly as sent.
app.post("/umbraco", express.raw({ type: "application/json" }), (req, res) => {
  const expected = crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const received = req.get("X-CL-Signature") ?? "";

  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.sendStatus(401);

  const payload = JSON.parse(req.body.toString("utf8"));
  console.log(req.get("X-CL-Event"), payload.data);
  res.sendStatus(204);
});

using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

app.MapPost("/umbraco", async (HttpRequest request, IConfiguration config) =>
{
    // Keep the raw bytes: the signature covers the body exactly as sent.
    using var buffer = new MemoryStream();
    await request.Body.CopyToAsync(buffer);
    var body = buffer.ToArray();

    var key = Encoding.UTF8.GetBytes(config["CitationLab:WebhookSecret"]!);
    var expected = Convert.ToHexString(HMACSHA256.HashData(key, body)).ToLowerInvariant();
    var received = request.Headers["X-CL-Signature"].ToString();

    if (!CryptographicOperations.FixedTimeEquals(
            Encoding.ASCII.GetBytes(expected), Encoding.ASCII.GetBytes(received)))
        return Results.Unauthorized();

    using var payload = JsonDocument.Parse(body);
    return Results.NoContent();
});

Levering og nye forsøg

• Leveringer sættes i kø og sendes uden for gemningen. At gemme i backoffice venter aldrig på jeres modtager.
• Alle statuskoder under 400 regnes som leveret.
• Efter netværksfejl, timeout, 5xx, 408 eller 429 prøver pakken to gange mere: efter 1 sekund og efter 3 sekunder. Andre 4xx-svar prøves ikke igen.
• Når alle tre forsøg mislykkes, giver pakken op og skriver en [citationlab]-advarsel i Umbraco-loggen. Brug hændelsen som et signal til at hente den aktuelle tilstand fra API'et, ikke som den eneste kopi af ændringen.

Sikkerhed og privatliv

• Forbindelse kræver login i backoffice

  Kun en administrator, der er logget ind i jeres backoffice, kan forbinde et website. En URL alene forbinder intet.

• Hvor nøglen ligger

  På websitet gemmes nøglen i App_Data/CitationLab/apikey.json. Behandl filen som en adgangskode, og hold App_Data uden for versionsstyringen. Manager gemmer sin kopi krypteret.

• Slået fra, til du slår det til

  Kun læsning er slået til efter installation. Sideoutput, forespørgsler, besøgsdata og integrationer kræver hver deres bevidste kontakt.

• Ingen rå IP-adresser

  Når sporing er slået til, gemmer pakken aldrig en besøgendes rå IP-adresse.

• Hver ændring logges

  Pakken har sin egen revisionslog over hver ændring, der foretages gennem den, med den tidligere værdi, og en ændring kan rulles tilbage. Ændringer fra Manager logges også i Manager.

• Hemmeligheder bliver, hvor de er

  Webhook-hemmeligheden kan kun skrives via API'et: læsninger returnerer hasSecret, aldrig værdien.

Fejlfinding

Ofte stillede spørgsmål