Vefforritarar

Að setja upp Önnu á vefsíðuna þína

Fyrir flestar vefsíður er uppsetningin ein lína, og þá er Anna komin í loftið. Þessi síða byrjar á þeirri línu. Allt sem kemur á eftir, Content-Security-Policy reglurnar, nonce og umgjarðirnar, á aðeins við ef vefsíðan þín keyrir stranga CSP (til dæmis sérsmíðuð Next.js-síða). Markmiðið er að þú getir sett Önnu upp án þess að rýna í þjappaðan loader-kóða, hvort sem síðan þín er einföld eða með stranga öryggisreglu.

Grunnuppsetning

Ein lína. Þú bætir script-tagi við síðuna og setur data-client á kenni viðskiptavinarins. Þú velur ekki stillinguna, heldur ræðst hún af uppsetningu viðskiptavinarins á þjóninum (spjallgluggi, hliðargluggi eða innfellt spjall). Settu tagið nákvæmlega einu sinni á hverja síðu.

HTML
<script
  async
  src="https://widget.corveria.com/v1/loader.js"
  data-client="your-client-slug"
></script>

Búið fyrir flestar síður

Þetta er allt og sumt fyrir flestar vefsíður. Ef síðan þín keyrir enga Content-Security-Policy, sem á við flestar WordPress-, Shopify-, Wix- og venjulegar síður, þá ertu búin. Haltu áfram hér að neðan aðeins ef vefurinn þinn er með stranga CSP-reglu.

Eigindin á script-taginu

data-client
Skylda. Kenni viðskiptavinarins. Vanti það skrifar loaderinn villu í console og gerir ekkert annað.
data-api
Valfrjálst. Yfirskrifar grunnslóð pallsins. Sjálfgefið er hún leidd af src scriptsins, sem dugar í nær öllum tilvikum.

Það er hvorki data-mode eigindi né ?mode= í slóðinni. Stillingin ræðst á þjóninum af uppsetningu viðskiptavinarins.

Hleðslustillingarnar þrjár

Sama script-tagið birtir þrjár ólíkar útfærslur. Hvaða útfærsla birtist ræðst af stillingu viðskiptavinarins á þjóninum, ekki af síðunni þinni.

Spjallgluggi

widget

Klassíska talblaðran neðst í horninu. Keyrir beint í síðunni þinni með Shadow DOM, ekki í ramma. Þessi stilling krefst mest af CSP-reglunni þinni, því allt sem spjallið notar keyrir í samhengi síðunnar þinnar.

Hliðargluggi

sidebar

Rammi sem festist við vinstri eða hægri brún vafrans og ýtir efni síðunnar til hliðar þegar hann opnast. Allt innihaldið er einangrað í rammanum á léni pallsins.

Innfellt spjall

embed

Rammi inni í reit sem þú útvegar, sjálfgefið `#annasvarar-embed`, minnst 220x400 px. Fyllir reitinn. Eins og hliðarglugginn er allt einangrað í rammanum.

Af því að stillingin ræðst á þjóninum skaltu staðfesta hana með Önnu-stjórnanda áður en þú byggir CSP-regluna: hún ákveður hvaða reglur þú þarft.

Leyfð lén

Áður en spjallið hleðst á síðunni þinni þarf lénið þitt að vera á lista yfir leyfð lén viðskiptavinarins. Það stýrir því hvaða síður mega sækja stillingar viðskiptavinarins og ramma spjallið. Bættu léninu við í stjórnborðinu (Stillingar, leyfð lén) eða láttu Önnu-stjórnanda gera það. Undirlén má leyfa með *.example.is.

Staðbundin prófun

Til að prófa á eigin tölvu áður en DNS bendir á réttan stað skaltu bæta localhost við leyfðu lénin. Samanburðurinn horfir aðeins á hýsilnafnið og sleppir gáttinni, svo ein localhost færsla dugar fyrir allar gáttir (3000, 5173 og aðrar). Gott er að fjarlægja hana fyrir opnun.

CSP-reglur eftir stillingu

Ef síðan þín keyrir Content-Security-Policy ráðast reglurnar sem Anna þarf af hleðslustillingunni, og munurinn er töluverður. Síður án CSP þurfa ekkert af þessu.

