CitationLab-pakken for Umbraco

Krav

Sjekk dette før du installerer.

• Umbraco 13 LTS på .NET 8

  Dette er versjonen pakken er laget for.

• Umbraco 14 og nyere: ikke ennå

  Umbraco 14 endret hvordan utvidelser i backoffice bygges, så dashbordet må skrives om før pakken støtter det. API-delen påvirkes ikke av den endringen.

• Utgående HTTPS

  Webserveren må nå manager.citationlab.ai over HTTPS, ellers feiler tilkoblingen.

• En administrator

  Tilkobling og funksjonsbrytere ligger i et dashbord som bare brukere i Umbracos admin-gruppe ser.

1. Installer

Legg pakken til i prosjektet som kjører Umbraco-nettstedet.

1. 1

   Legg til pakken

   Kjør dotnet add package CitationLab.Umbraco fra mappen til Umbraco-webprosjektet.

2. 2

   Bygg på nytt

   Bygg løsningen slik dere pleier, og deploy den.

3. 3

   Start nettstedet på nytt

   Ved oppstart lager pakken sine egne databasetabeller. Verken innhold eller maler blir rørt.

Valgfri konfigurasjon

Konfigurasjon trengs bare hvis pakken skal snakke med en annen Manager, for eksempel et testmiljø. Uten den bruker pakken manager.citationlab.ai.

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

Feil fra pakken skrives til den vanlige Umbraco-loggen med prefikset [citationlab], så du kan filtrere på dem.

2. Koble til AI Marketing Manager

Tilkoblingen gir nettstedet en permanent API-nøkkel og forteller Manager hvor nettstedet ligger. Du trenger et token fra Manager og ett klikk i Umbraco-backoffice.

1. 1

   Lag et tilkoblingstoken i Manager

   Åpne prosjektet i AI Marketing Manager, gå til Integrations → Umbraco → Connect og velg “Generate pairing token”.

2. 2

   Åpne CitationLab-dashbordet

   Logg inn i Umbraco-backoffice som administrator, åpne Content-seksjonen og velg dashbordet “CitationLab”.

3. 3

   Lim inn tokenet og klikk “Pair”

   Nettstedet sender tokenet, sin egen URL og grunnleggende informasjon om nettstedet til Manager, og får API-nøkkelen tilbake. Dashbordet viser deretter nettstedet som tilkoblet.

• Et token kan brukes én gang og utløper etter 15 minutter. Lag et nytt hvis det går ut.
• Koble til fra backoffice på det offentlige vertsnavnet. Manager lagrer adressen du sto på da du klikket Pair, så en tilkobling fra localhost eller et internt navn gir Manager en adresse den ikke kan bruke.
• Tilkoblingen krever innlogging i backoffice med vilje: den avgjør hvem som kan lese og skrive hele nettstedet, så det holder ikke å kjenne nettstedets URL.
• Ett Umbraco-nettsted per prosjekt. Kobler du til et prosjekt som allerede har en kobling, erstattes URL og nøkkel i den koblingen.
• For å koble fra bruker du “Disconnect” i dashbordet, som fjerner nøkkelen som er lagret på nettstedet, eller du fjerner koblingen i Manager, som sletter koblingen og Managers mellomlagrede kopi av innholdet. Å fjerne den i Manager endrer ingenting på Umbraco-nettstedet.

3. Velg hva pakken skal gjøre

Installasjonen endrer ingen sider på nettstedet. Bare synkroniseringsgruppen er på fra start, slik at Manager kan lese innholdet. Alt som ville endret HTML-en, håndtert forespørsler eller samlet inn besøksdata, er av til du slår det på.

Hvor du slår funksjoner av og på

En administrator slår funksjoner av og på under Features i CitationLab-dashbordet. Utviklere kan gjøre det samme gjennom API-et med PUT features. Manager leser hva som er slått på via GET capabilities, som rapporterer både hva installasjonen kan og hva som er aktivert. Et kall til en funksjon som er av, svarer 403 med koden feature_disabled.

4. API-referanse

Pakken leverer et REST API fra deres eget Umbraco-nettsted. Det er dette API-et Manager bruker etter tilkoblingen, og utviklerne deres kan bruke det også. Det er noe annet enn Managers eget REST API, som er beskrevet under Ressurser → API.

Base-URL

Alle ruter ligger under denne stien på nettstedets eget domene:

Autentisering

• Send nøkkelen fra tilkoblingen som bearer-token: Authorization: Bearer cl_um_… Nøkkelen er cl_um_ fulgt av 40 heksadesimale tegn.
• GET health er åpen og krever ingen nøkkel.
• Tilkoblingsrutene (pair, pairing-status, disconnect) godtar ikke nøkkelen. De krever en innlogget backoffice-økt.

