CitationLab-paketet för Umbraco

Krav

Kontrollera det här innan du installerar.

• Umbraco 13 LTS på .NET 8

  Det är den version paketet är byggt för.

• Umbraco 14 och senare: inte än

  Umbraco 14 ändrade hur tillägg till backoffice byggs, så dashboarden måste skrivas om innan paketet stöder det. API-delen påverkas inte av den ändringen.

• Utgående HTTPS

  Webbservern måste nå manager.citationlab.ai över HTTPS, annars misslyckas kopplingen.

• En administratör

  Koppling och funktionsbrytare finns i en dashboard som bara användare i Umbracos admin-grupp ser.

1. Installera

Lägg till paketet i projektet som kör er Umbraco-webbplats.

1. 1

   Lägg till paketet

   Kör dotnet add package CitationLab.Umbraco från mappen för ert Umbraco-webbprojekt.

2. 2

   Bygg om

   Bygg lösningen som ni brukar och driftsätt den.

3. 3

   Starta om webbplatsen

   Vid uppstart skapar paketet sina egna databastabeller. Inget innehåll och inga mallar rörs.

Valfri konfiguration

Konfiguration behövs bara om paketet ska prata med en annan Manager, till exempel en testmiljö. Utan den använder paketet manager.citationlab.ai.

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

Fel från paketet skrivs till den vanliga Umbraco-loggen med prefixet [citationlab], så att du kan filtrera fram dem.

2. Koppla till AI Marketing Manager

Kopplingen ger webbplatsen en permanent API-nyckel och talar om för Manager var webbplatsen finns. Du behöver en token från Manager och ett klick i Umbracos backoffice.

1. 1

   Skapa en kopplingstoken i Manager

   Öppna projektet i AI Marketing Manager, gå till Integrations → Umbraco → Connect och välj “Generate pairing token”.

2. 2

   Öppna CitationLab-dashboarden

   Logga in i Umbracos backoffice som administratör, öppna sektionen Content och välj dashboarden “CitationLab”.

3. 3

   Klistra in token och klicka på “Pair”

   Webbplatsen skickar token, sin egen URL och grundläggande uppgifter om webbplatsen till Manager och får sin API-nyckel tillbaka. Dashboarden visar sedan webbplatsen som kopplad.

• En token fungerar en gång och går ut efter 15 minuter. Skapa en ny om den hinner gå ut.
• Koppla från backoffice på det publika värdnamnet. Manager sparar adressen du var på när du klickade på Pair, så en koppling från localhost eller ett internt namn ger Manager en adress den inte kan använda.
• Kopplingen kräver inloggning i backoffice med avsikt: den avgör vem som får läsa och skriva hela webbplatsen, så det räcker inte att känna till webbplatsens URL.
• En Umbraco-webbplats per projekt. Kopplar du ett projekt som redan har en koppling ersätts URL och nyckel i den kopplingen.
• Koppla bort med “Disconnect” i dashboarden, som tar bort nyckeln som är sparad på webbplatsen, eller ta bort kopplingen i Manager, vilket raderar kopplingen och Managers cachade kopia av innehållet. Att ta bort den i Manager ändrar ingenting på Umbraco-webbplatsen.

3. Välj vad paketet ska göra

Installationen ändrar ingen sida på webbplatsen. Bara synkgruppen är påslagen från början, så att Manager kan läsa innehållet. Allt som skulle ändra er HTML, hantera förfrågningar eller samla in besöksdata är avstängt tills du slår på det.

Var du slår av och på funktioner

En administratör slår av och på funktioner under Features i CitationLab-dashboarden. Utvecklare kan göra samma sak via API:et med PUT features. Manager läser vad som är påslaget via GET capabilities, som rapporterar både vad installationen klarar och vad som är aktiverat. Ett anrop till en avstängd funktion svarar 403 med koden feature_disabled.

4. API-referens

Paketet tillhandahåller ett REST API från er egen Umbraco-webbplats. Det är det API som Manager använder efter kopplingen, och era utvecklare kan också använda det. Det är skilt från Managers eget REST API, som beskrivs under Resurser → API.

Bas-URL

Alla rutter ligger under den här sökvägen på webbplatsens egen domän:

Autentisering

• Skicka nyckeln från kopplingen som bearer-token: Authorization: Bearer cl_um_… Nyckeln är cl_um_ följt av 40 hexadecimala tecken.
• GET health är öppen och kräver ingen nyckel.
• Kopplingsrutterna (pair, pairing-status, disconnect) godtar inte nyckeln. De kräver en inloggad backoffice-session.