Ekki rugla saman tveimur reglum. frame-ancestors situr á svari pallsins fyrir /sidebar/<slug> og stýrir því hver má ramma spjallið; pallurinn setur hana sjálfur út frá leyfðu lénunum og þú bætir engu við hjá þér. Það sem hér fylgir er þín eigin CSP: það sem regla síðunnar þinnar þarf að leyfa svo loaderinn (og í spjallglugga-stillingu allt sem hann setur inn) sé ekki hindraður.

Allar stillingar: loaderinn sjálfur

Loaderinn er sóttur sem script og sækir stillingar yfir netið. Þessar tvær reglur eru alltaf nauðsynlegar.

CSP
script-src  https://widget.corveria.com;
connect-src https://widget.corveria.com;

Hliðargluggi og innfellt spjall: leyfðu rammann

Til viðbótar þarf að leyfa rammann sem birtir spjallið. Það er öll viðbótin: Turnstile, letur, Supabase-tengingin og Sentry keyra öll inni í ramma pallsins og heyra undir CSP pallsins, ekki þína.

CSP
frame-src https://widget.corveria.com;

Ekki er hægt að gefa frame-src nonce. Nonce og strict-dynamic ná aðeins til <script> og <style>, ekki ramma, svo hliðargluggi og innfellt spjall þurfa alltaf frame-src með léni pallsins. Algeng ströng sjálfgefin stilling er frame-src 'none', sem lætur takkann birtast og stillingasóknina heppnast en opnar aldrei gluggann. Loaderinn nefnir þetta núna í console.

Spjallgluggi í síðu: leyfðu allt sem hann snertir

Í spjallglugga-stillingu setur loaderinn `anna-widget.js` beint inn í síðuna þína, svo Turnstile, Google Fonts, Supabase-tengingin og Sentry keyra öll í CSP-samhengi síðunnar þinnar. Þú þarft að leyfa þau öll:

CSP
script-src  https://challenges.cloudflare.com;
frame-src   https://challenges.cloudflare.com;
style-src   https://fonts.googleapis.com 'unsafe-inline';
font-src    https://fonts.gstatic.com;
connect-src wss://<your-supabase-ref>.supabase.co <your-sentry-ingest-host>;
  • challenges.cloudflare.com: Cloudflare Turnstile (varnir gegn sjálfvirkri umferð) hleður script og sýnir ramma, því bæði script-src og frame-src.
  • fonts.googleapis.com og fonts.gstatic.com: Google Fonts stílblað og leturskrár. 'unsafe-inline' í style-src nær yfir innsettu stílana.
  • wss://<þitt-supabase-ref>.supabase.co: Supabase rauntímatengingin. Fylltu inn ref-ið úr þínum eigin NEXT_PUBLIC_SUPABASE_URL.
  • <þitt-sentry-lén>: Sentry-endapunkturinn, leiddur af NEXT_PUBLIC_SENTRY_DSN. Slepptu ef þú keyrir ekki Sentry.

Bæði gildin hér að ofan eru sértæk fyrir uppsetninguna þína. Lestu þau úr þínum eigin NEXT_PUBLIC_SUPABASE_URL og NEXT_PUBLIC_SENTRY_DSN frekar en að afrita fast gildi.

Ráðlegging

Síður með stranga CSP ættu að velja hliðarglugga eða innfellt spjall. Þær loka Turnstile, letrinu, Supabase-tengingunni og Sentry inni í ramma pallsins, svo reglan þín bætir aðeins við script-src (eða nonce), connect-src og frame-src fyrir lén pallsins. Spjallglugga-stillingin ýtir öllu þessu utanaðkomandi efni inn í CSP síðunnar þinnar. Stillingin ræðst á þjóninum, svo samræmdu valið við Önnu-stjórnanda þegar viðskiptavinurinn er settur upp.

Nonce og strict-dynamic (Next.js)

Hér festast flestar CSP-uppsetningar. Hráa `<script async>` loader-tagið er einmitt formið sem ber ekki nonce, og undir nonce-CSP keyrir script án nonce einfaldlega ekki. Það birtast engin villuboð sem vafrinn tengir við Önnu, spjallið birtist bara aldrei.

  1. 1.Undir strict-dynamic er host-listinn í script-src hunsaður. Aðeins skript sem nonce eða hash treystir fá að keyra. Því gerir script-src https://widget.corveria.com ekkert fyrir þig; loaderinn verður að bera nonce til að keyra yfirleitt. Um leið og hann gerir það lætur strict-dynamic traustið berast áfram til anna-widget.js sem loaderinn setur inn.

  2. 2.Loaderinn ber nonce sitt áfram. Við keyrslu les hann document.currentScript.nonce og setur það á scriptið (spjallgluggi) og stílinn (hliðargluggi) sem hann setur inn. Á hreinni nonce-CSP án strict-dynamic eru þessar innsetningar samþykktar með nonce-inu sem loaderinn ber áfram, svo þú þarft hvorki script-src <lén> né style-src 'unsafe-inline' fyrir innsetningar loadersins.