Konvensjoner

• Spørreparametere skrives i snake_case: per_page, document_type_alias, parent_id, order_by, include_properties.
• Forespørsels- og svarkropper er JSON i camelCase.
• Lister pagineres og returnerer items, total, page, perPage og totalPages. per_page er 100 som standard og maks 500.
• Lesing og skriving av innhold tar en valgfri culture-parameter. Ett språk kan publiseres alene med POST content/{id}/translations/{culture}/publish.
• En nodes {id} er GUID-nøkkelen eller den numeriske id-en.

Feil

Alle feil har samme form: error er en lesbar melding, code er en av verdiene under, og details er med når det er mer å si.

HTTP/1.1 403 Forbidden

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

Endepunkter

Hovedrutene i hver gruppe, relativt til base-URL-en. Hver gruppe lister også flere ressurser den inneholder.

Umbraco Forms og Umbraco Commerce leses gjennom en bro som ser etter dem mens nettstedet kjører, så pakken kan installeres og kjøre på nettsteder uten de lisensene. Rutene svarer da med unsupported.

Filer som leveres fra roten av nettstedet

Med de tilhørende sideutdata-bryterne på svarer pakken også på disse adressene på domenet:

/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 et signert varsel til et HTTPS-endepunkt dere velger når innhold eller media endres: deres egen tjeneste, eller et automasjonsverktøy som Zapier, Make eller n8n.

1. 1

   Slå på webhooks-bryteren

   Funksjonen webhooks er av som standard.

2. 2

   Sett mottakeren

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

3. 3

   Send en test

   POST settings/webhook/test sender en signert testhendelse, så du kan sjekke mottakeren før en ekte endring.

Ingenting sendes før bryteren er på og både url og secret er satt. Tilkoblingen til Manager peker allerede webhooken mot CitationLab Manager med en egen hemmelighet, så det holder å slå på bryteren for at Manager skal se en publisert endring i løpet av sekunder. Setter dere opp en egen mottaker, lar 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" }'

Hendelser

Slik ser en levering ut

En JSON-POST med event, siteUrl, timestamp (Unix-sekunder) og data. Felt som er null, utelates. X-CL-Event gjentar hendelsesnavnet, og X-CL-Signature inneholder 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", … }
}

Verifiser signaturen

X-CL-Signature er HMAC-SHA256 av den nøyaktige, rå forespørselskroppen med hemmeligheten som nøkkel, som heksadesimal med små bokstaver. Regn den ut over de rå bytene før du parser JSON-en, og sammenlign med en funksjon som bruker konstant tid. Serialiserer du den parsede kroppen på nytt, endres bytene og sjekken feiler.

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øk

• Leveringer legges i kø og sendes utenom lagringen. Lagring i backoffice venter aldri på mottakeren.
• Alle statuskoder under 400 regnes som levert.
• Etter nettverksfeil, tidsavbrudd, 5xx, 408 eller 429 prøver pakken to ganger til: etter 1 sekund og etter 3 sekunder. Andre 4xx-svar prøves ikke på nytt.
• Når alle tre forsøkene feiler, gir pakken opp og skriver en [citationlab]-advarsel i Umbraco-loggen. Bruk hendelsen som et signal om å hente gjeldende tilstand fra API-et, ikke som den eneste kopien av endringen.

Sikkerhet og personvern

• Tilkobling krever backoffice-innlogging

  Bare en administrator som er logget inn i backoffice, kan koble til et nettsted. En URL alene kobler ingenting.

• Hvor nøkkelen ligger

  På nettstedet lagres nøkkelen i App_Data/CitationLab/apikey.json. Behandle filen som et passord, og hold App_Data utenfor kildekontrollen. Manager lagrer sin kopi kryptert.

• Av til du slår på

  Bare lesing er på etter installasjon. Sideutdata, forespørsler, besøksdata og integrasjoner krever hver sin bevisste bryter.

• Ingen rå IP-adresser

  Når sporing er på, lagrer pakken aldri besøkendes rå IP-adresse.

• Hver endring logges

  Pakken har sin egen revisjonslogg over hver endring som går gjennom den, med forrige verdi, og en endring kan rulles tilbake. Endringer fra Manager logges i Manager også.

• Hemmeligheter blir der de er

  Webhook-hemmeligheten kan bare skrives via API-et: lesing returnerer hasSecret, aldri verdien.

Feilsøking

Vanlige spørsmål