Konventioner

• Frågeparametrar skrivs i snake_case: per_page, document_type_alias, parent_id, order_by, include_properties.
• Förfrågnings- och svarskroppar är JSON i camelCase.
• Listor pagineras och returnerar items, total, page, perPage och totalPages. per_page är 100 som standard och högst 500.
• Läsning och skrivning av innehåll tar en valfri culture-parameter. Ett språk kan publiceras ensamt med POST content/{id}/translations/{culture}/publish.
• En nods {id} är dess GUID-nyckel eller dess numeriska id.

Fel

Alla fel har samma form: error är ett läsbart meddelande, code är ett av värdena nedan och details finns med när det finns mer att säga.

HTTP/1.1 403 Forbidden

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

Endpoints

De viktigaste rutterna i varje grupp, relativt bas-URL:en. Varje grupp listar också fler resurser som ingår.

Umbraco Forms och Umbraco Commerce läses via en brygga som letar efter dem medan webbplatsen körs, så paketet kan installeras och köras på webbplatser utan de licenserna. Rutterna svarar då med unsupported.

Filer som levereras från webbplatsens rot

Med motsvarande brytare för sidutdata påslagna svarar paketet också på de här adresserna på er domän:

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

Exempel

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

Paketet kan skicka en signerad avisering till en HTTPS-endpoint ni väljer när innehåll eller media ändras: er egen tjänst eller ett automationsverktyg som Zapier, Make eller n8n.

1. 1

   Slå på brytaren webhooks

   Funktionen webhooks är avstängd som standard.

2. 2

   Ange mottagaren

   PUT settings/webhook med url (http eller https) och secret. GET settings/webhook visar url och hasSecret, aldrig själva hemligheten.

3. 3

   Skicka ett test

   POST settings/webhook/test levererar en signerad testhändelse så att du kan kontrollera mottagaren före en riktig ändring.

Inget skickas förrän brytaren är påslagen och både url och secret är angivna. Kopplingen till Manager pekar redan webhooken mot CitationLab Manager med en egen hemlighet, så det räcker att slå på brytaren för att Manager ska se en publicerad ändring inom några sekunder. Anger ni en egen mottagare låter Manager den vara.

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å ser en leverans ut

En JSON-POST med event, siteUrl, timestamp (Unix-sekunder) och data. Fält som är null utelämnas. X-CL-Event upprepar händelsenamnet och X-CL-Signature bär 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", … }
}

Verifiera signaturen

X-CL-Signature är HMAC-SHA256 av den exakta, råa förfrågningskroppen med er hemlighet som nyckel, som hexadecimal med gemener. Beräkna den över de råa byten innan du tolkar JSON:en och jämför med en funktion som tar konstant tid. Om du serialiserar den tolkade kroppen igen ändras byten och kontrollen misslyckas.

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

Leverans och nya försök

• Leveranser köas och skickas utanför sparningen. Att spara i backoffice väntar aldrig på er mottagare.
• Alla statuskoder under 400 räknas som levererade.
• Efter nätverksfel, timeout, 5xx, 408 eller 429 försöker paketet två gånger till: efter 1 sekund och efter 3 sekunder. Andra 4xx-svar försöks inte igen.
• När alla tre försöken misslyckas ger paketet upp och skriver en [citationlab]-varning i Umbraco-loggen. Använd händelsen som en signal att hämta aktuellt läge från API:et, inte som den enda kopian av ändringen.

Säkerhet och integritet

• Koppling kräver inloggning i backoffice

  Bara en administratör som är inloggad i er backoffice kan koppla en webbplats. En URL ensam kopplar ingenting.

• Var nyckeln finns

  På webbplatsen sparas nyckeln i App_Data/CitationLab/apikey.json. Behandla filen som ett lösenord och håll App_Data utanför versionshanteringen. Manager sparar sin kopia krypterad.

• Avstängt tills du slår på

  Bara läsning är påslagen efter installation. Sidutdata, förfrågningar, besöksdata och integrationer kräver var sin medveten brytare.

• Inga råa IP-adresser

  När spårning är påslagen sparar paketet aldrig en besökares råa IP-adress.

• Varje ändring loggas

  Paketet har en egen granskningslogg över varje ändring som görs via det, med föregående värde, och en ändring kan rullas tillbaka. Ändringar från Manager loggas även i Manager.

• Hemligheter stannar kvar

  Webhook-hemligheten kan bara skrivas via API:et: läsningar returnerar hasSecret, aldrig värdet.

Felsökning

Vanliga frågor