CSP
# All modes: nonce the loader so it runs under strict-dynamic.
script-src  'nonce-<per-request>' 'strict-dynamic';
connect-src https://widget.corveria.com;

# Sidebar / embed: add the frame (never nonce-able).
frame-src https://widget.corveria.com;

Nonce hjálpar ekki rammanum. frame-src hefur ekkert nonce, svo hliðargluggi og innfellt spjall þurfa alltaf frame-src <lén> óháð nonce. Það nær heldur ekki yfir rauntíma-stíla anna-widget.js í spjallglugga-stillingu, sem er ástæðan fyrir því að sú stilling vill enn 'unsafe-inline' stíla.

Uppsetning eftir umgjörð

Nonce er ósýnilegt í hreinu HTML en gegnir lykilhlutverki í Next.js nonce-CSP. Hvaðan <script> tagið kemur ræður því hvort það ber nonce.

Uppsetning eftir umgjörð
UmgjörðHvernig loaderinn er setturBer nonce?Athugasemdir
Hreint HTMLTagið sett beint í HTML síðunnarÁ ekki viðVirkar strax. Host-færslur aðeins ef þú keyrir CSP án nonce.
Next.js (nonce / strict-dynamic)next/script með nonce beiðninnarJá, borið áframRétta leiðin. Hrátt script async tag í nonce-CSP síðu ber ekki nonce og verður hindrað. Algengasta bilunin.
Vite / SPA með nonce-CSPSett inn við keyrslu, nonce sett handvirktJá, ef nonce er sett áður en tagið er sett innVite hefur enga innbyggða nonce-lögn; þú útvegar nonce þaðan sem þjónninn birtir það.
Hvaða umgjörð sem er, host-listi (ekkert nonce)Hráa script async tagiðÁ ekki viðNotaðu host-listareglurnar úr CSP-kaflanum orðrétt.

Next.js: next/script með nonce

app/layout.tsx
import Script from "next/script";

<Script
  src="https://widget.corveria.com/v1/loader.js"
  data-client="your-client-slug"
  nonce={nonce}
  strategy="afterInteractive"
/>

Vite / SPA: innsetning við keyrslu

JavaScript
const s = document.createElement("script");
s.src = "https://widget.corveria.com/v1/loader.js";
s.async = true;
s.dataset.client = "your-client-slug";
s.nonce = window.__CSP_NONCE__;
document.head.appendChild(s);

Villuboð sem segja þér hvað vantar

Af því að loaderinn keyrir inni í skjalinu þínu sér hann securitypolicyviolation atburði CSP-reglunnar þinnar. Þegar hindruð slóð tilheyrir léni pallsins skrifar hann gagnleg villuboð í console og nefnir nákvæmlega regluna sem vantar. Til dæmis:

console
Anna: your site's Content-Security-Policy blocked
https://widget.corveria.com/sidebar/acme (frame-src).
Add to your CSP: frame-src https://widget.corveria.com.
See Anna's widget CSP integration guide for the full per-mode list.

Boðin ná yfir frame-src, script-src, style-src, connect-src, font-src og img-src, og hver regla er nefnd einu sinni. Þau geta ekki tilkynnt hindrun á loader.js sjálfum: ef CSP-reglan þín hindrar loaderinn keyrir þessi kóði aldrei og þú sérð eigin villulínu vafrans fyrir slóð loaderins. Það þýðir að loader-scriptið er ekki með nonce eða á host-lista.

Algeng vandamál

Þarftu aðstoð við uppsetningu?

Ef þú ert að setja upp spjallþjónustu Önnu undir strangri CSP og eitthvað hindrar spjallið skaltu hafa samband. Segðu okkur umgjörðina þína og stillinguna, þá sendum við nákvæmu reglurnar.

Hafa samband